昨天提到，Codex 的成果會受到上下文影響。

每次開啟新任務時，我都可以重新說明專案使用什麼技術、應該執行哪些測試，以及哪些功能不在範圍內。但只要漏掉一項，Codex 就可能採用不同的做法。

如果有些規則適用於這個 repository 的每一個任務，就可以把它們寫進 AGENTS.md。

什麼是 AGENTS.md？

AGENTS.md 是提供給 coding agent 閱讀的專案指令文件。

依照 OpenAI 官方文件，Codex 會在開始工作前尋找並讀取 AGENTS.md，讓每個任務可以從一致的專案規則開始。

它不是一段需要每次複製到 Prompt 的文字，也不是讓 Codex 記住所有舊對話的永久記憶。它是一個跟著 repository 版本控制、可以被團隊共同檢查與修改的檔案。

為什麼不全部寫在 Prompt？

假設之後每次都要提醒 Codex：

• 使用 npm，不要混用其他套件管理工具
• 修改完成後要執行測試與建置
• 不要自行加入新的正式環境套件
• 不要順便實作任務範圍外的功能

一直重複貼上不只麻煩，也可能在某次任務漏掉其中一條。

把穩定、會重複使用的規則放入 AGENTS.md 後，每次的 Prompt 就能專注描述當下要完成的功能。

AGENTS.md 和 README 有什麼不同？

兩者都在 repository 裡，但用途不同。

例如「使用 npm run dev 啟動專案」適合留在 README、「修改原始碼後必須執行哪些檢查」則適合寫進 AGENTS.md。

兩份文件可能會提到相同指令，但不需要把整份 README 再複製一次。

請 Codex 根據 repository 起草

目前專案還很小，但已經有套件設定、原始碼、測試與 README。與其自己憑印象填入指令，不如先請 Codex 從實際檔案整理出草稿。

今天使用的 Prompt 是：

目標：
請根據目前 Issue Tracker repository 的實際內容，在 repository 根目錄建立第一版 AGENTS.md。

請先閱讀：
- package.json
- README.md
- TypeScript、Vite、測試與 lint 相關設定
- src 目錄中的現有程式與測試

AGENTS.md 請包含：
1. 專案技術與主要目錄的簡短摘要
2. 套件管理、啟動、測試、lint 與建置指令
3. 能從現有程式確認的命名與程式風格
4. 修改範圍與禁止事項
5. 任務完成前的驗證清單

我明確指定的規則：
- 使用 npm，不要混用其他套件管理工具
- 不要自行加入後端、資料庫或登入功能
- 新增正式環境套件前先詢問
- 不要修改與目前任務無關的檔案
- 完成功能後執行相關測試與建置

限制：
- 只建立 AGENTS.md，不要修改其他檔案
- 只寫能由 repository 證實或由我明確指定的規則
- 不要猜測不存在的架構、指令或團隊慣例
- 保持精簡，避免重複 README 的專案介紹

完成後請說明每條規則的來源，並指出仍需要我確認的內容。

這個 Prompt 把內容分成兩種來源：

• Codex 可以從 repository 證實的事實
• 我身為專案負責人明確決定的協作規則

如果兩種來源都沒有提到，就不應該被寫成專案規則。

這段 prompt 的回覆和執行

這是我的 repo，在裡面的 commit 找到 "add AGENTS.md" 就是這篇文章寫完時的狀態。

規則也有作用範圍

今天的這個 AGENTS.md 要放在 repository 根目錄，讓它成為整個 Issue Tracker 專案的共同規則。

如果未來專案變大，也可以在子目錄放置更具體的 AGENTS.md。Codex 會從專案根目錄往目前工作目錄尋找指令，位置越接近正在處理的檔案，規則越具體；較接近目前目錄的指令可以覆蓋前面的內容。

目前專案規模不需要多層規則，一份根目錄的 AGENTS.md 就足夠了。

今日小結

今天替 Issue Tracker 建立了第一版 AGENTS.md，把每次任務都會重複使用的工作方式，變成 repository 裡可追蹤、可審查的專案指令。