[AI 分享] Codex AGENTS.md 實戰寫法

 [AI 分享] Codex AGENTS.md 實戰寫法

摘要 : 善用精簡的 AGENTS.md，可大幅提升 Codex 輸出品質與專案協作效率。

內容:

AGENTS.md 是一份提供給 Codex 的專案使用說明。每次 Codex 啟動時，都會自動讀取這個檔案，因此不需要手動貼上內容，也不需要每次重新說明專案規則。只要在終端輸入指定初始化指令，就能依照當前專案自動生成模板，再依需求進行修改即可。

可以把 AGENTS.md 理解成 Codex 的專案入門指南。若沒有這份檔案，Codex 每次都像剛加入專案的新手，無法快速掌握規則；有了它，Codex 一開始就知道專案怎麼執行、有哪些限制，以及提交前應遵守哪些流程，整體使用體驗會明顯提升。

撰寫 AGENTS.md 時，不建議把整份專案文件全部貼進去。因為它有 32KB 的長度限制，內容太多不但可能被截斷，還可能讓重要規則被忽略。最理想的做法，是把內容控制在十幾行內，只保留最關鍵、最具操作性的資訊。

建議優先寫五類內容。第一是專案執行方式，例如怎麼安裝依賴、怎麼跑測試、使用什麼包管理器與工具。第二是提交前必須完成的動作，例如 lint 與 test 必須全部通過。第三是禁止變更的內容，例如不要修改 ENV 檔案或既有 migration。第四是專案特殊約定，例如 commit message 格式、變數命名規則。第五是新增依賴的規矩，例如加入新的正式環境依賴前需要先確認。

撰寫時也要避開幾個常見問題。第一，不要只寫空泛態度，例如「請重視程式碼品質」，這類描述對 Codex 幾乎沒有實際幫助，應改成具體可執行的命令與步驟。第二，不要把它本來就能從專案中直接判斷的資訊重複寫進去，否則只會製造噪音。第三，不要寫完後就放著不管，因為專案規則會隨時間變動，應定期回頭檢查並刪除已經不必要的內容。

進階用法是分層管理。若專案屬於單一倉庫但包含多個服務，例如前端與後端採用不同技術棧，建議在根目錄放通用規則，再於各服務子目錄內建立各自的 AGENTS.md，分別定義專屬的測試命令與開發規範。Codex 會依所在目錄自動套用對應規則，而且越接近當前目錄的設定優先度越高。

另外，如果只是想暫時調整規則，又不想修改原本的 AGENTS.md，可以在同目錄新增 Agents Override MD。這樣就能臨時覆蓋原設定，刪除後即可恢復，使用上相當彈性方便。

總結來說，AGENTS.md 的重點不是寫得多，而是寫得準。只要內容精簡、明確、可執行，就能讓 Codex 更理解你的專案脈絡，進一步提升輸出品質與工作效率。