更新履歴(3件・最終更新 2026年08月02日)
この記事に加えた変更の記録です。アーカイブした更新前のバージョンは、DOI付きの固定URLから読めます。
- 記事の冒頭に「この記事の知識マップ」節を追加しました。本文で扱っている概念とその関係を、要約・図・詳細ページへのリンクにまとめたものです。本文の主張は変えていません。
- 外部レビュー(1283件)への対応として本文を更新しました。個々の変更内容は、この下の履歴を参照してください。
- 前提としているCodexと`AGENTS.md`の説明を冒頭に追加しました(ルートから作業ディレクトリへ向かって連結され、下位が強く効くこと、既定で32 KiBで打ち切られること)。先頭バイトを16進で確認する方法、BOMの判定表、改行コードの計数、PowerShellの版差による既定エンコーディングの表、用語表、日本語版のテンプレートを追加しました。
- 初版公開
この記事を引用する(DOI: 10.5281/zenodo.21589704)
この記事はZenodoにアーカイブされています。常に最新版へ解決されるDOIと、いま表示している版に固定されたDOIの両方を下に示します。
小村 豪(2026)「WindowsでCodexの文字化け事故を減らす指示ルール」合同会社小村ソフト. https://doi.org/10.5281/zenodo.21589704 https://staging.comcomponent.com/blog/2026/03/19/002-codex-windows-mojibake-prompting-best-practices/
- DOI(最新版)
- 10.5281/zenodo.21589704
- DOI(この版)
- 10.5281/zenodo.21732725
Windows で Codex に日本語を含むファイルを扱わせるとき、最初に効くのはエディタや shell の設定を全部そろえることよりも、Codex に「どう読んで、どう書いて、どこで止まるか」を明示することです。
特に困りやすいのは、次のような場面です。
- UTF-8、CP932、UTF-16 系のファイルが混在している
- 見た目は読めているように見えるが、実バイトの解釈がずれている
- 既存ファイルを少し直しただけのつもりが、保存時に別 encoding で再保存してしまう
- CSV、TXT、ログ、Markdown、設定ファイルのような「コード以外」で壊れる
- 一時スクリプトや shell 出力をそのまま保存して事故が固定化する
OpenAI の Codex は、単発のチャット相手というより、設定と作業ルールを与えて継続的に使うチームメイトに近い形で扱うほうが安定しやすいです。特に AGENTS.md を読ませる運用があるなら、文字コードに関するルールは毎回口頭で繰り返すより、常設したほうが効きます。
この記事では、Windows で Codex に日本語ファイルを安全に扱わせるために、最初に与えると効きやすい指示を、実務向けに整理します。
前提: この記事が想定している Codex と AGENTS.md
Codex を使っていない方向けに、前提だけ先に書いておきます。
Codex は、リポジトリのファイルを実際に読み書きするコーディング エージェントです。手元のターミナルで動く CLI、エディタの拡張、クラウド側で動くもの、と複数の入口がありますが、この記事が想定しているのは 手元のリポジトリのファイルを直接編集させる使い方 です。文字化け事故は「編集して保存する」ときに起きるので、どの入口かより、ファイルへの書き込み経路をどう縛るか のほうが本質になります。
AGENTS.md は、そのリポジトリで作業するときの常設指示を書いておく Markdown ファイルです。読み込まれ方には、覚えておくと効く性質があります。
- 場所は 1 か所ではありません。 ホームディレクトリの
~/.codex/AGENTS.mdのような全体設定と、リポジトリ側のAGENTS.mdが両方読まれます。 - リポジトリ ルートから作業ディレクトリへ向かって、順に連結されます。 つまり、サブディレクトリに置いた
AGENTS.mdはあとから連結されるぶん、上位の指示より強く効きます。 - 合計サイズには上限があります。 既定で 32 KiB 程度で打ち切られるため、「とりあえず全部書く」と後ろが落ちます。文字コードのルールは、短く上位に置くほうが安全です。
この 3 点があるので、文字コード規約は リポジトリ ルートの AGENTS.md に、短く、最初のほうに書く のが実務的です。サブディレクトリ側に別の書き込み規約があると、そちらが勝ってしまいます。
1. まず結論
Windows 環境で Codex の文字化け事故を減らすうえで一番効きやすいのは、文字コードの作業手順を先に固定することです。
特に効くルールはこのあたりです。
- 日本語を含む既存ファイルは、読む前に encoding 候補、BOM 有無、改行コードを確認させる
- 文字化けが疑わしいファイルは、自信が持てるまで保存させない
- 既存ファイルは、元の encoding、BOM、改行を維持させる
- 新規ファイルは、リポジトリ規約に従って UTF-8 系へ寄せる
- 書き込みは、encoding を明示できる方法だけを使わせる
- 保存後は、再読込して日本語の代表行を検証させる
実務での短い言い方にすると、ほぼこれです。
- 読む前に確認
- 怪しければ保存禁止
- 既存は維持、新規だけ UTF-8
- 曖昧な書き込み経路を禁止
- 最後に再読込して確認
逆に危ないのはこういう指示です。
- 「文字化けを直して」
- 「全部 UTF-8 にして」
- 「CSV を出して」
- 「適当に合わせて」
- 「とりあえず保存して見て」
これらはどれも、Codex がどの段階で止まるべきか が書かれていません。文字化け対策では、何をするかだけでなく、どこで保存を止めるか まで指示する必要があります。
この記事の知識マップ
WindowsでCodexに日本語ファイルを扱わせるとき、鍵になるのは推測のままファイルを保存させないことです。CP932とUTF-8は同じバイト列を両立して正しく解釈できないため、読む前にBOMの有無や厳密UTF-8デコードでencoding候補を確認する手順が、実バイト列の解釈が本来のencodingとずれる事故を減らします。それでも見落とすと文字化けはファイル自体の破損として固定されるため、既存encodingの維持、encodingを明示する書き込み、保存後の再読込検証という作業ルールをAGENTS.mdに常設することが推奨されます。Windows PowerShell 5.1とPowerShell 7は既定の書き込みencodingが異なるため、曖昧な書き込み経路を避けることも欠かせません。
flowchart LR
accTitle: Codexの文字化け対策の知識マップ
accDescr: CodexにAGENTS.mdで文字コードの作業ルールを与えることが、encoding解釈のずれや推測のままの保存によるファイル破損をどう防ぐか、CP932とUTF-8の非互換性やPowerShellの版によるencoding既定の違いとあわせて示す図
codex["Codex"]
mojibake["文字化け"]
agents_md["AGENTS.md"]
character_encoding_rules["文字コードの作業ルール"]
pre_read_encoding_check["読む前のencoding/BOM/改行確認"]
unverified_save["推測のままの保存"]
existing_file_encoding_preservation["既存ファイルのencoding維持方針"]
explicit_encoding_write["encodingを明示する書き込み"]
post_write_reread_verification["保存後の再読込検証"]
ambiguous_write_path["曖昧な書き込み経路"]
utf8_migration_as_separate_task["UTF-8化の別タスク化"]
cp932["CP932"]
utf_8["UTF-8"]
bom["BOM(Byte Order Mark)"]
strict_utf8_decode_check["厳密UTF-8デコード判定"]
encoding_misinterpretation["encoding解釈のずれ"]
reencoding_corruption["誤ったencoding解釈によるファイル破損"]
replacement_character["U+FFFD(REPLACEMENT CHARACTER)"]
windows_powershell_5_1["Windows PowerShell 5.1"]
ansi_codepage["ANSIコードページ"]
utf_16["UTF-16"]
powershell_7["PowerShell 7"]
character_encoding_rules -->|"で構成できる"| agents_md
character_encoding_rules -->|"推奨される対応"| codex
pre_read_encoding_check -->|"推奨される対応"| codex
unverified_save -->|"用いるのは非推奨"| codex
existing_file_encoding_preservation -->|"推奨される対応"| codex
explicit_encoding_write -->|"推奨される対応"| codex
post_write_reread_verification -->|"推奨される対応"| codex
ambiguous_write_path -->|"用いるのは非推奨"| codex
utf8_migration_as_separate_task -->|"推奨される対応"| codex
cp932 -.->|"両立しない"| utf_8
pre_read_encoding_check -->|"で確認できる"| bom
pre_read_encoding_check -->|"で確認できる"| strict_utf8_decode_check
encoding_misinterpretation -->|"原因になり得る"| mojibake
mojibake -.->|"原因になり得る"| reencoding_corruption
unverified_save -.->|"原因になり得る"| reencoding_corruption
pre_read_encoding_check -->|"軽減する"| encoding_misinterpretation
reencoding_corruption -->|"で確認できる"| replacement_character
windows_powershell_5_1 -->|"利用する"| ansi_codepage
windows_powershell_5_1 -->|"利用する"| utf_16
powershell_7 -->|"利用する"| utf_8
ambiguous_write_path -->|"利用する"| windows_powershell_5_1
ambiguous_write_path -->|"利用する"| powershell_7
図の実線は常に成り立つ関係、破線は条件付きの関係です(成立条件は詳細ページの各関係の説明に記載)。関係すべての一覧(全22件、根拠・確度つき)と主要概念の定義は知識マップ詳細ページにまとめています。データ: JSON-LD / Turtle
2. なぜ Windows で文字化け事故が起きやすいのか
本当の問題は、Codex が日本語に弱いことではなく、Windows の資産側に複数の文字コードと複数の書き込み経路が共存していることです。
実務では、こういう混在は珍しくありません。
- 新しめのソースや Markdown は UTF-8
- 古い CSV、TXT、ログ、設定は CP932 系
- 一部の出力やツール生成物は UTF-16 系
- エディタ、shell、Excel 由来の出力で保存経路がばらばら
- 改行コードも LF と CRLF が混在
この状態で Codex が 1 回でも間違った解釈をすると、読めていない文字列を「読めているもの」として次の編集へ進む ことがあります。そしてそのまま保存すると、今度は表示上の問題ではなく、ファイル自体の破損 として固定されます。
だから文字化け対策は、突き詰めれば I/O 手順をどう管理するか の話になります。
2.1 先に用語を 4 つだけ
以降で何度も出てくる言葉を、ここで揃えておきます。
| 用語 | 意味 |
|---|---|
| CP932 | Windows の日本語コードページ。Microsoft のコードページ一覧では 932 番が shift_jis、説明は「ANSI/OEM 日本語、Japanese Shift-JIS」となっています。実務では「Windows 版の Shift_JIS」と考えて大きくは外れませんが、Windows-31J とも呼ばれ、他システムの Shift_JIS 実装と 1 バイトも違わない保証はありません。「Shift_JIS で」と言われたら、どの実装の Shift_JIS か を確認する価値があります |
| BOM | Byte Order Mark。ファイル先頭に置かれる、どの Unicode エンコーディングかを示す数バイトの目印。UTF-8 なら EF BB BF、UTF-16 LE なら FF FE、UTF-16 BE なら FE FF。BOM は本文ではないので、エディタ上では見えません。 差分だけが不自然に大きくなる事故の常連です |
| ANSI コードページ | その OS のロケールに対応した既定のレガシー コードページ。日本語 Windows なら 932。「ANSI で保存」は日本語環境では実質 CP932 保存を指します |
U+FFFD |
REPLACEMENT CHARACTER。デコードに失敗したバイトの置き換え先として入る文字で、多くの環境で「◆の中に ?」の形で表示されます。これが増えたら、その時点で情報は失われています |
大事なのは、CP932 と UTF-8 は どちらもファイル自身には書かれていない ことです。BOM がない限り、ファイルは「どう読むべきか」を自分では名乗りません。だから読む前の確認が要ります。
3. 最初に Codex へ固定したいルール
3.1 読む前に、encoding 候補と BOM と改行を確認させる
最初のルールはこれです。
日本語を含む既存ファイルを読む前に、現在の encoding 候補、BOM 有無、改行コードを確認し、怪しければそのまま内容解釈に進まないこと。
ポイントは、「テキストを読む前に、まずファイルの前提を見る」 に変えることです。
具体的にどう確認させるか
「確認して」とだけ書くと、Codex も人間もやり方がぶれます。確認手順まで指示に埋めておく ほうが安定します。以下は Windows PowerShell 5.1 と PowerShell 7 のどちらでも動く形です。
まず、先頭バイトを 16 進で見ます。BOM の有無はここで決まります。
$path = 'C:\work\orders.csv'
$bytes = [System.IO.File]::ReadAllBytes($path)
# 先頭 16 バイトを 16 進で表示する
$head = $bytes[0..([Math]::Min(15, $bytes.Length - 1))]
($head | ForEach-Object { $_.ToString('X2') }) -join ' '
以降のブロックは、ここで作った $path と $bytes をそのまま使います。読み方はこうです。
| 先頭バイト | 判定 |
|---|---|
EF BB BF |
UTF-8、BOM あり |
FF FE |
UTF-16 LE、BOM あり |
FE FF |
UTF-16 BE、BOM あり |
| 上のどれでもない | BOM なし。UTF-8 か CP932 かは中身で判断するしかない |
次に、改行コードを数えます。「LF と CRLF が混ざっている」はここで分かります。
$crlf = 0; $loneLf = 0; $loneCr = 0
for ($i = 0; $i -lt $bytes.Length; $i++) {
if ($bytes[$i] -eq 0x0A) {
if ($i -gt 0 -and $bytes[$i - 1] -eq 0x0D) { $crlf++ } else { $loneLf++ }
}
elseif ($bytes[$i] -eq 0x0D -and ($i -eq $bytes.Length - 1 -or $bytes[$i + 1] -ne 0x0A)) {
$loneCr++
}
}
"CRLF=$crlf LF=$loneLf CR=$loneCr"
最後に、encoding 候補を絞ります。BOM がないときは、UTF-8 として厳密にデコードできるかどうか が一番手早い判定材料です。UTF-8 はバイト列に強い制約があるので、CP932 のファイルを UTF-8 として厳密に読むと、たいてい途中で失敗します。
# 第 2 引数の $true が「不正なバイト列なら例外を投げる」指定
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
$null = $strictUtf8.GetString($bytes)
'UTF-8 として矛盾なくデコードできました'
}
catch {
'UTF-8 ではありません。CP932 などの候補を試してください'
}
CP932 側で読んでみるときは、コードページ番号を明示します。
# PowerShell 6.2 以降は、コードページ番号をそのまま指定できます
Get-Content -Path $path -Encoding 932 -TotalCount 3
# Windows PowerShell 5.1 では Default がシステムの ANSI コードページ。日本語 Windows なら CP932 です
Get-Content -Path $path -Encoding Default -TotalCount 3
厳密デコードが通っただけでは「UTF-8 で確定」ではありません。 ASCII だけのファイルはどちらでも通ります。最終的には、日本語の代表行が読めているかを目で確認させてください。
3.2 文字化けが疑わしいファイルは、推測のまま保存させない
これは特に重要です。
文字化けが疑われるときは、調査段階では read-only とし、解釈に自信が持てるまで上書き禁止にする。
人間でも同じですが、読めていないファイルを保存してはいけません。少し壊れて見えるけれどたぶんこれだろう、で保存すると、それが事故の確定版になります。
3.3 既存ファイルは維持し、新規ファイルだけ UTF-8 を基本にする
文字化け対策の文脈で、意外と危ないのが「全部 UTF-8 に統一して」です。
最終的に repo 全体を UTF-8 に寄せる判断はありえますが、それは 別タスク として差分と影響範囲を見ながらやるほうが安全です。日常の改修では、この運用が安定します。
- 既存ファイルを編集するときは、元の encoding を維持する
- 新規ファイルを追加するときは、repo 規約に従って UTF-8 系で作る
- 既存ファイルの変換が必要なら、通常の機能修正と分ける
3.4 曖昧な書き込み経路をデフォルトで使わせない
Windows で事故を増やしやすいのは、「ちょっとした出力だから shell で雑に書く」です。
- リダイレクトでそのまま吐く
- 便利コマンドでそのまま保存する
- 一時生成物をそのまま本番ファイルへ昇格する
こうした経路は、encoding が明示されていない ことが多く、事故の温床になります。だから Codex には、書き込み手段の選び方も固定しておくのが安全です。
「既定の encoding」は PowerShell の版で違う
ここは知らないと必ず踏みます。PowerShell は、版によって既定の書き込み encoding が違います。
| 書き込み経路 | Windows PowerShell 5.1 | PowerShell 7 |
|---|---|---|
Out-File、>、>> |
UTF-16LE | UTF-8、BOM なし |
新規ファイルへの Set-Content / Add-Content |
システムの ANSI コードページ | UTF-8、BOM なし |
Export-Csv |
ASCII | UTF-8、BOM なし |
つまり同じスクリプトでも、5.1 で流したか 7 で流したかで別のファイルができます。「開発機では平気だったのに、現場のサーバーで壊れた」の定番がこれです。
さらに 5.1 側には、Unicode 系の encoding を指定すると必ず BOM が付く という性質もあります。-Encoding UTF8 は UTF-8 BOM 付きです。
なので、書き込みは毎回明示させます。
# この節だけで完結するように、変数を定義しておきます
$path = 'C:\work\orders.csv'
$newPath = 'C:\work\orders-new.csv'
$lines = @('顧客コード,顧客名', 'C0001,株式会社サンプル')
# 既存が CP932 なら CP932 のまま書き戻す(PowerShell 6.2 以降)
Set-Content -Path $path -Value $lines -Encoding 932
# Windows PowerShell 5.1 でシステムの ANSI コードページに合わせる
Set-Content -Path $path -Value $lines -Encoding Default
# 新規ファイルを BOM なし UTF-8 で作る(PowerShell 7)
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM
セッション全体で既定を寄せたいなら、$PSDefaultParameterValues を使う手もあります。ただしこれは そのセッションだけの設定 なので、「うちのプロファイルには書いてある」を前提にした手順書は、他人の環境で壊れます。
$PSDefaultParameterValues['*:Encoding'] = 'utf8NoBOM'
Out-File の代わりに > を使う書き方も、5.1 以降は内部で Out-File を呼ぶだけなので、既定の encoding は同じ問題を抱えます。リダイレクトを禁止して、encoding を書ける cmdlet か .NET API だけ使わせる のが一番確実です。
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 行は、かなり効きます。
5.1 日本語版テンプレート
チームのレビューが日本語で回るなら、AGENTS.md も日本語のほうが運用しやすいことがあります。内容は同じです。
# 文字コードの取り扱い規約
## 適用範囲
このリポジトリには日本語テキストと、レガシーな文字コードのファイルが混在します。
文字化けと、意図しない再エンコードを、他の何よりも優先して避けてください。
## 必ず守ること
- 日本語を含む可能性がある既存テキストファイルは、読む前に次を確認する。
- encoding の候補
- BOM の有無
- 改行コード
- 文字化けが疑われる間は、解釈に確信が持てるまでそのファイルを保存しない。
- 既存ファイルは、元の encoding、BOM、改行コードを維持する。
- 「UTF-8 に変換する」は、機能修正とは別の独立したタスクとして扱う。
- 新規ファイルはリポジトリ規約に従う。規約がなければ UTF-8 を選び、BOM の有無を明記する。
- encoding を明示できない書き込み経路を既定で使わない。
シェルのリダイレクトや、encoding を指定できない便利コマンドが該当する。
- 書き込んだあとは開き直し、日本語の代表行が壊れていないことを確認する。
- 次のいずれかが出たら、修正しようとせず、いったん止めて報告する。
- 置換文字 U+FFFD の増加
- 想定していない `?` の増加
- 意図しない BOM の変化
- 意図しない改行コードの変換
- 業務上の理由がないファイル全体の差分
## 報告のしかた
変更したテキストファイルごとに、次を報告する。
- パス
- 検出した、または維持した encoding
- BOM の有無
- 改行コード
- どうやって検証したか
- 日本語の代表文字列が無事だったか
英語版と日本語版のどちらか一方で構いません。両方置くと 2 倍の分量を消費する ので、AGENTS.md の読み込みサイズ上限を考えると、片方に決めるほうが安全です。
6. NG 指示と OK 指示
文字化け対策では、指示の粒度が結果をかなり左右します。
| NG 指示 | OK 指示 |
|---|---|
| 文字化けを直して | まず、ファイル自体の破損か表示側だけの問題かを切り分け、推測のまま保存しないでください |
| 全部 UTF-8 にして | 既存ファイルは元の encoding を維持し、新規だけ repo 規約に従って UTF-8 系にしてください。既存変換は別タスクにしてください |
| CSV を出して | 既存運用の encoding に合わせ、書き込み時に encoding を明示し、出力後に日本語列を再読込して確認してください |
| 読める範囲で直して | 自信が持てない箇所は保存せず、候補と根拠を報告してください |
| 適当に合わせて | BOM、改行、encoding を勝手に変えず、差分が業務変更だけになるようにしてください |
ポイントは、手を動かす前の確認 と 保存後の検証 を必ず書くことです。
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
- Microsoft Learn, about_Character_Encoding
- Microsoft Learn, Code Page Identifiers
- Microsoft Learn, Byte order mark
関連する記事
同じタグを共有する最新の記事です。さらに近い話題で知識を深められます。
Windowsの文字コードと改行コード - 文字化けとCRLF/LFの基本
Windows で混ざりやすい Shift_JIS / UTF-8 / UTF-16、文字化け、CRLF / LF の違いを、実務で判断しやすい形に整理します。
Windows文字コード入門 - Linux連携で起きる文字化け
Windowsで文字化けが起きる理由を、CP932、UTF-8、UTF-16、BOM、コードページ、PowerShell、Linux localeの違いから実務向けに整理します。
マルチスレッドの実務ベストプラクティス C言語編 ── Win32 APIの流儀で安全に書く
C言語×Win32のマルチスレッドは、_beginthreadexでのスレッド作成、SRWロックと条件変数、Interlocked、停止イベント+WaitForMultipleObjectsの停止設計が定石。TerminateThreadの危険とDllMainの制約まで整理...
マルチスレッドの実務ベストプラクティス C++編 ── RAIIとjthreadで事故を構造から消す
C++のマルチスレッドはデータ競合が未定義動作になる世界。std::threadのデストラクタの罠、jthreadとstop_tokenによる停止設計、scoped_lockのデッドロック回避、atomicの正しい位置づけ、Win32同期APIとの使い分けまで整理します。
マルチスレッドの実務ベストプラクティス .NET編 ── スレッドを増やす前に決めておくこと
「スレッドを立てたら、たまに落ちる・固まる」を防ぐ設計の定石を.NET/C#向けに整理。スレッドを自分で作らずTaskに乗る、共有可変状態を減らす、ロックの規律、CancellationTokenでの停止設計、UIスレッドの扱いまで解説します。
関連トピック
このテーマと近いトピックページです。記事を起点に、関連するサービスや他の記事へ進めます。
Windows技術トピック
Windows 開発、不具合調査、既存資産活用の技術トピックをまとめた入口です。
このテーマがつながるサービス
この記事は次のサービスページにつながります。近い入口からご覧ください。
技術相談・設計レビュー
既存資産に CP932 や UTF-8 が混在する開発環境では、AI への指示ルールと運用手順を先に整理したほうが事故を減らしやすいです。
Windowsアプリ開発
Windows 向けの業務ツールや保守案件では、日本語ファイルや CSV、設定ファイルの文字コード事故を避ける運用設計が実装品質に直結します。
よくある質問
この記事のテーマについて、相談時によくある質問をまとめています。
- WindowsでCodexを使うと日本語が文字化けするのはなぜですか?
- 本当の原因は Codex が日本語に弱いことではなく、Windows の資産側に UTF-8、CP932、UTF-16 系など複数の文字コードと複数の書き込み経路が共存していることです。この状態で Codex が一度でも間違った解釈をすると、読めていない文字列を「読めているもの」として次の編集へ進むことがあります。そしてそのまま保存すると、表示上の問題ではなくファイル自体の破損として固定されます。だから文字化け対策は、突き詰めれば I/O 手順をどう管理するかの話になります。
- Codexの文字化けを防ぐには、どんな指示をすればよいですか?
- 文字コードの作業手順を先に固定するのが一番効きます。具体的には、日本語を含む既存ファイルは読む前に encoding 候補・BOM 有無・改行コードを確認させる、文字化けが疑わしいファイルは自信が持てるまで保存させない、既存ファイルは元の encoding を維持し新規だけ UTF-8 系にする、encoding を明示できる書き込み方法だけを使わせる、保存後は再読込して日本語の代表行を検証させる、の 5 点です。対象ファイルと「壊れてはいけない代表文字列」を渡すと、さらに安定します。
- 「文字化けを直して」「全部UTF-8にして」と指示してはいけないのですか?
- どちらも危ない指示です。Codex がどの段階で保存を止めるべきかが書かれていないため、推測のまま保存されて事故が確定しやすくなります。「全部 UTF-8 に」は特に危険で、既存ファイルの編集では元の encoding・BOM・改行を維持させ、repo 全体の UTF-8 化は差分と影響範囲を見ながら進める別タスクとして切り出すほうが安全です。代わりに「破損か表示側の問題かを切り分け、推測のまま保存しない」のように、手を動かす前の確認と保存後の検証まで含めて指示します。
- 文字コードのルールはAGENTS.mdに書いたほうがよいですか?
- 同じ注意を毎回のタスクで繰り返すくらいなら、AGENTS.md に常設するほうが効きます。読む前の encoding・BOM・改行の確認、文字化けが疑われる間の保存禁止、既存ファイルの維持、UTF-8 変換の別タスク化、曖昧な書き込み経路の禁止、保存後の再読込検証、異常時に止めて報告するルールをまとめて書いておきます。加えて、変更したファイルごとに encoding・BOM・改行・検証方法を報告させるフォーマットまで固定すると、レビュー側のチェックも安定します。