維護 AGENTS.md
AGENTS.md 是權威性的代理用文件。保持精簡——代理能力強大，不需要被手把手教導。目標低於 60 行；絕不超過 100 行。文件越長，指令遵循品質越差。
使用時機
- 使用者要求建立、更新或稽核
AGENTS.md或CLAUDE.md。 - 專案需要根據實際工具鏈和儲存庫佈局，提煉出簡潔、高信號的代理指令。
- 現有代理文件太長、重複，或偏離實際專案慣例。
檔案設定
- 在專案根目錄建立
AGENTS.md - 建立符號連結：
ln -s AGENTS.md CLAUDE.md
寫入前
分析專案，了解哪些內容應包含在檔案中：
- 套件管理器 — 檢查鎖定檔（
pnpm-lock.yaml、yarn.lock、package-lock.json、uv.lock、poetry.lock） - Linter/格式化程式設定 — 尋找
.eslintrc、biome.json、ruff.toml、.prettierrc等（不要在 AGENTS.md 中重複這些） - CI/建置指令 — 檢查
Makefile、package.json腳本、CI 設定中的權威指令 - Monorepo 跡象 — 檢查
pnpm-workspace.yaml、nx.json、Cargo workspace 或子目錄中的package.json檔案 - 現有慣例 — 檢查現有的 CONTRIBUTING.md、docs/ 或 README 模式
寫作規則
- 標題 + 項目符號 — 無段落
- 程式碼區塊 — 用於指令和範本
- 引用，不內嵌 — 指向現有文件：「請參閱
CONTRIBUTING.md了解設定」或「遵循src/api/routes/中的模式」 - 無填充 — 無引言、結論或客套話
- 信任能力 — 省略顯而易見的上下文
- 偏好檔案範圍指令 — 每個檔案的測試/lint/型別檢查指令優於全專案建置
- 不要重複 linter — 程式碼風格存在於 linter 設定中，而非 AGENTS.md
必備章節
套件管理器
僅包含工具和關鍵指令：
## 套件管理器
使用 **pnpm**：`pnpm install`、`pnpm dev`、`pnpm test`
檔案範圍指令
單檔指令比全專案建置更快且更便宜。可用時務必包含：
## 檔案範圍指令
| 任務 | 指令 |
|------|------|
| 型別檢查 | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| 測試 | `pnpm jest path/to/file.test.ts` |
提交歸屬
務必包含此章節。代理應使用自己的身份：
## 提交歸屬
AI 提交必須包含：
Co-Authored-By: (代理模型的名稱與歸屬署名)
範例：`Co-Authored-By: Claude Sonnet 4 <[email protected]>`
關鍵慣例
代理必須遵守的專案特定模式。保持簡潔。
選用章節
僅在真正需要時加入：
- API 路由模式（展示範本，無需解釋）
- CLI 指令（表格格式）
- 檔案命名慣例
- 專案結構提示（指向關鍵檔案，標示應避免的舊程式碼）
- Monorepo 覆寫（子目錄中的
AGENTS.md檔案覆寫根目錄）
反模式
省略以下內容：
- 「歡迎來到...」或「本文件說明...」
- 「你應該...」或「記得要...」
- 已在設定檔中定義的 linter/格式化規則（
.eslintrc、biome.json、ruff.toml） - 列出已安裝的技能或外掛（代理會自動發現它們）
- 當有檔案範圍替代方案時，使用全專案建置指令
- 顯而易見的指令（「執行測試」、「寫乾淨的程式碼」）
- 為何如此的解釋（只說要做什麼）
- 冗長的散文段落
範例結構
# 代理指令
## 套件管理器
使用 **pnpm**：`pnpm install`、`pnpm dev`
## 提交歸屬
AI 提交必須包含：
Co-Authored-By: (代理模型的名稱與歸屬署名)
## 檔案範圍指令
| 任務 | 指令 |
|------|------|
| 型別檢查 | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| 測試 | `pnpm jest path/to/file.test.ts` |
## API 路由
[範本程式碼區塊]
## CLI
| 指令 | 描述 |
|---------|------|
| `pnpm cli sync` | 同步資料 |
限制
- 僅在任務明確符合上述範圍時使用此技能。
- 請勿將輸出視為針對特定環境的驗證、測試或專家審查的替代方案。
- 如果缺少所需的輸入、權限、安全邊界或成功標準，請停止並要求說明。