Windows + PowerShell 5.1 で Claude Code を実運用して踏んだ落とし穴と対策

• URL: https://zenn.dev/equaliainc/articles/claude-code-windows-powershell-tips
• 日付: 2026-06-21
• Tier: Tier 3
• 要旨: Windows 11 + PowerShell 5.1 環境で Claude Code を実運用して踏んだ落とし穴。&&/|| が使えない・2>&1 でネイティブ exe の stderr が誤った失敗判定・Out-File のデフォルトが UTF-16 BOM・bash コマンドが動かない。CLAUDE.md に「標準は PowerShell、POSIX が必要なときだけ bash」と記載することで、エージェントが同じハマりを繰り返さない。

詳細

PowerShell 5.1 は PowerShell 7 以降の機能が使えない環境下での実装。bash の && / || は構文エラー。代わりに if ($?) { } で成功判定。ネイティブ exe（git など）への 2>&1 は stderr を NativeCommandError に包んで、終了コード 0 でも $? が $false になることがあり、git の進捗出力で何度も引っかかる。素直に実行（stderr そのまま）で対処。Out-File / Set-Content のデフォルトエンコーディングは UTF-16 LE（BOM 付き）で、他ツールが読む JSON・.md が壊れる。-Encoding utf8 を明示必須。bash 由来コマンド（head・tail・which・touch・2>/dev/null）は対応表で読み替え（Get-Content の TotalCount/Tail、Get-Command の Source、New-Item、2>$null など）。ヒアドキュメント @’…’@ の閉じ @ は行頭必須。「プロジェクト指示ファイル（CLAUDE.md・AGENTS.md）に最初から書いておく」のが最も効果的。エージェントはセッション開始時に指示ファイルを読むため、同じハマりを繰り返さない。