在 Windows 減少 Codex 亂碼問題的指示規則

在 Windows 上讓 Codex 處理含日文的檔案時，最先派得上用場的，不是把編輯器與 shell 的設定全部對齊，而是對 Codex 明確說清楚「怎麼讀、怎麼寫、在哪裡停下來」。

特別容易卡住的是下列這些場面。

• UTF-8、CP932、UTF-16 系的檔案混在一起
• 表面上看起來讀得出來，但實際位元組的解讀已經對不上
• 以為只是稍微改了一下既有檔案，儲存時卻用別的 encoding 重新存了一次
• 壞掉的是 CSV、TXT、日誌、Markdown、設定檔這類「程式碼以外」的檔案
• 把暫時用的指令碼或 shell 輸出直接存下來，問題就此固定

OpenAI 的 Codex，與其當成一次性的聊天對象，不如當成一位給它設定與作業規則、持續合作的隊友，這樣比較穩定。特別是維運上已經讓它讀 AGENTS.md 的話，字元編碼的規則與其每次口頭重複，不如常設在文件裡更有效。

本文梳理在 Windows 要讓 Codex 安全處理日文檔案時，一開始就給出、效果最明顯的指示，並以實務角度編排。

flowchart TB
    accTitle: 先釘住指示，再談設定
    accDescr: 在 Windows 讓 Codex 處理日文檔案時，最先派得上用場的不是把編輯器或 shell 的設定對齊，而是明確說清楚怎麼讀、怎麼寫、在哪裡停下來的圖。
    a1["把編輯器或 shell 的設定對齊"] -.-> a2["最先見效的不是這邊"]
    a3["怎麼讀"] --> a6["對 Codex 明確說清楚"]
    a4["怎麼寫"] --> a6
    a5["在哪裡停下來"] --> a6

圖 1: 最先見效的不是環境設定，而是把讀法、寫法、停下的時機說清楚。

前提：本文假設的 Codex 與 AGENTS.md

先為還沒用過 Codex 的讀者寫下前提。

Codex 是會實際讀寫儲存庫檔案的程式開發代理程式（coding agent）。入口有好幾種：在本機終端機執行的 CLI、編輯器擴充功能、在雲端執行的版本；本文假設的是讓它直接編輯本機儲存庫檔案的用法。亂碼問題發生在「編輯後儲存」的時候，所以比起走哪個入口，如何約束寫入檔案的路徑才是本質。

AGENTS.md 是一份 Markdown 檔案，用來寫下在該儲存庫工作時的常設指示。它被讀取的方式有幾個值得先掌握的性質。

• 位置不只一處。 家目錄下 ~/.codex/AGENTS.md 這類全域設定，與儲存庫側的 AGENTS.md，兩邊都會被讀取。
• 會從儲存庫根目錄往工作目錄依序串接。 也就是說，放在子目錄的 AGENTS.md 因為串接在後面，會比上層的指示更強勢。
• 合計大小有上限。 預設在 32 KiB 左右就會被截斷，所以「先全部寫上去再說」會讓後面的內容掉光。字元編碼的規則寫短一點、放在上層比較安全。

有這 3 點，所以字元編碼規約在實務上要寫在儲存庫根目錄的 AGENTS.md，寫短，而且放在前面。如果子目錄那邊另有寫入規約，贏的會是那一份。

flowchart TB
    accTitle: AGENTS.md 被讀取的方式
    accDescr: AGENTS.md 在家目錄側與儲存庫側都會被讀取，並從根目錄往工作目錄串接，串在後面的下層更強勢，合計大小預設在 32 KiB 左右被截斷，因此字元編碼規約要寫短並放在根目錄前面的圖。
    b1["家目錄側的 AGENTS.md"] --> b3["從根目錄往工作目錄串接"]
    b2["儲存庫側的 AGENTS.md"] --> b3
    b3 --> b4["串在後面的下層更強勢"]
    b3 -.-> b5["預設約 32 KiB 就截斷"]
    b4 --> b6["規約放根目錄，寫短並放在前面"]
    b5 -.-> b6

