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、格式化程序或类型检查器的配置。
• 不要列出已安装的技能或插件。
• 不要包含通用的质量口号。

外部参考规则

好的示例：

## 外部参考
| 需求 | 文件 |
|------|------|
| API 契约 | `docs/api.md` |
| 发布流程 | `docs/releasing.md` |

反模式

• 欢迎文本、介绍、结论或客套话
• 解释指令为何重要的长篇散文
• 从 README.md、CONTRIBUTING.md 或策略文档中复制的内容
• 当文件范围命令可用时使用项目范围命令
• 重复根指令的嵌套 AGENTS.md 文件