维护 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/中的模式" - 无填充内容 — 没有引言、结论或客套话
- 信任能力 — 省略显而易见的上下文
- 优先使用文件级命令 — 针对单个文件的测试/检查/类型检查命令，而不是全量构建
- 不重复 linter — 代码风格存在于 linter 配置中，而不是 AGENTS.md 中
必要章节
包管理器
仅指明使用的工具和关键命令：
## 包管理器
使用 **pnpm**：`pnpm install`、`pnpm dev`、`pnpm test`
文件级命令
文件级命令比全量构建更快且成本更低。可用时始终包含：
## 文件级命令
| 任务 | 命令 |
|------|------|
| 类型检查 | `pnpm tsc --noEmit path/to/file.ts` |
| 检查 | `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文件覆盖根目录）
反模式
省略以下内容：
- “欢迎使用…”或“本文档解释…”
- “你应该…”或“记住要…”
- 已在配置文件（
.eslintrc、biome.json、ruff.toml）中的 linter/格式化规则 - 列出已安装的技能或插件（代理自动发现这些）
- 存在文件级替代方案时的全量构建命令
- 显而易见的指令（“运行测试”、“编写干净代码”）
- 原因解释（只说做什么）
- 长篇散文段落
结构示例
# 代理指令
## 包管理器
使用 **pnpm**：`pnpm install`、`pnpm dev`
## 提交归属
AI 提交必须包含：
Co-Authored-By: (代理模型的名称和归属署名)
## 文件级命令
| 任务 | 命令 |
|------|------|
| 类型检查 | `pnpm tsc --noEmit path/to/file.ts` |
| 检查 | `pnpm eslint path/to/file.ts` |
| 测试 | `pnpm jest path/to/file.test.ts` |
## API 路由
[模板代码块]
## CLI
| 命令 | 描述 |
|------|------|
| `pnpm cli sync` | 同步数据 |
限制
- 仅当任务明确匹配上述描述的范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停下来要求澄清。