はじめに
今回、Antigravity（AIエージェント開発環境）でGeminiとペアプログラミングを行いながら、PowerShell 5.1 を用いて、Slackや各種API（Webhook）と連携する自動化スクリプトを開発した際、日本語Windows特有の「文字コードの罠」による深刻なエラーや文字化けに遭遇した。
これらの致命的な地雷を回避するために明文化したプロジェクト固有の開発ルール（マニュアル）を共有したい。
プロジェクト固有開発ルール：PowerShell 5.1 / 日本語Windows環境における開発
PowerShell 5.1 および日本語 Windows 環境で動作するスクリプトを開発する際は、文字化けや構文エラーを防ぐため以下のルールを厳守すること。
1. スクリプト内での全角日本語の直接記述の禁止 (BOMなしUTF-8のパースエラー回避)
-
原因: スクリプト（
.ps1）ファイルが「BOMなしUTF-8」で保存された場合、PowerShell 5.1はマルチバイト（全角日本語）を正しく認識できず、括弧や制御記号の位置がずれてParserError（構文エラー）を引き起こします。 - 対策: スクリプト内（コード、文字列リテラル、コメント）に全角文字を直接記述しないようにします。
-
解決策: 表示やキー名に必要な日本語は、16進数の Unicode 文字コード配列（
[char]）に置き換えて動的に結合します。
2. Unicodeエスケープ時の文字列結合ルール
-
原因:
charの配列を文字列化する際、安易に[string]キャスト（例:[string]($char1, $char2)）を使用すると、PowerShellの仕様により文字の間に自動的に半角スペースが挿入されてしまいます。 -
対策: 必ず
-join ""を使用して明示的に空文字で結合します。-
正しい例:
$KEY = @([char]0x30eb, [char]0x30fc) -join ""(「ルー」となる) -
誤った例:
$KEY = [string]([char]0x30eb, [char]0x30fc)(「ル ー」のようにスペースが入る)
-
正しい例:
3. Invoke-RestMethod での日本語文字化け回避 (UTF-8送信の徹底)
-
原因: PowerShell 5.1 の
Invoke-RestMethodで JSON 文字列を-Bodyにそのまま渡すと、システムの既定エンコード（Shift-JIS / CP932）で送信されてしまい、Slack等の受信側で?に文字化けします。 -
対策: 必ず
[System.Text.Encoding]::UTF8.GetBytes($body)を介して、明示的に UTF-8 のバイト配列に変換してから送信します。 - 実装例:
$bodyBytes = [System.Text.Encoding]::UTF8.GetBytes($body)
$response = Invoke-RestMethod -Uri $webhookUrl -Method Post -Body $bodyBytes -Headers @{"Content-Type" = "application/json; charset=utf-8"}
終わりに
このルールを導入してからは、エラーに悩まされずWebhook連携や自動化スクリプトが動くようになった。
評判の良いClaude Codeを使用していれば陥らない罠かもしれないが、誰かの役に立てればと思い、公開する。
同じ罠にハマって苦労しているかたの助けになれば幸いです。