CLAUDE.md 與 AGENTS.md：把 AI 協作規則寫在對的位置

01／範圍

同一條規則，不一定要讓所有任務都看到

CLAUDE.md 與 AGENTS.md 目的相近，但載入與優先順序依工具而異。共通原則是：規則越接近實際工作的目錄，作用範圍越精準。

U 使用者

個人長期偏好

語言、回覆格式、個人工作習慣。只放你跨專案都會使用的規則。

P 專案

專案共同規則

測試指令、商業邏輯、完成標準，以及整個團隊都必須知道的連動關係。

N 巢狀

資料夾專屬規則

例如前端視覺驗收或資料層遷移規則，只在相關目錄工作時加入。

提醒：Claude Code 與 Codex 的檔名、搜尋路徑與優先順序不同，導入前應以各自官方文件為準。

02／編輯

先做減法，再做加法

/init 可以產生起始版本，但它不是完成品。自動生成後，應逐條判斷是否真的值得每次都送進代理的工作脈絡。

刪除前，問三題

代理能從程式碼、README 或既有文件自行找到嗎？
這條規則和多數工作都有關，還是只屬於一個資料夾或單次任務？
三個月後它仍然會是正確的嗎？

新增前，問五題

這是 AI 無法推得的非協商規則嗎？
是否有固定流程或唯一可信來源？
是否存在容易漏掉、必須一起修改的檔案？
完成工作前，必須跑哪些檢查？
遇到問題時，應該去哪一份文件找答案？

03／路由

別把所有知識都塞進同一份檔案

判斷資訊放哪裡，比文字寫得多漂亮更重要。以下四條路徑，可以避免指令檔變成又長、又難維護的規則倉庫。

AI 自己找得到

→

程式／文件

讓代理需要時再讀，不必每次載入。

短、長期、不可推得

→

CLAUDE.md／AGENTS.md

專案不成文規則、連動關係、測試與完成標準。

長而有條件的流程

→

技能／操作手冊

只有任務符合時才載入完整步驟。

絕對不能違反

→

掛鉤／提交前檢查／CI

用程式化檢查阻擋錯誤，不只依賴文字提醒。

04／建置

建立第一版：五步就夠

第一版的目標不是完整，而是建立一個短、可信、能被驗證的起點。

產生起點

Claude Code 可用 /init 掃描專案並產生起始內容。

移除常識

刪掉檔案樹、套件列表與其他代理能自行發現的資訊。

縮小範圍

資料夾專屬規則移到更靠近實際工作的子目錄規則檔。

分流流程

長流程移至技能；安全底線移至 Hook、pre-commit 或 CI。

跑一次驗證

交給代理做真實小任務，檢查規則是否有幫助或衝突。

05／範例

好的指令檔，看起來通常很短

以下範例刻意只保留代理不容易從程式碼自行理解的規則與驗收條件。

五行規則，勝過五頁背景

每一行都應回答一個實務問題：什麼不能錯、哪些地方會連動、完成前要做什麼，以及長流程去哪裡找。

若同時使用 Claude Code 與 Codex，可選一份共同規則作為唯一可信來源，再依工具支援的方式匯入或引用，避免兩份檔案逐漸分歧。

# Project instructions
- Run `npm test` before reporting completion.
- Prices shown to users include tax.
- Update checkout copy and receipt templates together.
- For releases, follow `skills/release/SKILL.md`.
- Never commit secrets; pre-commit scanning is mandatory.

06／維護

把規則當成會變動的產品

新增規則只是維護的一半；另一半是刪除已經被工具、程式碼或流程取代的舊規則。

觀察重複失誤

只記錄反覆出現、真正造成成本的問題。

判斷正確層級

專案、子目錄、技能還是程式化檢查？

用任務驗證

確認新規則真的改變行為，且沒有製造衝突。

定期修剪

模型、架構或流程改變時，移除過時內容。

07／驗證

三個容易被舊資訊誤導的地方

AI 程式設計工具更新很快。教材保留影片的核心方法，但版本相關細節以官方文件為準。

不是完全同一套規則

CLAUDE.md 與 AGENTS.md 用途相近，但搜尋路徑、載入順序與覆寫方式不同。不能只改檔名就假設行為完全一致。

私人偏好改用匯入

Anthropic 官方文件已將 CLAUDE.local.md 標示為已淘汰；目前建議使用 @path/to/file 匯入不提交到版本控制的個人檔案。

功能指令先查現行文件

斜線指令、模型名稱與內建分析功能會隨版本變動。採用前先查官方文件，不把影片中的版本名稱寫成長期規則。

把 AI 協作規則，寫在對的位置。