Windows で Claude Code を使うと、たまに起きる不思議な失敗
Windows マシンで Claude Code を触っていて、こんな場面に遭遇したことはないでしょうか。
ファイルを開く・検索する・簡単なスクリプトを走らせるといった作業は普通に動くのに、あるタイミングでパスが壊れたり、Git コマンドがクオートの解釈で失敗したり、改行コードがらみで挙動が読めなくなります。それらを Claude Code 側から見ると、「Bash でこう書いた → エラー → 別の書き方を試す」を往復し始めて、出力がだんだん冗長になっていきます。
このタイプの不調の原因の多くは、Windows 上の Bash(Git Bash・MSYS2・WSL 風のラッパーなど)と、Claude Code が想定しているシェルの振る舞いが微妙にずれているところにあります。ここで役に立つのが CLAUDE_CODE_USE_POWERSHELL_TOOL=1 という環境変数です。これをセットした状態で Claude Code を起動すると、シェル経由のコマンドを PowerShell 側に直接渡すようになります。
この記事は、私がこの切り替えを業務で使ってみて得た、Windows ユーザーにとっての判断材料をまとめたものです。公式の機能説明を翻訳し直すのではなく、「いつ使うべきか」「使うと何が変わるか」「残る落とし穴は何か」という実務目線の話を中心に書きます。
そもそもこの環境変数は何をしているのか
Claude Code は内部で複数の「ツール」を切り替えながらコマンドを実行します。そのなかでシェル実行を担うのが Bash 系のツールです。既定では、POSIX シェル互換の挙動を前提にした実装になっていて、Linux や macOS ではそのまま素直に動きます。
Windows の場合、Claude Code を Git Bash などの POSIX エミュレーション上で動かすケースが多く、そこでは「パスのスラッシュが混ざる」「クオートの解釈が二重になる」「cmd と PowerShell のどちらが最終的に呼ばれるか環境で変わる」といったズレが発生しやすくなります。
CLAUDE_CODE_USE_POWERSHELL_TOOL=1 を立てると、シェル実行の経路を変更し、PowerShell を直接叩くようになります。PowerShell は Windows 11 にも標準で入っており、Windows 側のパスやユーザープロファイル、環境変数を最初から前提として動きます。結果として、Windows ならではの噛み合わなさがだいぶ減ります。
こういうときに効く
使って一番わかりやすく効くのは、以下のような場面です。
長いパスやスペースを含むパスを扱うとき
Windows は C:\Users\<名前>\OneDrive\Documents のような、スペースや日本語を含むパスが当たり前です。Git Bash 経由でここを渡すと、クオートを何重に書けばいいかで毎回つまずきます。PowerShell 直接実行だと、Windows 側のパス表記をそのまま渡せるので、このストレスがほとんど消えます。
ネットワーク関連・プロキシ越しのコマンド
企業 PC では HTTP プロキシや証明書周りの設定が Windows の資格情報マネージャーに寄っていることが多く、Bash 経由だと証明書の参照位置が合わずに SSL certificate problem のようなエラーが出ます。PowerShell 側だと Windows の証明書ストアをそのまま見にいくため、追加設定なしで通ることがあります。
PowerShell でしか使えない cmdlet を呼びたいとき
Get-Process、Get-Service、Get-AppxPackage のような cmdlet は PowerShell 固有のものです。Bash からは呼べませんが、PowerShell 経由なら自然に書けます。Windows 環境の診断を Claude Code 越しに行うときに便利です。
切り替えたときに注意すること
逆に、切り替えることで「従来の Bash 書きの慣習」がそのままでは使えなくなる部分もあります。
POSIX のパイプやリダイレクトの書き方
command1 | command2 のようなパイプは PowerShell でも動きますが、PowerShell のパイプはテキストではなく「オブジェクト」を流す設計です。grep の代わりに Select-String、awk の代わりに ForEach-Object のように、置き換えが必要になります。Claude Code は多くの場合この変換を自動で調整してくれますが、既存のシェルスクリプトをそのまま貼り付けるような使い方は相性が悪くなります。
実行ポリシー(Execution Policy)
PowerShell にはスクリプト実行を制限するポリシー設定があります。業務 PC で Restricted が適用されていると、Claude Code から .ps1 ファイルを走らせようとしたときに拒否されます。この場合、管理者権限で Set-ExecutionPolicy RemoteSigned -Scope CurrentUser を一度実行して、ユーザー単位で緩める必要があります。
クオート挙動の差
POSIX シェルと PowerShell はクオートの扱いが微妙に違います。とくに二重引用符の中での $ の展開ルールや、シングルクオートの扱いが違います。Claude Code が生成したコマンドの挙動を「確認せずに流す」運用をしていた人ほど、この差にハマりやすくなります。まずは短いコマンドで動作を見てから、長い処理に入るのが安全です。
切り替え方と解除の仕方
設定はシンプルです。新しいシェルを起動する前に環境変数を立てるだけで、Claude Code の次回起動から有効になります。
# PowerShell の場合（現在のセッションだけ）
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
claude
# 永続化したい場合（ユーザー環境変数に保存）
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_USE_POWERSHELL_TOOL", "1", "User")Git Bash 側で起動している場合は、.bashrc に export 行を足しておくと、Bash から claude を起動したときにも伝播します。
# ~/.bashrc
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1止めたくなったら、値を空に戻すか、ユーザー環境変数を削除します。
# 現在のセッションだけ
Remove-Item Env:CLAUDE_CODE_USE_POWERSHELL_TOOL
# ユーザー環境変数から削除
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_USE_POWERSHELL_TOOL", $null, "User")切り替えるかどうかの判断基準
ここまでを踏まえて、切り替えるかどうかの判断を迷う場面もあるはずです。私の経験則としては、次の条件のどれかに当てはまるなら試す価値があります。
一つ目は、Windows でしか作業しない日が多いこと。Git Bash と PowerShell の二段構えの複雑さを避けられるだけでも十分に価値があります。二つ目は、企業 PC で証明書・プロキシ・資格情報周りの制約が厳しいこと。三つ目は、扱うコードベースの多くが Windows 前提(.NET、PowerShell スクリプト、Windows API 利用など)であること。
逆に、普段から WSL の中で作業していて Claude Code も WSL 側で動いている人は、切り替えの恩恵がほぼありません。WSL はすでに Linux そのものなので、POSIX シェル互換の振る舞いで問題が起きにくいからです。
残る Windows 固有の詰まりどころ
環境変数を切り替えても、Windows ならではのトラブルがすべて消えるわけではありません。覚えておきたい残りのポイントをいくつかメモしておきます。
パスの長さ制限
Windows には既定で 260 文字のパス長制限があります。npm や Yarn のプロジェクトで node_modules が深くネストすると、この制限に引っかかります。Group Policy や LongPathsEnabled レジストリで解除できますが、Claude Code が関わる問題というより Windows 全体の話です。
改行コード
Git を Windows で使うと、core.autocrlf の設定によってチェックアウト時に改行が勝手に変換されます。これは Claude Code が関与する前の問題ですが、.gitattributes を設定していない状態で、生成されたコマンドの挙動が予想外に見えることがあります。新しいリポジトリでは .gitattributes に * text=auto eol=lf のような基本行を入れておくと、この手の混乱を未然に防げます。
管理者権限が必要なコマンド
netsh、sfc、Stop-Service のような管理者権限が必要な操作は、Claude Code からはそのままでは走りません。Claude Code 自体を管理者権限で起動している必要があります。権限昇格のプロンプトが常に必要な業務 PC だと、このあたりは手動操作の出番になります。
切り替え後のふるまいを確認する簡単な方法
CLAUDE_CODE_USE_POWERSHELL_TOOL=1 を立てたあと、実際に PowerShell が使われているかを確認したくなります。簡単な確認としては、以下のような Windows 固有コマンドを Claude Code に実行させてみることです。
$PSVersionTable
Get-Location
[System.Environment]::OSVersionこれらが素直に結果を返すようになっていれば、切り替えが効いています。Bash 経由のままだと「command not found」相当のエラーになることが多いので、違いが分かりやすいはずです。
Windows で Claude Code を使っていて「なんとなく噛み合わない」感覚がある人は、一度この環境変数を立ててみる価値があります。合わなければ戻せばいいだけなので、失う時間もわずかです。私自身、Windows と macOS を行き来する開発環境では、Windows マシンだけ常時この設定を有効にしています。環境ごとに最適な構成は違うものの、それを明示的に選べるようにしておくこと自体が、長期的にはコード生成の品質を一段階引き上げてくれます。