小村軟體有限公司
日本語 English 한국어 繁體中文 العربية
聯絡我們
選單

在 Windows 環境下減少 Codex 亂碼事故的最佳實務 - 先把『指示方式』釘住，再談環境整備

· · Codex, Windows, 亂碼, UTF-8, CP932, AI 編碼

在 Windows 讓 Codex 處理含日文的檔案時，最先見效的並不是把編輯器或 shell 的設定全部對齊，而是 對 Codex 明確說清楚「怎麼讀、怎麼寫、在哪停住」。

特別容易出問題的場景如下。

  • UTF-8、CP932、UTF-16 系的檔案混在一起
  • 表面上看起來能讀，但實際位元組的解讀其實錯了
  • 以為只是稍微修了一下既有檔案，儲存時卻換成別的 encoding 重新寫入
  • CSV、TXT、日誌、Markdown、設定檔這類「程式碼以外」的檔案壞掉
  • 暫存腳本或 shell 輸出直接存起來，讓事故被固定下來

OpenAI 的 Codex 與其當成單次對談對象，不如當成一位靠設定與作業規則持續合作的隊友，會比較穩。特別是有讓它讀 AGENTS.md 的流程時，與其每次口頭重複文字編碼的規則，不如常態化放在文件裡更有效。

本文整理 在 Windows 要讓 Codex 安全處理日文檔案時，最先建議給出的指示，以實務角度編排。

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 只要在某一次把編碼解讀錯，就可能 把看不懂的字串當成「看懂了」繼續進行下一步編輯。如果就這樣存下去，問題就從顯示層面升級成 檔案本身的毀損，而且會被固定住。

所以亂碼對策不是「能不能好好處理日文」的問題，而是 I/O 的流程該如何管理 的問題。

3. 一開始就該對 Codex 釘住的規則

3.1 讀之前要先確認 encoding 候選、BOM、換行

第一條規則：

讀或編輯可能含日文的既有檔案之前，要先判斷目前的 encoding 候選、是否有 BOM、換行符號，若有疑慮就不要直接進入內容解讀。

關鍵是把動作改成 「讀內容之前，先把檔案的前提看清楚」。

3.2 疑似亂碼的檔案，別帶著臆測儲存

這一條特別重要。

疑似亂碼時，調查階段採 read-only，在對 encoding 解讀沒把握前禁止覆寫。

人也一樣，不要儲存一個你還沒真的讀懂的檔案。「看起來有點壞，但大概就是這樣吧」就存下去，等於替事故定案。

3.3 既有檔案維持原狀，只有新建檔案才預設 UTF-8

在亂碼對策的脈絡下，出乎意料地危險的是「全部改成 UTF-8」。

最終把整個 repo 統一成 UTF-8，這個決策可能有，但 應當作獨立任務，按 diff 與影響範圍分別處理比較安全。日常修改下列運作較穩。

  • 編輯既有檔案時，維持原 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 / 換行事故、大量差異，視為異常回報

若目標檔案已經確定，再加一行會更穩：

目標檔案：<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.

這兩行特別有效。

6. NG 指示與 OK 指示

在亂碼對策上，指示的細度對結果影響很大。

NG 指示 OK 指示
幫我修亂碼 請先切分是檔案本身壞了，還是只有顯示端的問題，並且別帶著臆測直接儲存
全部改成 UTF-8 既有檔案請維持原 encoding，只有新增遵循 repo 規範採 UTF-8 系。既有的轉換另列為獨立任務
輸出一份 CSV 依既有運維的 encoding，寫入時明示 encoding，輸出後重新讀取日文欄位進行驗證
在能讀的範圍裡修 沒把握的地方不要儲存，把候選與根據一起回報
自己看著辦 不要擅自改動 BOM、換行、encoding；讓差異只剩業務變更

重點是在 動手前的確認 與 存檔後的驗證 都要寫清楚。

7. 審查時的 checklist

Codex 做完工作之後，人工這端固定幾個檢查點，整體會更穩。

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

亂碼對策的重點是：比起增加成功的 diff，更該早點煞住可疑的 diff。

8. 總結

在 Windows 讓 Codex 處理日文檔案時，最先見效的並不是把 PC 側配置弄到完美，而是 對 Codex 把文字編碼的作業流程講清楚。

特別要記住下列 5 點。

  • 讀之前要先確認 encoding / BOM / 換行
  • 疑似亂碼時，不要帶著臆測儲存
  • 既有檔案維持原狀，只有新建檔案向 UTF-8 系靠
  • 禁用模糊的寫入路徑
  • 存檔後重新讀取、驗證代表性日文行

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

亂碼對策不是「請你好好處理日文」這麼簡單的委託，而是 把「可以儲存的條件」和「必須停下的條件」都明文化。寫到這個程度，Codex 在 Windows 上就會變得好用很多。

9. 參考資料

相關文章

共用相同標籤的最新文章。能以相近的主題延伸理解。

相關主題

與本文相近的主題頁面。以本文為起點，可進一步連到相關服務與其他文章。

與本主題相關的服務

本文連結到以下服務頁面，歡迎從最接近的入口查看。

作者檔案

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

Go Komura

小村軟體有限公司 代表

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

聯絡我們
回到部落格一覽