推文教學 · AGENTS.md 工程化

推文教學 · @freeman1266 · 2026 年 5 月

Tweet Tutorial · 推文教學 AGENTS.md 工程化：可攜 context 層的寫法與維護紀律。寫對等於免費換模型，寫錯是負資產。

@freeman1266（老金）以三張圖卡說明：「好的 AGENTS.md 等於免費換模型，寫錯了比沒文檔更糟」。Tenten 把這個觀點依核心觀念、實作步驟、延伸應用三段展開，引用 agents.md 開放規格與社群實踐補齊細節，整理成可直接照做的工程化流程。

推文格式

Visual / 3 圖卡

原貼文以三張視覺圖卡呈現，主題為「AGENTS.md 工程化」。

回覆互動

4 Replies

x.com 統計，截至 Tenten 編譯時點。原貼文持續累積中。

發布日期

2026/05/09

UTC 10:13。發布於 AGENTS.md 跨工具採用快速擴散的時間點。

標準採用

60K+ Repos

agents.md 規格頁宣稱逾 6 萬個開源專案採用，跨 Claude、Cursor、Codex、Copilot、Devin 等。

01 / 編者手記 FROM THE EDITOR · MAY 2026

根目錄的 AGENTS.md：工程化寫法與維護紀律。

編者手記 EDITOR'S NOTE

多數人把 AGENTS.md 當成「寫一次就放著」的 README 附屬品。當 agent 照著它工作，過時或矛盾的規則會把任務帶歪。不維護的 AGENTS.md 是負資產。Tenten 把這個觀點接上 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 無法判斷優先序。

02 / 重點摘要 KEY TAKEAWAYS · 從原貼文與 agents.md 規格提煉

重點摘要

從原貼文與 agents.md 規格提煉的五個觀念，供重寫 AGENTS.md 之前參照。

5 Takeaways
Portable · Authoritative · Map
Source: @freeman1266

01^/05

x.com / @freeman1266 · 原貼文

好的 AGENTS.md 讓換模型成本接近零

context 寫進開放格式，換 Claude / GPT / Gemini 不需重寫

老金原文：「好的 AGENTS.md 等於免費換模型」。agents.md 是開放規格，Claude Code、Cursor、Codex、Copilot、Devin 都讀同一份檔。把專案的建置流程、目錄結構、硬規則寫進這份文件，換工具或換底層模型的遷移成本接近零。把知識鎖在某個工具的私有設定裡，換工具時就要從頭重寫。

✓ 來自原貼文開放格式跨工具零遷移成本

Source @freeman1266 Format agents.md Adoption 60K+ repos

x.com / @freeman1266 · 原貼文

過時的 AGENTS.md 是負資產

agent 把過時規則當權威，在錯誤前提上疊一連串動作

老金原文：「寫錯了比沒文檔更糟」。沒有 AGENTS.md 時，agent 會讀程式碼、詢問確認；有一份過時或自相矛盾的 AGENTS.md 時，agent 把它當權威執行。一條已被改掉的 build 指令、一個不再存在的目錄樹，足以讓整個任務跑歪。不維護的 AGENTS.md 是負資產。

✓ 來自原貼文負資產風險需要維護

Failure Stale rules Fix 持續同步

cnkirito.moe · AGENTS.md 實踐指南

AGENTS.md 指路：去哪裡找，而非怎麼做

漸進式披露：AGENTS.md 指引位置，細節放 docs/ 與源碼

依徐靖峰實踐指南：AGENTS.md 回答「去哪裡找」，細節放 docs/ 與源碼。把所有細節塞進去，重要規則反而被稀釋。私有元件或參考系統，用 git submodule 引入源碼，因為「源碼永遠不會過時」。

漸進式披露 submodule 引用源碼 ≈ 200 行上限

Principle Map > Manual Detail → docs/

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

cnkirito.moe · AGENTS.md 實踐指南

用 bad case 驅動更新

先寫夠用的版本上路，每次 AI 犯錯就補一條規則

不要在開工前把 AGENTS.md 寫到完美。先寫一份夠用的版本就上路，每次 AI 犯一次明顯的錯，就補一條對應規則。這讓 AGENTS.md 反映「這個專案上 AI 實際會踩的坑」，而不是憑空想像的清單。AGENTS.md 是活的文件，跟著專案演進。