圖 2: AGENTS.md 有串接順序與大小上限，所以規約要短，放在根目錄的前面。

1. 先講結論

在 Windows 環境要減少 Codex 的亂碼問題，最容易見效的是先把字元編碼的作業步驟釘住。

特別有效的規則大致是這些。

• 含日文的既有檔案，讀之前先讓它查看 encoding 候選、有無 BOM、換行字元
• 疑似亂碼的檔案，在有把握之前不讓它儲存
• 既有檔案，讓它維持原本的 encoding、BOM、換行
• 新建檔案，依儲存庫規約統一改用 UTF-8 系
• 寫入時，只讓它使用能明確指定 encoding 的方式
• 儲存後，讓它重新讀取，驗證日文的代表行

換成實務上的短說法，大致就是這幾句。

• 讀之前先查看
• 有疑慮就禁止儲存
• 既有維持原狀，只有新建採 UTF-8
• 禁止模糊的寫入路徑
• 最後重新讀取確認

flowchart TB
    accTitle: 防止字元編碼問題的 5 個步驟
    accDescr: 依序呈現讀之前先查看、有疑慮就禁止儲存、既有維持原狀只有新建採 UTF-8、禁止模糊的寫入路徑、最後重新讀取確認這幾句實務短說法的圖。
    c1["讀之前先查看"] --> c2["有疑慮就禁止儲存"]
    c2 --> c3["既有維持原狀，只有新建採 UTF-8"]
    c3 --> c4["禁止模糊的寫入路徑"]
    c4 --> c5["最後重新讀取確認"]

圖 3: 想釘住的作業步驟，可以收攏成這 5 個流程。

反過來說，下列這類指示很危險。

• 「幫我修好亂碼」
• 「全部改成 UTF-8」
• 「輸出一份 CSV」
• 「隨手對齊一下就好」
• 「先存起來看看」

這些指示都沒有寫出Codex 該在哪個階段停下來。亂碼對策不能只寫要做什麼，還必須指示到在哪裡停止儲存。

圖中實線表示始終成立的關係，虛線表示附帶條件的關係（成立條件寫在詳細頁面中各關係的說明中）。關係的完整清單（共 22 條，附依據與可信度）以及主要概念的定義，彙整在知識地圖詳細頁面（日文）。資料：JSON-LD / Turtle

2. 為什麼 Windows 特別容易發生亂碼問題

真正的問題不是 Codex 不擅長日文，而是Windows 這側的既有資產同時存在多種字元編碼與多條寫入路徑。

在實務上，這種混用並不罕見。

• 比較新的原始碼與 Markdown 是 UTF-8
• 舊的 CSV、TXT、日誌、設定是 CP932 系
• 部分輸出與工具產出物是 UTF-16 系
• 編輯器、shell、Excel 產生的輸出，儲存路徑各不相同
• 換行字元也混用 LF 與 CRLF

在這種狀態下，Codex 只要有一次解讀錯誤，就可能把根本沒讀懂的字串當成「已經讀懂」，直接進入下一步編輯。若就這樣儲存，問題就不再是顯示層面，而是固定成檔案本身的毀損。

所以亂碼對策追根究柢，談的是如何管理 I/O 步驟。

flowchart TB
    accTitle: 問題固定成毀損的過程
    accDescr: 在多種字元編碼與寫入路徑並存的資產上，Codex 只要有一次解讀錯誤，就會把沒讀懂的字串當成已經讀懂而進入下一步編輯，儲存的當下就不再是顯示層面的問題，而是固定成檔案本身毀損的圖。
    d1["多種 encoding 與寫入路徑並存"] --> d2["一次錯誤的解讀"]
    d2 --> d3["沒讀懂就進入下一步編輯"]
    d3 --> d4["儲存後固定成毀損"]
    d4 -.-> d5["對策的本體是管理 I/O 步驟"]

