Windows × Codex の文字化け防止ガイド

まず結論

Windows で Codex（AIコーディングツール）に日本語ファイルを扱わせるとき、最初に効くのはエディタやシェルの設定を揃えることより、Codex に「どう読んで、どう書いて、どこで止まるか」を明示することです。

特に効くルール:

• 日本語を含む既存ファイルは、読む前に encoding 候補、BOM 有無、改行コードを確認させる
• 文字化けが疑わしいファイルは、自信が持てるまで保存させない
• 既存ファイルは元の encoding、BOM、改行を維持させる
• 新規ファイルはリポジトリ規約に従って UTF-8 系へ寄せる
• 書き込みはencoding を明示できる方法だけを使わせる
• 保存後は再読込して日本語の代表行を検証させる

なぜ Windows で文字化け事故が起きやすいのか

問題は Codex が日本語に弱いことではなく、Windows の資産側に複数の文字コードと複数の書き込み経路が共存していることです。

実務では次のような混在が珍しくありません:

• 新しいソースや Markdown は UTF-8
• 古い CSV、TXT、ログ、設定ファイルは CP932
• 一部の出力やツール生成物は UTF-16
• エディタ、シェル、Excel 由来の出力で保存経路がばらばら

この状態で Codex が1回でも間違った解釈をして保存すると、ファイル自体の破損として固定されます。

Codex に与えるべき指示ルール

1. 読む前に encoding 候補と BOM と改行を確認させる

「テキストを読む前に、まずファイルの前提を見る」に変える。

2. 文字化けが疑わしいファイルは推測のまま保存させない

読めていないファイルを保存してはいけません。調査段階では read-only とし、解釈に自信が持てるまで上書き禁止。

3. 既存ファイルは維持、新規ファイルだけ UTF-8 を基本に

「全部 UTF-8 に統一して」は危険。既存ファイルの変換は別タスクとして切り離す。

4. 曖昧な書き込み経路をデフォルトで使わせない

リダイレクトや便利コマンドでの「雑な保存」を禁止。encoding を明示できる方法だけを使う。

5. 保存後は再読込して日本語の代表行を確認させる

「保存できた」と「壊れていない」は別。U+FFFD、? の増加、BOM/改行だけの巨大差分がないか確認。

6. 異常兆候が出たら修正より先に報告させる

U+FFFD の増加、? の増加、想定外の BOM 変化、改行だけの大量差分が出たら異常扱いで止める。

短い指示文のテンプレート

この作業では文字コード事故を最優先で避けてください。

- 日本語を含む既存ファイルは、読む前に encoding 候補、BOM 有無、改行コードを確認する
- 文字化けが疑われるファイルは、推測のまま保存しない
- 既存ファイルは元の encoding / BOM / 改行を維持する
- 新規ファイルは repo 規約に従って UTF-8 系で作成する
- 書き込みは encoding を明示できる方法だけを使う
- 保存後は再読込し、日本語の代表行が壊れていないことを確認する
- U+FFFD、? の増加、BOM/改行事故、大量差分があれば異常として報告する

対象ファイルが決まっているなら、次の1行を足すと安定します:

対象ファイル: <paths> / 代表文字列: "<examples>"

代表文字列を渡すのはかなり効きます。Codex に「この日本語が壊れてはいけない」という具体的な監視点を持たせられるからです。

AGENTS.md に常設するテンプレート

同じ注意を何度も言うより、AGENTS.md に以下のようなルールを入れるのが実務的です:

• 日本語ファイルを読む前に encoding/BOM/改行を確認
• 文字化け疑い時は保存禁止
• 既存ファイルの encoding を維持
• 「UTF-8 への変換」は別タスク扱い
• 保存後は再読込して代表行を検証
• 異常（置換文字、BOM変化、大量差分）は停止して報告

NG 指示と OK 指示

レビュー時のチェックリスト

• 変更ファイルごとの encoding/BOM/改行の扱いが報告されているか
• 日本語行だけ不自然に大きく変わっていないか
• 改行だけの差分が大量に出ていないか
• U+FFFD や ? が増えていないか
• CSV やログで列崩れが起きていないか

まとめ

• 読む前に encoding/BOM/改行を確認させる
• 文字化けが疑わしければ、推測のまま保存させない
• 既存ファイルは維持し、新規だけ UTF-8 系へ寄せる
• 曖昧な書き込み経路を禁止する
• 保存後に再読込して、日本語の代表行を確認させる

文字化け対策は「日本語をちゃんと扱って」と頼む話ではありません。保存してよい条件と、止まるべき条件を明文化する話です。毎回言うくらいなら AGENTS.md に入れましょう。