Windows 環境で Codex の文字化け事故を減らすベストプラクティス - 環境整備より『こう指示する』を先に決める

Windows で Codex に日本語を含むファイルを扱わせるとき、最初に効くのはエディタや shell の設定を全部そろえることよりも、Codex に「どう読んで、どう書いて、どこで止まるか」を明示することです。

特に困りやすいのは、次のような場面です。

• UTF-8、CP932、UTF-16 系のファイルが混在している
• 見た目は読めているように見えるが、実バイトの解釈がずれている
• 既存ファイルを少し直しただけのつもりが、保存時に別 encoding で再保存してしまう
• CSV、TXT、ログ、Markdown、設定ファイルのような「コード以外」で壊れる
• 一時スクリプトや shell 出力をそのまま保存して事故が固定化する

OpenAI の Codex は、単発のチャット相手というより、設定と作業ルールを与えて継続的に使うチームメイトに近い形で扱うほうが安定しやすいです。特に AGENTS.md を読ませる運用があるなら、文字コードに関するルールは毎回口頭で繰り返すより、常設したほうが効きます。

この記事では、Windows で Codex に日本語ファイルを安全に扱わせるために、最初に与えると効きやすい指示を、実務向けに整理します。

目次

1. 1. まず結論
2. 2. なぜ Windows で文字化け事故が起きやすいのか
3. 3. 最初に Codex へ固定したいルール
   • 3.1 読む前に、encoding 候補と BOM と改行を確認させる
   • 3.2 文字化けが疑わしいファイルは、推測のまま保存させない
   • 3.3 既存ファイルは維持し、新規ファイルだけ UTF-8 を基本にする
   • 3.4 曖昧な書き込み経路をデフォルトで使わせない
   • 3.5 保存後は再読込して、日本語の代表行を確認させる
   • 3.6 異常兆候が出たら、修正より先に報告させる
4. 4. 短い指示文として渡すなら
5. 5. AGENTS.md に常設したいテンプレート
6. 6. NG 指示と OK 指示
7. 7. レビュー時のチェックリスト
8. 8. まとめ
9. 9. 参考資料

1. まず結論

Windows 環境で Codex の文字化け事故を減らすうえで一番効きやすいのは、文字コードの作業手順を先に固定することです。

特に効くのは、だいたい次のルールです。

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

実務での短い言い方にすると、ほぼこれです。

• 読む前に確認
• 怪しければ保存禁止
• 既存は維持、新規だけ UTF-8
• 曖昧な書き込み経路を禁止
• 最後に再読込して確認

逆に危ない指示は次です。

• 「文字化けを直して」
• 「全部 UTF-8 にして」
• 「CSV を出して」
• 「適当に合わせて」
• 「とりあえず保存して見て」

これらはどれも、Codex がどの段階で止まるべきか が書かれていません。文字化け対策では、何をするかだけでなく、どこで保存を止めるか まで指示する必要があります。

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

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

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

• 新しめのソースや Markdown は UTF-8
• 古い CSV、TXT、ログ、設定は CP932 系
• 一部の出力やツール生成物は UTF-16 系
• エディタ、shell、Excel 由来の出力で保存経路がばらばら
• 改行コードも LF と CRLF が混在

この状態で Codex が 1 回でも間違った解釈をすると、読めていない文字列を「読めているもの」として次の編集へ進む ことがあります。そしてそのまま保存すると、今度は表示上の問題ではなく、ファイル自体の破損 として固定されます。

だから文字化け対策は「日本語をうまく扱えるか」ではなく、I/O 手順をどう管理するか の話です。

3. 最初に Codex へ固定したいルール

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

最初のルールはこれです。

日本語を含む既存ファイルを読む前に、現在の encoding 候補、BOM 有無、改行コードを確認し、怪しければそのまま内容解釈に進まないこと。

ポイントは、「テキストを読む前に、まずファイルの前提を見る」 に変えることです。

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

これは特に重要です。

文字化けが疑われるときは、調査段階では read-only とし、解釈に自信が持てるまで上書き禁止にする。

人間でも同じですが、読めていないファイルを保存してはいけません。少し壊れて見えるけれどたぶんこれだろう、で保存すると、それが事故の確定版になります。

3.3 既存ファイルは維持し、新規ファイルだけ UTF-8 を基本にする

文字化け対策の文脈で、意外と危ないのが「全部 UTF-8 に統一して」です。