圖 4: 亂碼從顯示問題開始，在儲存的瞬間固定成毀損。

2.1 先講 4 個名詞

以下會反覆出現的詞，先在這裡對齊。

重點是，CP932 與 UTF-8 兩者都沒有寫在檔案本身裡。只要沒有 BOM，檔案就不會自己說明「該怎麼讀」。所以讀之前的查看是必要的。

flowchart TB
    accTitle: 檔案不會自己說明 encoding
    accDescr: 是 CP932 還是 UTF-8 並沒有寫在檔案本身裡，只要沒有 BOM，檔案就不會說明該怎麼讀，因此讀之前必須先查看的圖。
    e1["檔案的內容只是位元組序列"] --> e2{"有 BOM 嗎"}
    e2 -->|"有"| e3["可以判斷是 Unicode 系"]
    e2 -->|"沒有"| e4["是 UTF-8 還是 CP932 只能看內容判斷"]
    e4 --> e5["所以讀之前的查看是必要的"]

圖 5: 沒有 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。判讀方式如下。

接著計算換行字元。「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 的檔案兩邊都會通過。最後還是要讓它用眼睛確認日文的代表行有沒有讀對。

flowchart TB
    accTitle: 讀之前的查看步驟
    accDescr: 以 16 進位看開頭位元組判斷有無 BOM，計算換行字元，用嚴格 UTF-8 解碼縮小 encoding 候選，最後用眼睛確認日文代表行有沒有讀對這一連串步驟的圖。
    f1["以 16 進位看開頭位元組"] --> f2["判斷有沒有 BOM"]
    f2 --> f3["計算換行字元"]
    f3 --> f4["用嚴格 UTF-8 解碼縮小候選"]
    f4 --> f5["用眼睛確認日文代表行"]
    f4 -.-> f6["只有 ASCII 的話兩邊都會通過"]

圖 6: 讀之前的查看，依位元組、換行、解碼、目視的順序進行。

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 並不相同。

也就是說，同一份指令碼，在 5.1 執行還是在 7 執行，產生的會是不同的檔案。「開發機上沒事，到了第一線的伺服器就壞了」的經典案例就是這個。

此外 5.1 這側還有一個性質：只要指定 Unicode 系的 encoding，就一定會加上 BOM。-Encoding UTF8 是帶 BOM 的 UTF-8。

所以，每一次寫入都要讓它明確指定。

# 為了讓這一節能單獨成立，先定義變數
$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，是最確實的做法。

flowchart TB
    accTitle: 同一份指令碼會產生不同的檔案
    accDescr: PowerShell 不同版本的預設寫入 encoding 不同，因此同一份指令碼在 5.1 執行或在 7 執行會產生不同的檔案，禁止重新導向、只讓它使用能寫出 encoding 的 cmdlet 或 .NET API 才確實的圖。
    g0["同一份指令碼"] --> g1["在 Windows PowerShell 5.1 執行"]
    g0 --> g2["在 PowerShell 7 執行"]
    g1 --> g3["產生不同 encoding 的檔案"]
    g2 --> g3
    g3 -.-> g4["只讓它使用能明確指定 encoding 的路徑"]

圖 7: 預設的 encoding 會因版本而異，所以每次寫入都要讓它明確指定。

3.5 儲存後重新讀取，讓它確認日文的代表行

「存好了」和「沒有壞掉」不是同一件事。

重點是儲存後讓它再讀一次具代表性的日文行，確認下列幾點。

• 有沒有混入替換字元 U+FFFD
• ? 有沒有莫名增加
• 有沒有變成只有 BOM 或換行的巨大差異
• 業務上沒有變更的日文是否原樣保留

3.6 出現異常徵兆時，先回報再修

字元編碼問題上，與其硬要它修好，不如讓它停下來回報，災情範圍會比較小。

例如出現下列徵兆時，先當成異常處理比較安全。

