知識マップ: WindowsでCodexの文字化け事故を減らす指示ルール

記事「Windowsで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件)

図と同じ関係を文章でも列挙します。表示している文と機械可読な意味データ(RDFa)は同じ要素に載っています。確度が「確立した関係」のものは直接の関係として、「条件付きの関係」のものは成立条件つきの言明(rdf:Statement)として表現しています。

文字コードの作業ルールはAGENTS.mdで構成できます。文字コードに関する作業ルールは、毎回のタスクで繰り返すよりAGENTS.mdへ常設したほうが安定する。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
文字コードの作業ルールはCodexに対する本記事の推奨です。Windowsで日本語ファイルを扱わせるCodexに、最初に与えると効きやすい作業ルールである。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
読む前のencoding/BOM/改行確認はCodexに対する本記事の推奨です。日本語を含む既存ファイルは、読む前にencoding候補・BOM有無・改行コードを確認させることが推奨される。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
推測のままの保存をCodexに用いることは推奨されません。文字化けが疑わしいファイルを、encoding解釈に自信が持てないまま保存させることは推奨されない。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
既存ファイルのencoding維持方針はCodexに対する本記事の推奨です。既存ファイルの編集では元のencoding・BOM・改行を維持させ、新規ファイルだけUTF-8系にすることが推奨される。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
encodingを明示する書き込みはCodexに対する本記事の推奨です。書き込みはencodingを明示できる方法だけを使わせることが推奨される。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
保存後の再読込検証はCodexに対する本記事の推奨です。保存後は再読込して日本語の代表行を検証させることが推奨される。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
曖昧な書き込み経路をCodexに用いることは推奨されません。リダイレクトや便利コマンドなど、encodingを明示しない書き込み経路をデフォルトで使わせることは推奨されない。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
UTF-8化の別タスク化はCodexに対する本記事の推奨です。リポジトリ全体をUTF-8へ統一する作業は、日常の改修とは切り離した別タスクとして進めることが推奨される。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
CP932はUTF-8と両立しません。非ASCIIのバイトを含む場合、CP932のバイト列をUTF-8として厳密にデコードすると多くの場合失敗するため、同じバイト列を両方の解釈で同時に正しく読むことはできない。ASCIIの範囲だけで書かれたファイルは両方の解釈で同一に読める / 確度: 条件付きの関係 / 確認日: 2026-08-01 出典
読む前のencoding/BOM/改行確認はBOM(Byte Order Mark)で確認できます。ファイル先頭がEF BB BF/FF FE/FE FFであれば、それだけでUTF-8/UTF-16 LE/UTF-16 BEと確定できる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
読む前のencoding/BOM/改行確認は厳密UTF-8デコード判定で確認できます。BOMがない場合は、UTF-8として厳密にデコードできるかどうかがCP932などとの切り分けに使える最有力の手がかりになる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
encoding解釈のずれは文字化けの原因になることがあります。実際のバイト列の解釈が本来のencodingとずれると、表示や内容が壊れて見える文字化けが起きる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
文字化けは誤ったencoding解釈によるファイル破損の原因になることがあります。文字化けに気づかないまま保存すると、表示上の問題ではなくファイル自体の破損として固定される。 / 確度: 条件付きの関係 / 確認日: 2026-08-01 出典
推測のままの保存は誤ったencoding解釈によるファイル破損の原因になることがあります。encoding解釈に自信が持てないまま保存すると、誤った解釈がそのままファイルの破損として固定され得る。 / 確度: 条件付きの関係 / 確認日: 2026-08-01 出典
読む前のencoding/BOM/改行確認はencoding解釈のずれを軽減します。読む前にencoding候補・BOM・改行を確認させることで、実バイト列の解釈が本来のencodingとずれるリスクを減らせる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
誤ったencoding解釈によるファイル破損はU+FFFD(REPLACEMENT CHARACTER)で確認できます。保存後の再読込で置換文字U+FFFDや`?`の増加が見えたら、encoding解釈が壊れていたことを確認できる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
Windows PowerShell 5.1はANSIコードページを利用します。Windows PowerShell 5.1でSet-Content/Add-Contentが新規ファイルに書き込むときの既定encodingは、システムのANSIコードページである。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
Windows PowerShell 5.1はUTF-16を利用します。Windows PowerShell 5.1でOut-Fileやリダイレクト(>、>>)を使ったときの既定書き込みencodingはUTF-16LEである。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
PowerShell 7はUTF-8を利用します。PowerShell 7でOut-File、Set-Content、Export-Csvを使ったときの既定書き込みencodingはBOMなしUTF-8である。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
曖昧な書き込み経路はWindows PowerShell 5.1を利用します。曖昧な書き込み経路の既定encodingは、Windows PowerShell 5.1ではUTF-16LEやANSIコードページになる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典
曖昧な書き込み経路はPowerShell 7を利用します。曖昧な書き込み経路の既定encodingは、PowerShell 7ではBOMなしUTF-8になる。 / 確度: 確立した関係 / 確認日: 2026-08-01 出典