最終的に repo 全体を UTF-8 に寄せる判断はありえますが、それは 別タスク として差分と影響範囲を見ながらやるほうが安全です。日常の改修では、次の運用が安定します。

• 既存ファイルを編集するときは、元の encoding を維持する
• 新規ファイルを追加するときは、repo 規約に従って UTF-8 系で作る
• 既存ファイルの変換が必要なら、通常の機能修正と分ける

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

Windows で事故を増やしやすいのは、「ちょっとした出力だから shell で雑に書く」です。

• リダイレクトでそのまま吐く
• 便利コマンドでそのまま保存する
• 一時生成物をそのまま本番ファイルへ昇格する

こうした経路は、encoding が明示されていない ことが多く、事故の温床になります。だから Codex には、書き込み手段の選び方も固定しておくのが安全です。

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

「保存できた」と「壊れていない」は同じではありません。

大事なのは、保存後に代表的な日本語行をもう一度読み、次を見せることです。

• 置換文字 U+FFFD が入っていないか
• ? が不自然に増えていないか
• BOM や改行だけの巨大差分になっていないか
• 業務上変えていない日本語がそのまま残っているか

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

文字コード事故では、無理に直させるより、止めて報告させる ほうが被害を小さくできます。

たとえば次が出たら、いったん異常扱いにしたほうが安全です。

• U+FFFD の増加
• ? の増加
• 想定外の BOM 変化
• 改行だけの大量差分
• 日本語行だけが不自然に大きく変わる

4. 短い指示文として渡すなら

毎回のタスクに添える短い版なら、次くらいで十分に効きます。

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

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

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

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

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

5. AGENTS.md に常設したいテンプレート

同じ注意を何度も言うくらいなら、AGENTS.md に入れたほうがよいです。以下は、Windows で日本語ファイルを扱う repo 向けの、実用寄りのテンプレートです。

# Text Encoding Rules

## Scope
This repository may contain Japanese text and mixed legacy encodings.
Avoid mojibake and accidental re-encoding above all else.

## Mandatory Rules
- Before reading or editing an existing text file that may contain Japanese, first determine:
  - likely encoding
  - BOM presence
  - newline style
- If mojibake is suspected, do not save the file until the encoding interpretation is credible.
- Preserve the original encoding, BOM, and newline style for existing files.
- Treat "convert to UTF-8" as a separate, explicit task.
- New files should follow repository convention. If there is no clear rule, prefer UTF-8 and state whether BOM is used.
- Do not use ambiguous write paths by default, such as shell redirection or convenience commands without explicit encoding control.
- After writing, reopen the file and verify representative Japanese lines.
- If any of the following appears, stop and report:
  - replacement characters
  - unexpected `?`
  - unintended BOM change
  - unintended newline conversion
  - whole-file diffs without a business reason

## Reporting Format
For each changed text file, report:
- path
- detected or preserved encoding
- BOM presence
- newline style
- how verification was performed
- whether representative Japanese text remained intact

このテンプレートのよいところは、どう編集するか ではなく、どう壊さないか まで固定できることです。特に、

• If mojibake is suspected, do not save ...
• Treat "convert to UTF-8" as a separate, explicit task.

の 2 行は、かなり効きます。

6. NG 指示と OK 指示

文字化け対策では、指示の粒度が結果をかなり左右します。

ポイントは、手を動かす前の確認 と 保存後の検証 を必ず書くことです。

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

Codex に作業させたあと、人間側で見るチェックポイントも固定しておくとさらに安定します。

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

文字化け対策で大事なのは、成功した差分を増やすことより、怪しい差分を早く止めること です。

8. まとめ

Windows 環境で Codex に日本語ファイルを扱わせるとき、最初に効くのは PC 側を完璧にそろえることよりも、Codex に文字コードの作業手順を明示することです。

特に覚えておきたいのは次の 5 点です。

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

そして、毎回言うくらいなら AGENTS.md に入れる。これが一番実務的です。

文字化け対策は、「日本語をちゃんと扱って」と頼む話ではありません。保存してよい条件と、止まるべき条件を明文化する話 です。そこまで書けば、Windows でも Codex はかなり扱いやすくなります。

9. 参考資料

• OpenAI Codex docs, Best practices
• OpenAI Codex docs, Custom instructions with AGENTS.md
• OpenAI Codex docs, Windows