• U+FFFD 增加
• ? 增加
• 非預期的 BOM 變化
• 只有換行的大量差異
• 只有日文行莫名地大幅變動

flowchart TB
    accTitle: 出現異常徵兆就停下來回報
    accDescr: 出現替換字元 U+FFFD 或 ? 增加、非預期的 BOM 變化、只有換行的大量差異等徵兆時，與其硬要它修好，不如讓它停下來回報，災情範圍會比較小的圖。
    h1["U+FFFD 或 ? 增加"] --> h4["先當成異常處理"]
    h2["非預期的 BOM 變化"] --> h4
    h3["只有換行的大量差異"] --> h4
    h4 --> h5["先停下來回報，再談修正"]

圖 8: 出現異常徵兆時，不是讓它去修，而是讓它停下來回報。

4. 如果要以簡短的指示文交出去

要附在每次任務上的簡短版本，這樣的分量就已經很有效。

本次作業請以避免字元編碼問題為最優先。

- 含日文的既有檔案，讀之前先確認 encoding 候選、有無 BOM、換行字元
- 疑似亂碼的檔案，不要在臆測下儲存
- 既有檔案維持原本的 encoding / BOM / 換行
- 新建檔案依 repo 規約以 UTF-8 系建立
- 寫入只使用能明確指定 encoding 的方式
- 儲存後重新讀取，確認日文的代表行沒有壞掉
- 若出現 `U+FFFD`、`?` 增加、BOM / 換行問題、大量差異，就當成異常回報

如果目標檔案已經確定，再加上這 1 行會相當穩定。

目標檔案: <paths> / 代表字串: "<examples>"

交出代表字串相當有效。因為這能讓 Codex 握有「這段日文不能壞」的具體監控點。

flowchart TB
    accTitle: 用代表字串交出監控點
    accDescr: 交出目標檔案與不能壞掉的代表字串，就能讓 Codex 握有這段日文不能壞的具體監控點，指示會相當穩定的圖。
    i1["指定目標檔案"] --> i3["讓它握有具體的監控點"]
    i2["不能壞掉的代表字串"] --> i3
    i3 --> i4["指示會相當穩定"]

圖 9: 目標檔案與代表字串這 1 行，把驗證的著力點固定下來。

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 指示

在亂碼對策上，指示的細緻程度會相當左右結果。

重點是一定要寫上動手前的檢查與儲存後的驗證。

flowchart TB
    accTitle: 把 NG 指示改成 OK 指示的型
    accDescr: 像「幫我修好亂碼」這樣的指示沒有寫出該在哪裡停下來，因此要補上動手前的檢查與儲存後的驗證，改成連在哪裡停止儲存都涵蓋的指示的圖。
    j1["「幫我修好亂碼」"] --> j2["沒有寫出停下來的位置"]
    j2 -.->|"補寫上去"| j3["動手前的檢查"]
    j2 -.->|"補寫上去"| j4["儲存後的驗證"]
    j3 --> j5["涵蓋在哪裡停下來的指示"]
    j4 --> j5

圖 10: 與 NG 指示的差別，在於有沒有檢查、驗證，以及停下來的位置。

7. 審查時的檢查清單

讓 Codex 做完之後，把人這端要看的檢查點也固定下來，會更穩定。

• 每個變更過的檔案，encoding / BOM / 換行的處理方式有沒有被回報
• 是不是只有日文行莫名地大幅變動
• 有沒有冒出大量只有換行的差異
• U+FFFD 或 ? 有沒有增加
• 有沒有與業務變更無關的整檔差異
• CSV 或日誌有沒有出現欄位錯位、引號錯位

亂碼對策重要的是，比起增加成功的差異，更該早一點煞住可疑的差異。

8. 總結

在 Windows 環境讓 Codex 處理日文檔案時，最先見效的不是把電腦這端調到完美，而是對 Codex 明確說清楚字元編碼的作業步驟。

特別想記住的有 5 點。

