讓 Codex 更懂你的意圖、
專案與工作習慣
把穩定偏好放在全域，把專案背景放在 repo，編目重要參考文件，必要時再用搜尋或 MCP 做檢索。理解 RAG 原理，學會讓 Codex 讀對文件、標出引用依據，並同步跨專案知識。
120 分鐘安排
先選對客製化工具
穩定且每次任務都適用的程式慣例、測試命令、資料限制和審查規則。
多步驟、重複出現的工作流程，附上範本、腳本或參考資料。
把 Codex 接到即時外部資料或動作；需要考慮身份驗證、權限和信任。
AGENTS.md 怎麼被套用？
Codex 會從全域設定和目前專案路徑尋找指示，並把沿途規則合併。較接近目前工作的子目錄規則可補充更具體要求；存在 override 檔時也會影響同層規則。指示檔有合併大小限制，長篇流程不該全部塞在根檔。
~/.codex/AGENTS.md 放跨 repo 個人偏好；Memories 是可選的個人回想層，不取代持久規則。
產品背景、共同命令、架構慣例、安全界線和參考文件索引。
特定 package 或 team 的局部規則。
RAG：不是把所有文件塞進去，而是按任務取回依據
RAG（檢索增強生成）先從外部資料找出與目前問題相關的內容，再把片段加入這次模型脈絡，讓回答根據來源生成。開發情境的來源可以是需求、ADR（架構決策紀錄）、API 規格、設計系統、事故報告或程式範例。
用 docs/INDEX.md 列出要做哪種任務該讀哪些文件。AGENTS.md 說明先看索引、按任務挑選，並回報引用路徑。這是成本低且容易除錯的 RAG 起點。
文件很多或常變動時，才考慮全文／向量搜尋或 MCP 知識服務。要求回傳文件標題、版本、原始連結和相關片段。
怎麼讓 Codex 更懂你的意圖、背景和習慣？
使用者是誰、主要任務是什麼、怎樣算成功；寫清楚已知取捨與未決問題。
模組邊界、資料流、架構決策、相容性要求和不採用某方案的原因；連到 ADR 或系統圖。
真實 build/test 命令、命名、錯誤處理、審查重點；以好的程式範例說明，不只寫「保持乾淨」。
慣用語言、回覆長度、先探索或先詢問、是否先出計畫。跨專案偏好放全域檔，專案例外留在 repo。
不可新增依賴、不可改公開 API、不可用生產資料等；未知時要問什麼、不能猜什麼。
重複糾正的穩定習慣才寫成規則；一次性偏好不要變成全域要求。
指定 Codex 讀取並引用你提供的參考檔
做一份參考文件索引，明確標註適用任務、權威順位、版本和更新日期。任務開始時要求 Codex 先讀索引，只取回與本次變更相關的來源；文件衝突時列出原句與路徑，請你裁決。把引用路徑和章節納入最後交付格式。
全域使用、跨專案共用和同步方式
~/.codex/AGENTS.md 放你跨 repo 的工作偏好；~/.agents/skills/ 放通用流程。可用私有 dotfiles Git repo 備份，在新機器安裝到對應位置。不要同步 token、session 或機器專屬絕對路徑。
把 AGENTS.md、docs 和 repo Skills 放在同一 Git repo，讓 PR 審查變更與歷史。巢狀指示只放目錄特有規則。這是專案知識最直接的同步方式。
建立版本化 engineering-playbook repo。各專案用 Git submodule 固定版本，或用同步腳本選擇性複製至 docs/references；索引註明來源 commit／版本，並定期檢查漂移。
資料散落多系統且常更新時，考慮 MCP 知識服務。按使用者權限搜尋，回傳來源連結與版本。不要把私有文件索引開放給無權限的工作區。
同步策略抽選
私有 dotfiles repo 管理全域規則與 Skills；新電腦 clone 後安裝。先檢查同步內容，秘密資訊交由 secret manager。
Skill 和 MCP 的邊界
每週資料匯入是重複流程：檢查欄位 → 正規化 → 去重 → 驗證筆數 → 匯出差異摘要。把 SOP、範本與必要腳本封裝成 Skill，讓任務按同樣步驟完成。
Skill 不是服務帳號，也不會自帶權限；它提供工作流程說明和相關資源。
建立一份有效的 AGENTS.md
- 挑一個 repo，問 Codex 哪些操作規則目前未知、哪些模式重複出現。
- 你確認真實命令和規範後，只選 5–8 條最有影響的規則。
- 放入根層 AGENTS.md：用途、建置 / 測試命令、風格、資料界線、交付格式。
- 如果某子目錄有特殊規則，再建置局部指示；避免重複和互相矛盾。
- 開一個新 Codex session，要求它摘要已載入規則，並用一個小任務驗證。
- 發現規則太長或互相衝突時，先精簡與排序再增加內容。
把一次工作教訓轉成 Skill 的判準：同樣流程已重複多次、輸入和輸出穩定，而且未來能讓別人使用。