AI 建立 / 審查 AGENTS.md
兩種模式：建立新的 AGENTS.md，或根據以研究為基礎的品質標準審查現有的 AGENTS.md。
模式偵測
- 使用者提供現有的 AGENTS.md，或指向某個路徑 → 審查模式
- 使用者要求建立/生成/產生骨架 → 建立模式
- 不明確時 → 詢問：
(c) 建立新的 AGENTS.md 還是 (r) 審查現有的？
建立模式
步驟 1：詢問放置位置
AGENTS.md 應放置於何處？
(r) 根目錄 — 整個倉庫的基準
(p) 路徑 — 特定目錄（提供路徑）
對於單體倉庫：建議根目錄 + 每個套件各一個檔案。以最近的 AGENTS.md 為準。
如果目標路徑已存在 AGENTS.md → 詢問：檔案已存在。(r) 審查現有檔案 / (o) 覆寫 / (Q) 離開？
步驟 2：專家思考
在開始撰寫之前，針對此專案判斷：
- 什麼是無法發現的？ 哪些事項無法從 package.json、組態檔或目錄結構中推斷出來？
- 什麼是危險的？ 哪些指令或模式會導致無聲失敗？
- 什麼是模糊的？ 哪些情況存在兩種有效做法，且代理程式可能會猜錯？
- 什麼是非標準的？ 哪些慣例與框架預設值不同？
如果所有答案都是「無」— 則該專案可能不需要 AGENTS.md。請如實告知。
對於沒有 package.json 或建置組態的倉庫（僅文件、資料倉庫、簡單腳本）：只專注於使命 + 判斷邊界 — 工具鏈和閉包章節不適用。
步驟 3：按優先順序撰寫
僅在通過「無法發現」測試時才加入章節，順序如下：
- 使命（2–4 句）— 專案目的 + 代理程式無法推斷的核心限制
- 工具鏈登錄 — 以表格形式呈現的指令，而非工具強制執行的規則
- 判斷邊界 — 永不 / 詢問 / 一律 三個層級
- 閉包定義 — 「完成」= 特定的結束碼
- 升級規則 — 卡住時該怎麼辦
- 任務組織章節 — 「當撰寫…時 / 當審查…時 / 當發布…時」
步驟 4：驗證
- 總行數 ≤ 150 行（最佳：60–100）
- 每個章節 ≤ 50 行
- 每條指令都回答：「哪個指令可以證明這件事已完成？」
- 每個「禁止」都搭配一個「請使用」
- 不重複 lint 規則（工具鏈優先）
- 不含沒有指令的散文段落
強制 — 閱讀 references/knowledge-base.md 以取得有研究依據的模式和證據。
強制 — 閱讀 references/template.md 以取得入門結構。
僅在使用者詢問完整的 AGENTS.md 看起來如何時，或倉庫是 JS/TS 單體倉庫（這是 turborepo + pnpm 的實作範例）時才載入 references/example.md — 否則跳過。
審查模式下，如果目標 AGENTS.md 少於 20 行，請勿載入 references/knowledge-base.md — 對於極短的檔案，主體檢查清單和反模式清單就已足夠。
審查模式
根據以研究為基礎的品質標準評估所提供的 AGENTS.md。
評分維度
| 維度 | 權重 | 檢查項目 |
|---|---|---|
| 訊號密度 | 25% | 屬於無法發現的專家知識而非通用/重複內容的行數比例 |
| 命令優先 | 20% | 每條指令都附有可驗證的命令或結束碼 |
| 閉包定義 | 15% | 明確的「完成」標準，並帶有具體檢查 |
| 邊界系統 | 15% | 存在且具體的 永不/詢問/一律 三個層級 |
| 長度紀律 | 10% | 總行數 ≤150，每章節 ≤50，無冗贅 |
| 反模式缺失 | 15% | 無經證實會失敗的模式 |
評分指引
- 對於已成熟的倉庫且擁有完善的工具鏈，在訊號密度上要嚴格打分 — 大多數內容可能是重複的
- 對於全新專案，在閉包/邊界上要寬鬆打分 — 它們可能還沒有 CI 閘道
- 對於單體倉庫的根目錄檔案，在長度上要嚴格打分 — 這些檔案會在每次工作階段中載入，跨越所有套件
- 如果總分 < 40 分：建議重寫而非逐步修正
反模式檢查清單
標記任何以下項目（經實證會損害代理程式效能）：
- 不含指令的散文段落
- 模糊的指示（「小心」、「儘可能」）
- 沒有明確排序的互相矛盾優先級
- lint 組態已強制執行的樣式規則
- 架構總覽（導致過度探索）
- 15 條以上的警告，但沒有提供替代方案
- 來自
/init指令的 LLM 生成的樣板 - 轉述工具鏈已強制執行的規則
- 粉紅大象違規（冗長的「禁止」清單讓被禁止的概念保持活躍）
輸出格式
## AGENTS.md 審查：<檔名或路徑>
**分數**：X/100
**評語**：[已可上線 / 需要改進 / 建議重寫]
### 優點
- ...
### 問題（依嚴重程度排序）
1. [嚴重] ...
2. [高] ...
3. [低] ...
### 重寫建議
1. ...
2. ...
套用
審查本身並非最終產出 — 更好的 AGENTS.md 才是。呈現審查結果後，提供：
套用？(a) 全部 / (s) 依編號選取 / (n) 不要
對於 (a) 或 (s)：逐一修改檔案（依編號項目），然後重新執行評分維度，並報告新分數與舊分數。未被審查標記的每一行都原封不動保留 — 審查不是重寫命令，默默地「改善」未標記的散文段落會破壞作者的原意和風格。
當使用者以內嵌方式提供內容而非路徑，或檔案不可寫入時，請跳過此提議。說明原因，而不是報告改善事項已套用。
強制 — 閱讀 references/knowledge-base.md 以取得每個標準背後的研究證據。
永不
- 永不包含代理程式可從倉庫結構發現的內容 — package.json 的腳本、目錄佈局和組態檔案都是不言自明的；重複它們會浪費 token 並造成維護漂移。請改為： 引用檔案（
請參閱 biome.json）然後繼續。 - 永不重述 linter/formatter 規則 — 工具本身就是限制；重複會造成過時，且不必要的需求會主動損害代理程式的效能。請改為： 只列出執行指令（
Lint: \pnpm lint``）。 - 永不撰寫沒有搭配「請使用」的「禁止」 — 僅有警告的文件會導致過度探索；超過 15 條的「禁止」而沒有替代方案會使代理程式變得保守且生產力降低。請改為： 將每條禁止事項都與正確的替代方案配對。
- 永不超過 150 行 — 超過此門檻，效益會反轉，且檔案會主動損害品質。請改為： 將細節提取到被引用的檔案中，或刪除。
- 永不將 LLM 生成的內容作為最終版本 —
/init的輸出是代理程式已知事項的清單；它會降低效能並增加成本。請改為： 將其視為草稿清單，然後刪除工具鏈已強制執行的所有內容。 - 永不撰寫散文段落 — 代理程式會跳過它們；請使用指令、表格和帶有可驗證結果的要點。請改為： 轉換為「指令 + 結束碼 + 一行說明」。