agents-md

維護 AGENTS.md

目標：簡潔、可操作的代理指令。目標少於 60 行；絕不超過 100 行。

工作流程

1. 撰寫前檢查：
   • 套件管理器：鎖定檔案與清單
   • 指令：package.json、Makefile、任務執行器、CI 工作流程
   • 文件/規格/政策：README.md、CONTRIBUTING.md、docs/、specs/、policies/、SECURITY.md、.github/
   • 慣例：當前程式碼模式、測試佈局、產生的檔案、應避免的舊有區域
2. 選擇範圍：
   • 根目錄 AGENTS.md：儲存庫範圍的預設值
   • 巢狀 AGENTS.md：僅當子目錄有不同指令或規則時
   • 最近的指令檔案優先；保持較窄的檔案比根目錄檔案更短
3. 撰寫最小可用的檔案。
4. 驗證確切路徑和指令存在。

檔案設定

• 在儲存庫根目錄建立 AGENTS.md。
• 如果需要 Claude 相容的進入點，將 CLAUDE.md 符號連結到 AGENTS.md。
• 不要維護分歧的 AGENTS.md 和 CLAUDE.md 副本。

預設章節

僅使用能增加非顯而易見價值的章節。

# 代理指令

## 套件管理器
- 使用 **pnpm**：`pnpm install`

## 指令
| 任務 | 指令 |
|------|------|
| 測試檔案 | `pnpm vitest run path/to/file.test.ts` |
| 檢查語法 | `pnpm eslint path/to/file.ts` |

## 外部參考
| 需求 | 檔案 |
|------|------|
| 設定 | `CONTRIBUTING.md` |
| 架構 | `docs/architecture.md` |
| 安全政策 | `SECURITY.md` |

## 關鍵慣例
- 產生的檔案：使用 `pnpm generate` 更新；不要手動編輯。

## 提交歸屬
AI 提交必須包含：
```
Co-Authored-By: (代理名稱與歸屬署名)
```

撰寫規則

• 使用標題、項目符號和表格；避免段落。
• 使用儲存庫相對路徑；避免模糊的參考如「參見文件」。
• 參考現有文件/規格/政策，而非複製它們。
• 列出設定、架構、API 規格、安全、發佈和政策文件的確切外部檔案（若存在）。
• 優先使用檔案範圍的測試/語法檢查/型別檢查指令；僅在沒有更精細指令時包含完整建置。
• 當有多個指令時，將指令放入表格。
• 每個項目符號保持一條規則。
• 除非能防止可能的錯誤，否則不包含理由。
• 不要重述 linter、formatter 或 typechecker 的設定。
• 不要列出已安裝的技能或外掛。
• 不要包含通用的品質口號。

外部參考規則

良好範例：

## 外部參考
| 需求 | 檔案 |
|------|------|
| API 合約 | `docs/api.md` |
| 發佈流程 | `docs/releasing.md` |

反模式

• 歡迎文字、介紹、結論或客套話
• 解釋指令為何重要的長篇散文
• 從 README.md、CONTRIBUTING.md 或政策文件複製的內容
• 當有檔案範圍指令時使用專案範圍指令
• 重複根目錄指令的巢狀 AGENTS.md 檔案