agents-md

维护 AGENTS.md

目标：提供简洁、可执行的 Agent 指令。控制在 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 的入口文件，则创建指向 AGENTS.md 的符号链接 CLAUDE.md。
• 不要维护内容不同的 AGENTS.md 和 CLAUDE.md 副本。

默认章节

仅使用能提供非显而易见价值的章节。

# Agent Instructions

## Package Manager
- Use **pnpm**: `pnpm install`

## Commands
| Task | Command |
|------|---------|
| Test file | `pnpm vitest run path/to/file.test.ts` |
| Lint file | `pnpm eslint path/to/file.ts` |

## External References
| Need | File |
|------|------|
| Setup | `CONTRIBUTING.md` |
| Architecture | `docs/architecture.md` |
| Security policy | `SECURITY.md` |

## Key Conventions
- Generated files: update with `pnpm generate`; do not edit by hand.

## Commit Attribution
AI commits MUST include:
```
Co-Authored-By: (the agent's name and attribution byline)
```

编写规则

• 使用标题、项目符号和表格；避免使用段落。
• 使用仓库相对路径；避免使用“参见文档”等模糊表述。
• 引用现有文档／规范／政策，而不是复制其内容。
• 如果存在外部文档，应列出准确的文件路径，用于安装设置、架构、API 规范、安全、发布和政策。
• 优先使用针对单个文件的测试／lint／类型检查命令；仅在没有更精确命令时才包含完整构建命令。
• 命令超过一个时，放入表格。
• 每条项目符号只写一条规则。
• 除非理由能避免可能的错误，否则不要写理由。
• 不要复述 linter、formatter 或类型检查器的配置。
• 不要列出已安装的技能或插件。
• 不要加入泛泛的质量口号。

外部引用规则

良好示例：

## External References
| Need | File |
|------|------|
| API contract | `docs/api.md` |
| Release process | `docs/releasing.md` |

反模式

• 欢迎辞、引言、结语或客套话
• 长篇解释指令为何重要
• 重复 README.md、CONTRIBUTING.md 或政策文档中的内容
• 有针对单个文件的命令时仍使用项目范围的命令
• 嵌套的 AGENTS.md 文件重复根目录指令