主要概念の定義

Codex: OpenAIが提供する、リポジトリのファイルを実際に読み書きするコーディングエージェント。
文字化け: 実際のバイト列の解釈が意図したencodingとずれ、表示や内容が壊れて見える状態。
AGENTS.md: リポジトリでの作業に対する常設の指示を書いておくMarkdownファイルで、ルートから作業ディレクトリへ向かって連結され、既定で合計32KiB程度で打ち切られる。
文字コードの作業ルール: 既存ファイルを読む前の確認、推測のままの保存禁止、既存encodingの維持、encoding明示書き込み、保存後の再読込検証などをまとめた、Codexに与える作業手順の集合。
読む前のencoding/BOM/改行確認: 日本語を含む既存ファイルを読む前に、encoding候補・BOMの有無・改行コードを確認する作業手順。
推測のままの保存: 文字化けが疑わしいファイルについて、encoding解釈に自信が持てないまま上書き保存すること。
既存ファイルのencoding維持方針: 既存ファイルを編集するときは元のencoding・BOM・改行コードを維持し、新規ファイルだけrepo規約に沿ったUTF-8系で作成する運用方針。
encodingを明示する書き込み: Set-Content -Encodingなど、書き込み時に使用するencodingを明示的に指定する方法。
保存後の再読込検証: 保存後にファイルを再読込し、日本語の代表行が壊れていないか、置換文字や`?`が増えていないかなどを確認する作業手順。
曖昧な書き込み経路: リダイレクトやOut-Fileなど、encodingを明示しないままファイルへ書き込む経路。
UTF-8化の別タスク化: リポジトリ全体をUTF-8へ統一する変換は、通常の機能修正とは分離し、差分と影響範囲を見ながら進める独立したタスクとして扱う方針。
CP932: Windowsの日本語コードページ(コードページ番号932)。実務上はWindows版のShift_JISに近いが、他システムのShift_JIS実装と1バイトも違わない保証はない。
encoding解釈のずれ: 見た目は読めているように見えるが、実際のバイト列の解釈がファイルの本来のencodingとずれている状態。
誤ったencoding解釈によるファイル破損: 読めていない文字列を読めているものとして扱ったまま保存した結果、表示上の問題ではなくファイル自体の破損として固定される状態。
Windows PowerShell 5.1: Windowsに標準で同梱されている、.NET Framework上に構築されたレガシー世代のPowerShell(5.1系)のランタイム。実行ファイルはpowershell.exeで、.NETアプリからはMicrosoft.PowerShell.5.1.ReferenceAssembliesを介して呼び出せる。
PowerShell 7: PowerShell Core系譜の最新世代で、.NET(Core以降)上に構築されたPowerShellのエディション。実行ファイルはpwsh.exeで5.1のpowershell.exeとサイドバイサイドに共存し、Out-File・Set-Content・Export-Csvなどの既定書き込みencodingはBOMなしUTF-8である。

機械可読データ

JSON-LD / Turtle ── この記事の知識グラフ全体
概念一覧 / 語彙(述語)の定義

このページはサイトの知識グラフ(_data/knowledge/)から自動生成されています。誤りの指摘はお問い合わせからお願いします。