🔤

文字化けした状態で .md を読ませないために苦労した話

に公開
AI
個人開発
Windows
Claude
Claude Code
idea

Claude Code 、codex を使っていると、こんな表示を見かけることがあります。

AI返信

これ、気になりませんか？

読み直してくれるのはありがたいですが、一度文字化けした状態で読んでしまっているということは、そのゴミデータがコンテキストに残ったまま再読み込みが走っています。トークンが二重に消費されていますし、そもそも「なぜ文字化けしたのか」の原因が解決されていません。

前回の記事で「ai-common.md にルールを書いておけば楽になる」と紹介しました。

その ai-common.md 自体が文字化けしていて読めていなかった、というオチから始まる話です。

何が起きていたか

前回の記事で紹介した構成はこういうものでした。

  • docs/ai-common.md に「PowerShell でファイルを読むときは -Encoding UTF8 をつける」などのルールを書く
  • AIが毎回参照することで、同じ指示を繰り返さなくて済む

ところが実際には、そのルールが書かれた ai-common.md 自体が文字化けした状態で読まれていました。ルールが入っているファイルが読めていなかった、というオチです。
オチ

最初に試した対策：最初に差し込まれるファイルを英文で書く

セッション開始時に最初に読まれるファイルが日本語だと文字化けするなら、英文で書けば防げると考えました。

グローバルの CLAUDE.md（Claude Code が起動時に自動で読み込む設定ファイル）を英文で書き直してみました。

Codex はこれで問題なく動きました。Claude はというと、別の経路で読み込んでいたドキュメントが引き続き文字化けしていました。

根本的な対策：文字化けしない読み方をグローバル指示文に書く

Claude Code には Read ツールというファイルを直接読み込む仕組みがあります。PowerShell 経由ではなく直接読むので、Windows のコンソールエンコーディング（CP932）の影響を受けません。

グローバルの CLAUDE.md に以下を追加しました。

- To read .md / .txt / .json files, always use the Read tool directly.
  Do not use PowerShell or Bash to read these files.
  PowerShell's console output encoding is CP932 on Windows,
  which garbles Japanese characters even with -Encoding UTF8.

これで Claude が .md ファイルを読むときに Read ツールを使うようになり、文字化けが起きなくなりました。

Codex 向けには引き続き -Encoding UTF8 の指示を残してあります。

なぜ文字化けが起きるのか

Windows 日本語環境では、PowerShell のコンソール出力エンコーディングがデフォルトで CP932（Shift-JIS）になっています。

ファイル自体は VS Code で UTF-8 として正しく保存されています。問題はファイルの中身ではなく、PowerShell がその内容をコンソールに出力するときに CP932 で変換してしまうことです。

ファイル（UTF-8）✓ → PowerShell が読む ✓ → コンソール出力（CP932）✗ → AI が受け取る ✗

-Encoding UTF8 を指定するだけでは読み取り側の話しか解決しておらず、出力側の CP932 問題は残ります。

Mac や Linux はターミナルのデフォルトが UTF-8 なので、この問題は起きません。

文字化けしたまま読ませるとトークンが二重に無駄になる

文字化けした状態でファイルを読むと：

  1. 文字化けした内容がコンテキストに入る（トークン消費）
  2. 文字化けを検出して読み直す
  3. 正常な内容もコンテキストに入る（さらにトークン消費）

文字化けした内容はコンテキストから消えないので、ゴミデータと正常データが両方残ります。セッション開始時に複数のドキュメントを読ませている場合、その分だけ掛け算になります。

前回の記事で「コンテキストの無駄遣い」の話を書いたのに、自分のセットアップでそれが起きていたというオチです。

現状と残っている不安

今のところ Read ツールの指示で文字化けは起きていません。

ただ、Claude の動きが常に一貫するかは正直なところよくわかっていません。セッションが長くなってくると、指示の参照が薄れて Bash 経由で読んでしまうケースがまた起きるかもしれません。

いっそのこと docs/ 配下のファイルも全部英文に変えてしまうべきか、という迷いは現在進行形です。

まとめ

  • Windows 環境では PowerShell のコンソール出力が CP932 のため、UTF-8 の日本語ファイルが文字化けする
  • -Encoding UTF8 だけでは不十分で、出力側の問題が残る
  • Claude Code では Read ツールを使えばこの問題を回避できる
  • グローバルの CLAUDE.md に明示することで安定する（はず）
  • 根本的に解決したかは、まだ様子見中
GitHubで編集を提案

Discussion