• 讀之前先讓它查看 encoding / BOM / 換行
• 疑似亂碼時，不要讓它在臆測下儲存
• 既有檔案維持原狀，只有新建檔案統一改用 UTF-8 系
• 禁止模糊的寫入路徑
• 儲存後重新讀取，讓它確認日文的代表行

然後，與其每次都講，不如寫進 AGENTS.md。這才是最實務的做法。

亂碼對策的核心，不在於拜託它「好好處理日文」，而在於把可以儲存的條件與必須停下的條件白紙黑字寫下來。寫到這個程度，Codex 在 Windows 上也會變得相當好用。

flowchart TB
    accTitle: 核心是把條件白紙黑字寫下來
    accDescr: 亂碼對策的核心不在於拜託它好好處理日文，而在於把可以儲存的條件與必須停下的條件白紙黑字寫下來的圖。
    k1["拜託它「好好處理日文」"] -.-> k2["這裡不是核心"]
    k3["白紙黑字寫下可以儲存的條件"] --> k5["Codex 在 Windows 上也變得好用"]
    k4["白紙黑字寫下必須停下的條件"] --> k5

圖 11: 核心不是拜託的方式，而是把儲存與停止的條件白紙黑字寫下來。

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 使用 Codex 時，日文為什麼會變成亂碼？

真正的原因不是 Codex 不擅長日文，而是 Windows 這側的既有資產同時存在 UTF-8、CP932、UTF-16 系等多種字元編碼，以及多條寫入路徑。在這種狀態下，Codex 只要有一次解讀錯誤，就可能把根本沒讀懂的字串當成「已經讀懂」，直接進入下一步編輯。若就這樣儲存，問題就不再只是顯示層面，而是固定成檔案本身的毀損。所以亂碼對策追根究柢，談的是如何管理 I/O 步驟。

要防止 Codex 產生亂碼，該給什麼樣的指示？

先把字元編碼的作業步驟釘住最有效。具體來說有 5 點：含日文的既有檔案，讀之前先讓它查看 encoding 候選、有無 BOM、換行字元；疑似亂碼的檔案，在有把握之前不讓它儲存；既有檔案維持原本的 encoding，只有新建檔案採 UTF-8 系；只讓它使用能明確指定 encoding 的寫入方式；儲存後讓它重新讀取，驗證日文的代表行。再把目標檔案與「不能壞掉的代表字串」交給它，會更穩定。

「幫我修好亂碼」「全部改成 UTF-8」這種指示不能下嗎？

兩種都是危險的指示。因為沒有寫出 Codex 該在哪個階段停止儲存，很容易在臆測之下就存檔，讓問題就此定案。「全部改成 UTF-8」尤其危險：編輯既有檔案時要讓它維持原本的 encoding、BOM 與換行，整個 repo 的 UTF-8 化則切出成另一個任務，一邊看差異與影響範圍一邊進行才安全。改成「先分辨是檔案毀損還是顯示端的問題，不要在臆測下儲存」這樣的寫法，把動手前的檢查與儲存後的驗證都寫進指示裡。

字元編碼的規則寫進 AGENTS.md 會比較好嗎？

與其每次任務都重複同樣的提醒，不如常設在 AGENTS.md 裡更有效。把下列規則一次寫齊：讀取前確認 encoding、BOM、換行字元；疑似亂碼期間禁止儲存；既有檔案維持原狀；UTF-8 轉換另立任務；禁止模糊的寫入路徑；儲存後重新讀取驗證；出現異常就停下來回報。再進一步，連「每個變更過的檔案都要回報 encoding、BOM、換行字元與驗證方式」的格式都固定下來，審查這端的檢查也會跟著穩定。

作者檔案

本文作者的個人檔案頁面。

Go Komura

小村軟體有限公司 代表

以 Windows 軟體開發、技術諮詢與故障調查為中心，在難以重現的故障調查與既有資產仍在運作的專案上具有優勢。