bad-case-driven 迭代式 living doc

Start 夠用就好 Update 遇錯即補

03 / 步驟拆解 STEP-BY-STEP · 從骨架到驗證閉環 · 引用 agents.md 與社群實踐

步驟拆解

原貼文說明觀點，本節提供操作流程。這六步依 agents.md 規格與徐靖峰實踐指南整理，供把 AGENTS.md 寫成工程文件使用。

6 Steps
Skeleton · Rules · Loop
Refs: agents.md / cnkirito

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 目錄樹文件索引

Blocks 9 Core Length ≈ 200 行 Source cnkirito

Step 02 · agents.md · 快速指令區塊

快速指令區塊：可直接貼到終端機的單行命令

build / start / test / format，agent 自動執行

agents.md 規格說明：把 build 與 test 指令列進去，agent 會在完成任務前自動執行相關檢查並修正失敗。「快速指令」區塊要寫成可直接貼到終端機跑的單行命令，不要寫「執行測試」這類需要翻譯的描述句。一般放四條：安裝、啟動、格式化、品質檢查。

copy-paste ready agent 自動執行無歧義

Form 單行命令 Source agents.md

Step 03 · cnkirito.moe · 關鍵約定

關鍵約定：5–10 條硬規則

違反後果是「程式跑不起來或上線出包」的規則才放這裡

「關鍵約定」只放違反即出問題的規則，例如「所有 API 回應必須走 Result<T> 包裝」、「不要在 app/ 下放 server-only 程式碼」。控制在 5–10 條：太少漏重點，太多稀釋注意力。判準：違反的後果是「程式跑不起來或上線出包」，就放這裡；只是「看起來不太一致」，放到 docs/。

5–10 條硬規則紅線思維

Count 5–10 Test 違反 = 出錯

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

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

Step 06 · cnkirito.moe · 迭代與源碼即真相

維護紀律：長度控制、迭代更新、源碼即真相

≈ 200 行上限，bad case 反向補規則，submodule 引參考專案

維護三條紀律：① 控制長度 ≈ 200 行，超過代表細節該搬去 docs/。② bad-case 驅動更新，每次 AI 犯錯就補一條對應規則。③ 源碼即真相，與其寫一段描述參考系統的文字，不如用 git submodule 把源碼拉進來，因為源碼不會過時。這三條讓 AGENTS.md 反映「現在這個專案實際會踩的坑」，不是憑空想像的清單。

≈ 200 行迭代式維護 submodule 引源碼

Limit ≈ 200 行 Update 遇錯即補

04 / 延伸應用 REAL-WORLD APPLICATIONS · 從跨模型遷移到開源維護

延伸應用

一份工程化的 AGENTS.md 可服務多個場景：換工具的可攜性保障、新人 onboarding 入口、CI 的規格來源、開源貢獻者的操作地圖。

6 Scenarios
Portability · Onboarding · CI
Engineering-First

01^/06

Use Case · 跨模型／跨工具遷移

換 agent 工具：context 不需重寫

Claude Code → Codex → Cursor → Gemini CLI，同一份 AGENTS.md 跟著走

這是老金原文的核心論點。專案知識沉澱在 agents.md 開放格式裡，換底層模型或換編碼工具時，新 agent 開箱就讀得到同一份規則，不需為每個工具另維護一份私有 prompt。某家工具漲價、改政策或停服時，遷移成本接近零。

✓ 兌現原貼文主張抗鎖定零遷移成本開放格式

Audience 所有開發者 Risk vendor lock-in ↓ Cost ≈ 0 遷移

Use Case · 團隊 onboarding

新人 onboarding：一份檔跑通環境

快速指令與驗證閉環對人類工程師同樣適用

「改完 → 編譯 → 啟動 → 驗證」流程和 lint / build / test 命令矩陣，新工程師第一天照著操作即可把專案跑起來，不需到處詢問環境設定。AGENTS.md 與 agent 共用同一份事實來源，維護者有動機保持它最新。

新人上手環境地獄 ↓ 人機共用

Audience 新進工程師 Win Day-1 跑通

Use Case · monorepo 多專案治理

monorepo 分層治理：root + 子目錄各一份

root 放全域約定，子目錄放框架專屬規則

