根目錄的 AGENTS.md：工程化寫法與維護紀律。
編者手記
AGENTS.md 是 agent 的可攜 context 層。
agents.md 是開放格式，Claude Code、Cursor、Codex、Copilot、Devin、Jules 都會讀它，與任何工具的私有設定無關。把專案知識寫進這份格式，換模型的成本從「重寫一份 prompt」降到零。
過時的 AGENTS.md 比沒有 AGENTS.md 更糟。
沒有 AGENTS.md，agent 會讀程式碼、詢問確認；有一份過時的 AGENTS.md，agent 會照著錯的規則執行。一條已被改掉的 build 指令、一個不再存在的目錄結構，會讓 agent 在錯誤前提上疊一整串動作。文件的權威性是雙面刃。
AGENTS.md 是導覽地圖，細節放 docs/。
AGENTS.md 只放理解專案必需的 context 與不可違反的硬規則，細節連結到
docs/與源碼。把所有細節塞進去的結果：重要規則被稀釋，agent 無法判斷優先序。
重點 摘要
從原貼文與 agents.md 規格提煉的五個觀念，供重寫 AGENTS.md 之前參照。
重點摘要
KEY TAKEAWAYS · 從原貼文與 agents.md 規格提煉
排名 01/05
x.com / @freeman1266 · 原貼文好的 AGENTS.md 讓換模型成本接近零
context 寫進開放格式，換 Claude / GPT / Gemini 不需重寫
老金原文：「好的 AGENTS.md 等於免費換模型」。agents.md 是開放規格，Claude Code、Cursor、Codex、Copilot、Devin 都讀同一份檔。把專案的建置流程、目錄結構、硬規則寫進這份文件，換工具或換底層模型的遷移成本接近零。把知識鎖在某個工具的私有設定裡，換工具時就要從頭重寫。
- ✓ 來自原貼文
- 開放格式
- 跨工具
- 零遷移成本
- /
- 05
- Source
- @freeman1266
- Format
- agents.md
- Adoption
- 60K+ repos
排名 02
x.com / @freeman1266 · 原貼文過時的 AGENTS.md 是負資產
agent 把過時規則當權威，在錯誤前提上疊一連串動作
老金原文：「寫錯了比沒文檔更糟」。沒有 AGENTS.md 時，agent 會讀程式碼、詢問確認；有一份過時或自相矛盾的 AGENTS.md 時，agent 把它當權威執行。一條已被改掉的 build 指令、一個不再存在的目錄樹，足以讓整個任務跑歪。不維護的 AGENTS.md 是負資產。
- ✓ 來自原貼文
- 負資產風險
- 需要維護
- Failure
- Stale rules
- Fix
- 持續同步
排名 03
cnkirito.moe · AGENTS.md 實踐指南AGENTS.md 指路：去哪裡找，而非怎麼做
漸進式披露：AGENTS.md 指引位置，細節放 docs/ 與源碼
依徐靖峰實踐指南：AGENTS.md 回答「去哪裡找」，細節放 docs/ 與源碼。把所有細節塞進去，重要規則反而被稀釋。私有元件或參考系統，用 git submodule 引入源碼，因為「源碼永遠不會過時」。
- 漸進式披露
- submodule 引用源碼
- ≈ 200 行上限
- Principle
- Map > Manual
- Detail
- → docs/
排名 04
cnkirito.moe · AGENTS.md 實踐指南每條規則需有對應的自動化腳本
沒有 lint / verify 的規則對 AI 和人類都缺乏強制力
一條寫在 AGENTS.md 裡、卻沒有對應 lint 腳本的規則，對 AI 和人類都缺乏強制力，執行結果不一致。文件要附上 build / start / test 的完整指令，讓 agent 寫完程式碼後能自行驗證，不必每次回報等待確認。優先寫「能被自動檢查的規則」，不要寫「靠人自覺的規則」。
- automation-first
- 驗證閉環
- CI gate
- Rule
- + lint script
- Loop
- build→start→test
排名 05
cnkirito.moe · AGENTS.md 實踐指南用 bad case 驅動更新
先寫夠用的版本上路，每次 AI 犯錯就補一條規則
不要在開工前把 AGENTS.md 寫到完美。先寫一份夠用的版本就上路，每次 AI 犯一次明顯的錯，就補一條對應規則。這讓 AGENTS.md 反映「這個專案上 AI 實際會踩的坑」，而不是憑空想像的清單。AGENTS.md 是活的文件，跟著專案演進。
- bad-case-driven
- 迭代式
- living doc
- Start
- 夠用就好
- Update
- 遇錯即補
步驟 拆解
原貼文說明觀點，本節提供操作流程。這六步依 agents.md 規格與徐靖峰實踐指南整理，供把 AGENTS.md 寫成工程文件使用。
步驟拆解
STEP-BY-STEP · 從骨架到驗證閉環 · 引用 agents.md 與社群實踐
排名 01/06
Step 01 · cnkirito.moe · 九大區塊骨架九個核心區塊骨架：從概覽到文件索引
依徐靖峰實踐指南：專案概覽、快速指令、架構、約定、驗證、品質、參考、導覽
徐靖峰提出的九段結構是好起點：① 專案概覽（一段話講清技術棧與目錄結構）② 快速指令（build / start / format / quality）③ 後端架構（ASCII 樹 + 用途註記）④ 前端架構（技術選型、路由、API 約定、元件規範）⑤ 關鍵約定（5–10 條硬規則）⑥ 本地開發與驗證（modify → build → start → verify）⑦ 品質檢查（lint / format / build / test 矩陣）⑧ 參考專案（外部 codebase + 查閱優先序）⑨ 文件導覽（repo 內詳細文件索引）。不必照搬，但這九題你都該回答。
- ✓ 可直接套用
- 9 區塊
- ASCII 目錄樹
- 文件索引
- /
- 06
- Blocks
- 9 Core
- Length
- ≈ 200 行
- Source
- cnkirito
排名 02
Step 02 · agents.md · 快速指令區塊快速指令區塊：可直接貼到終端機的單行命令
build / start / test / format，agent 自動執行
agents.md 規格說明：把 build 與 test 指令列進去，agent 會在完成任務前自動執行相關檢查並修正失敗。「快速指令」區塊要寫成可直接貼到終端機跑的單行命令，不要寫「執行測試」這類需要翻譯的描述句。一般放四條：安裝、啟動、格式化、品質檢查。
- copy-paste ready
- agent 自動執行
- 無歧義
- Form
- 單行命令
- Source
- agents.md
排名 03
Step 03 · cnkirito.moe · 關鍵約定關鍵約定：5–10 條硬規則
違反後果是「程式跑不起來或上線出包」的規則才放這裡
「關鍵約定」只放違反即出問題的規則，例如「所有 API 回應必須走 Result<T> 包裝」、「不要在 app/ 下放 server-only 程式碼」。控制在 5–10 條：太少漏重點，太多稀釋注意力。判準：違反的後果是「程式跑不起來或上線出包」，就放這裡；只是「看起來不太一致」，放到 docs/。
- 5–10 條
- 硬規則
- 紅線思維
- Count
- 5–10
- Test
- 違反 = 出錯
排名 04
Step 04 · cnkirito.moe · 驗證閉環驗證閉環：每條規則配一支可執行腳本
modify → build → start → verify，agent 自行跑完
在「本地開發與驗證」段寫出完整的改完 → 編譯 → 啟動 → 驗證流程，在「品質檢查」段給出 lint / format / build / test 的命令矩陣。有了這組命令，agent 寫完程式碼能自行驗證，不需要每次停下來等確認。把同一組命令接進 CI，PR 通過 gate 才能 merge。
- 驗證閉環
- 命令矩陣
- 接 CI gate
- Loop
- build→start→verify
- Then
- → CI
排名 05
Step 05 · agents.md · monorepo 巢狀檔monorepo：巢狀 AGENTS.md，就近覆寫
agent 自動讀目錄樹裡最近的那一份，子目錄規則勝出
agents.md 規格：在 monorepo 的子目錄放各自的 AGENTS.md，agent 自動讀目錄樹裡最近的那一份，最近的檔案優先。根目錄放整個 repo 的共通約定，packages/web/、services/api/ 各自再放一份子專案專屬規則。使用者在對話裡的明確指示優先序高於所有檔案。
- monorepo
- 巢狀檔
- 就近覆寫
- Scope
- root + 子目錄
- Source
- agents.md
排名 06
Step 06 · cnkirito.moe · 迭代與源碼即真相維護紀律：長度控制、迭代更新、源碼即真相
≈ 200 行上限，bad case 反向補規則，submodule 引參考專案
維護三條紀律：① 控制長度 ≈ 200 行，超過代表細節該搬去 docs/。② bad-case 驅動更新，每次 AI 犯錯就補一條對應規則。③ 源碼即真相，與其寫一段描述參考系統的文字，不如用 git submodule 把源碼拉進來，因為源碼不會過時。這三條讓 AGENTS.md 反映「現在這個專案實際會踩的坑」，不是憑空想像的清單。
- ≈ 200 行
- 迭代式維護
- submodule 引源碼
- Limit
- ≈ 200 行
- Update
- 遇錯即補
延伸 應用
一份工程化的 AGENTS.md 可服務多個場景：換工具的可攜性保障、新人 onboarding 入口、CI 的規格來源、開源貢獻者的操作地圖。
延伸應用
REAL-WORLD APPLICATIONS · 從跨模型遷移到開源維護
排名 01/06
Use Case · 跨模型／跨工具遷移換 agent 工具：context 不需重寫
Claude Code → Codex → Cursor → Gemini CLI，同一份 AGENTS.md 跟著走
這是老金原文的核心論點。專案知識沉澱在 agents.md 開放格式裡，換底層模型或換編碼工具時，新 agent 開箱就讀得到同一份規則，不需為每個工具另維護一份私有 prompt。某家工具漲價、改政策或停服時，遷移成本接近零。
- ✓ 兌現原貼文主張
- 抗鎖定
- 零遷移成本
- 開放格式
- /
- 06
- Audience
- 所有開發者
- Risk
- vendor lock-in ↓
- Cost
- ≈ 0 遷移
排名 02
Use Case · 團隊 onboarding新人 onboarding：一份檔跑通環境
快速指令與驗證閉環對人類工程師同樣適用
「改完 → 編譯 → 啟動 → 驗證」流程和 lint / build / test 命令矩陣，新工程師第一天照著操作即可把專案跑起來，不需到處詢問環境設定。AGENTS.md 與 agent 共用同一份事實來源，維護者有動機保持它最新。
- 新人上手
- 環境地獄 ↓
- 人機共用
- Audience
- 新進工程師
- Win
- Day-1 跑通
排名 03
Use Case · monorepo 多專案治理monorepo 分層治理：root + 子目錄各一份
root 放全域約定，子目錄放框架專屬規則
大型 monorepo 裡，前端、後端、infra 的規則不同。利用 agents.md 的巢狀檔機制，agent 自動讀最近的那一份。root 放 commit 規範、CI 流程這類全域約定，apps/web/、services/api/ 各自再放框架專屬規則。新增子專案時加一份檔，根目錄那份不會越養越肥。
- monorepo
- 分層治理
- 就近覆寫
- Audience
- 平台團隊
- Scope
- root + N 子檔
排名 04
Use Case · CI gate 的規格來源AGENTS.md 的品質檢查段 = CI pipeline 的 single source
文件、agent、CI 讀同一組命令，規則從希望遵守變成 gate
AGENTS.md 裡每條硬規則對應一支可執行腳本，這組腳本同時掛在 CI 上。文件、agent、CI 三者讀同一組命令：agent 寫完自行驗證，PR 跑同一套檢查，人類照同一份清單 review。規則不再是「希望大家遵守」，而是「通不過就 merge 不進去」。
- CI / CD
- single source
- 強制力
- Audience
- DevOps / Lead
- Effect
- 規則 = gate
排名 05
Use Case · 開源專案的貢獻者入口開源貢獻者入口：降低首次 PR 的門檻
60K+ 開源專案已採用 agents.md 格式
常見問題：「PR 來了，但作者沒跑測試、不懂專案慣例」。一份清楚的 AGENTS.md 讓第一次貢獻的人照著把環境裝好、跑通檢查、按慣例提交。使用 AI 工具的貢獻者，其 agent 會自動讀 AGENTS.md 並修正檢查失敗。維護者收到的 PR 品質提升。把參考實作用 git submodule 引入，貢獻者不需猜測應照哪個範例。
- OSS 維護
- 貢獻者地圖
- PR 品質 ↑
- Audience
- OSS 維護者
- Adopters
- 60K+ repos
排名 06
Use Case · 讓 agent 跑完整閉環驗證閉環的實際效益：減少來回等待
agent 寫完自行驗證，回報時已是綠燈狀態
沒有驗證閉環時，agent 寫完程式碼會停下來問「build 指令是什麼」；有了它，agent 寫完直接跑 build → start → test，失敗自行修復，回報時已是綠燈狀態。每個任務減少兩三次來回，agent 從「輔助寫程式碼」進展到「能完成完整交付」。
- autonomous loop
- 少來回
- 交付率 ↑
- Audience
- 日常開發者
- Win
- 綠燈才回報
四種場景的行動計畫
行動計畫
個人開發者、工程團隊、開源維護者、工具選型者，各有不同的切入點。以下依角色給出具體操作步驟。
01 · 個人開發者 · SOLO
從最小可用版本開始，按錯誤迭代
先放四件事：專案一句話說明、build / start / test 三條單行指令、3–5 條硬規則。之後每次 AI 犯一次明顯的錯，補一條對應規則。控制在 200 行內，超過把細節搬去 docs/。
02 · 工程團隊 · TEAM
九區塊骨架 + 自動化腳本
依九段結構（概覽 / 指令 / 後端 / 前端 / 約定 / 驗證 / 品質 / 參考 / 導覽）建骨架。每條規則對應一支 lint / test 腳本，並把這組命令同時掛上 CI。文件、agent、pipeline 讀同一份命令，規則從「希望遵守」變成「通不過就 merge 不進去」。
03 · 開源維護者 · OSS
把它當貢獻者操作地圖來寫
AGENTS.md 說明環境安裝、檢查指令、提交慣例。用 git submodule 把參考實作的源碼拉進來，因為源碼不會過時。使用 AI 工具的貢獻者，其 agent 自動讀 AGENTS.md 並修正檢查失敗，你收到的 PR 品質提升。
04 · 工具選型 · PORTABILITY
把 agents.md 開放格式當作抗鎖定的基礎建設
把專案知識寫進 agents.md 開放格式，不要寫進某個工具的私有設定。Claude Code、Cursor、Codex、Copilot、Devin 都讀同一份檔。換工具、換底層模型或某家工具停服時，遷移成本接近零。