WindowsでClaude Codeを使うと、日本語で3回つまずく——実際に踏んだ順に書く

WindowsでClaude Codeを使い始めると、たいてい同じ場所でつまずきます。しかもそのほとんどが 日本語がらみです。文字化け、パス、改行コード。

この記事は入門記事の写しではありません。この環境で実際に出たエラーだけを、踏んだ順に書きます。 ゲームを11本とブログを十数本、全部Windowsで作ってきて、繰り返し当たった場所です。

1. Pythonの出力が文字化けして落ちる（いちばん最初に当たる）

Claude Codeにスクリプトを書かせて実行すると、こういうエラーで止まります。

UnicodeEncodeError: 'cp932' codec can't encode character '\u274c'

原因はWindowsの標準の文字コードがcp932（Shift_JIS系）だからです。 UTF-8で書かれた絵文字や一部の記号が、そのままでは出力できません。

厄介なのは、処理そのものは成功しているのに、結果を表示する最後の1行で落ちることです。 実際、記事を公開するスクリプトが「品質チェックは通ったのに、結果を出力するprintで落ちる」という 形で止まったことがあります。原因が分かるまで、処理が失敗したのだと勘違いしました。

対処はどちらかです。

• 実行するときに環境変数を渡す：PYTHONIOENCODING=utf-8 python script.py
• スクリプトの先頭で自分で差し替える：
  sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')

前者が手軽ですが、AIに書かせるスクリプトが増えるほど、後者を最初から入れておくほうが楽です。 毎回思い出さなくて済みます。

2. 日本語のパスが、シェルによって壊れる

作業フォルダの名前に日本語が入っていると、ここで詰まります。

Claude Codeでは、PowerShellとbash（Git Bash）のどちらでもコマンドを実行できます。ところが 同じパスの書き方が、両方では通りません。

	PowerShell	bash（Git Bash）
区切り	D:\共有フォルダ\_Tools	D:/共有フォルダ/_Tools
環境変数	$env:NAME	$NAME
スラッシュ始まりの文字列	そのまま渡る	勝手にパスとして変換される

最後の行がとくに厄介です。bashに /api/items のような文字列を渡すと、 MSYSのパス変換が働いて C:/Program Files/Git/api/items のような まったく別の文字列に化けます。APIを叩くときに何度かこれで詰まりました。

使い分けの目安はこうです。

• PowerShell：Windowsのツールを呼ぶとき、スラッシュ始まりの引数を渡すとき、クリップボードを触るとき
• bash：gitやテキスト処理など、UNIX系のコマンドを使うとき
• 迷ったら、パスは必ず絶対パスで、引用符で囲む

3. 改行コードが勝手に変わって、差分が真っ赤になる

gitを使っていると、こういう警告が延々と出ます。

warning: LF will be replaced by CRLF in index.html

Windowsの改行はCRLF、多くのツールが吐くのはLF。gitがその間で変換してくれているのですが、 結果として1文字も内容を変えていないのに、diffが「全行変わった」ように見えることがあります。

これは実際に、AIに文章を直させたときに起きました。中身は1段落しか変えていないのに、 差分を見ると数百行が変更扱い。レビューが不可能になります。

差分を見るときは、改行を無視して比べてください。

• git diff --word-diff …… 単語単位で見る。意味のある変更だけが浮かぶ
• git diff --stat …… まず規模だけ見る
• diff --strip-trailing-cr 旧 新 …… gitの外で比べるとき

なお、.cmd や .ps1 を書くときは、中身をASCIIに保ってCRLFで保存するのが安全です。 日本語のコメントを入れたスクリプトが、実行時に文字化けして動かないことがあります。

4. 「動いているのに固まって見える」問題

これは日本語とは関係ありませんが、Windows特有なので書いておきます。

PowerShellで外部コマンドの出力を Out-String などでいったん受けると、 出力がバッファされて、最後まで何も表示されません。実際には動いているのに、固まったように見えます。

長い処理を走らせるときは、出力をそのまま流すのが基本です。あわせて、 必ずタイムアウトを付けることをおすすめします。応答しなくなったときに、 自分で止められる状態にしておかないと、待つしかなくなります。

5. これらをAIに毎回説明しなくて済むようにする

ここまでの話は、全部プロジェクトの設定ファイルに書いておけます。

Claude Codeは、作業フォルダに置いた CLAUDE.md を起動時に読みます。そこに 「この環境ではこうする」を書いておけば、毎回説明しなくても、その前提で動くようになります。

実際に書いてあるのは、たとえばこういうことです。

• 共有フォルダの場所（Windowsならこのパス、Macならこのパス）
• PowerShellとbashのどちらを使うかの目安
• .cmd / .ps1 はASCII＋CRLFで書く
• 長い処理は必ずタイムアウトを付ける

ここに書いた分だけ、同じ失敗を繰り返さなくなります。 逆に言えば、書いていないことは何度でも繰り返します。エラーで詰まったら、 直すだけでなく「次に同じ場所で止まらないための1行」を設定ファイルに足すのが、いちばん効きます。

この記事の要点

• cp932の文字化け——処理は成功しているのに最後のprintで落ちる。 PYTHONIOENCODING=utf-8 か、スクリプト先頭で標準出力を差し替える
• 日本語パス——PowerShellとbashで書き方が違う。bashはスラッシュ始まりの文字列を勝手に変換する
• 改行コード——CRLF変換でdiffが真っ赤になる。--word-diff で見る
• バッファ——出力を受け止めると固まって見える。そのまま流し、タイムアウトを付ける
• 全部 CLAUDE.md に書けば、毎回説明しなくて済む

※すべてWindows 11 ＋ Claude Code の環境で、実際に踏んだものです。 一般論として集めたものではなく、この環境で出たエラーメッセージをもとに書いています。