大型 monorepo 裡，前端、後端、infra 的規則不同。利用 agents.md 的巢狀檔機制，agent 自動讀最近的那一份。root 放 commit 規範、CI 流程這類全域約定，apps/web/、services/api/ 各自再放框架專屬規則。新增子專案時加一份檔，根目錄那份不會越養越肥。

monorepo 分層治理就近覆寫

Audience 平台團隊 Scope root + N 子檔

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

Use Case · 開源專案的貢獻者入口

開源貢獻者入口：降低首次 PR 的門檻

60K+ 開源專案已採用 agents.md 格式

常見問題：「PR 來了，但作者沒跑測試、不懂專案慣例」。一份清楚的 AGENTS.md 讓第一次貢獻的人照著把環境裝好、跑通檢查、按慣例提交。使用 AI 工具的貢獻者，其 agent 會自動讀 AGENTS.md 並修正檢查失敗。維護者收到的 PR 品質提升。把參考實作用 git submodule 引入，貢獻者不需猜測應照哪個範例。

OSS 維護貢獻者地圖 PR 品質 ↑

Audience OSS 維護者 Adopters 60K+ repos

Use Case · 讓 agent 跑完整閉環

驗證閉環的實際效益：減少來回等待

agent 寫完自行驗證，回報時已是綠燈狀態

沒有驗證閉環時，agent 寫完程式碼會停下來問「build 指令是什麼」；有了它，agent 寫完直接跑 build → start → test，失敗自行修復，回報時已是綠燈狀態。每個任務減少兩三次來回，agent 從「輔助寫程式碼」進展到「能完成完整交付」。

autonomous loop 少來回交付率 ↑

Audience 日常開發者 Win 綠燈才回報

想讓 AI agent 真的能在你的 codebase 上交付？

AGENTS.md 寫好了，
把 agent 接進正式 pipeline，
是 Tenten 在做的事。

Tenten 是 AI-First 設計與技術顧問公司。我們把 Claude、MCP、AI coding agent 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 從 AGENTS.md 工程化、驗證閉環、到 CI gate，讓 agent 不只是「輔助」，而是能在你正式上線的 codebase 上穩定交付。

預約 30 分鐘諮詢 → Tenten Awesome List

Tenten 如何部署這些 Skills

Skills 架構諮詢

依團隊與堆疊選出適配 skills，建立 OpenClaw 路由與 CI/CD 部署流程。

Claude Design System Sprint

兩週固定價格，接上 frontend-design + brand-guidelines 到 production。

Agentic Commerce Build

Shopify Plus / Webflow / Headless 遷移，搭配 Claude + MCP 營運層。

根目錄的 AGENTS.md：工程化寫法與維護紀律。

AGENTS.md 是 agent 的可攜 context 層。

過時的 AGENTS.md 比沒有 AGENTS.md 更糟。

AGENTS.md 是導覽地圖，細節放 docs/。

重點 摘要

好的 AGENTS.md 讓換模型成本接近零

過時的 AGENTS.md 是負資產

AGENTS.md 指路：去哪裡找，而非怎麼做

每條規則需有對應的自動化腳本

用 bad case 驅動更新

步驟 拆解

九個核心區塊骨架：從概覽到文件索引

快速指令區塊：可直接貼到終端機的單行命令

關鍵約定：5–10 條硬規則

驗證閉環：每條規則配一支可執行腳本

monorepo：巢狀 AGENTS.md，就近覆寫

維護紀律：長度控制、迭代更新、源碼即真相

延伸 應用

換 agent 工具：context 不需重寫

新人 onboarding：一份檔跑通環境

monorepo 分層治理：root + 子目錄各一份

AGENTS.md 的品質檢查段 = CI pipeline 的 single source

開源貢獻者入口：降低首次 PR 的門檻

驗證閉環的實際效益：減少來回等待

四種場景的行動計畫

從最小可用版本開始，按錯誤迭代

九區塊骨架 + 自動化腳本

把它當貢獻者操作地圖來寫

把 agents.md 開放格式當作抗鎖定的基礎建設

AGENTS.md 寫好了， 把 agent 接進 正式 pipeline， 是 Tenten 在做的事。

重點摘要

步驟拆解

延伸應用

AGENTS.md 寫好了，
把 agent 接進正式 pipeline，
是 Tenten 在做的事。