writing-agents-md

编写 AGENTS.md

编写最精简且实用的仓库指南。 为 Agent 提供安全完成工作的背景信息、限制、权限和证据。

工作流

• 找到目标目录以及所有适用于该目录的 AGENTS.md 文件。
  • 优先遵循用户的明确指示，再遵循仓库指示。
  • 将每个文件视为适用于其所在目录的子树，并优先遵循作用范围最近的文件，再遵循其父级文件。
  • 在最窄的共同父级范围内放置共享指南。
  • 默认只使用一个根目录文件。
  • 仅当子项目需要不同规则时，才添加嵌套文件。
• 检查现有指南、人工编写的文档、配置、任务文件、CI 和相关的软件包文档。
  • 从工具可运行或可读取的文件中核实命令和路径。
  • 找出由其他位置生成或复制而来的文件。
  • 找出会影响 Agent 工作方式的高风险迁移、破坏性步骤、外部操作、大型数据和所有权规则。
• 只保留正确且针对项目的规则。
  • 删除过时、重复、猜测性、通用或放错位置的内容。
  • 在父级文件中保留共享规则，在子级文件中保留局部差异。
• 检查指示链中是否存在冲突。
  • 运行与变更规模和风险相匹配的检查。
  • 检查差异，确认没有重复规则或范围过大的内容。
  • 标明无法核实的事实。
• 进行审查时，优先检查错误的命令、过时的路径、冲突的作用范围、不安全的权限和缺失的检查。
  • 为每项发现注明严重性、位置、证据和替代内容。
  • 如果没有遗留问题，说明这一点并指出任何重要的缺失证据。

自动维护

除非用户明确要求编辑 AGENTS.md，否则只有在仓库证据证明某条持久且针对仓库的规则会改变未来 Agent 的工作方式时，才记录该指南。 不要记录任务历史、临时状态、猜测、通用建议、机密信息或权威文档中已有的指南。 不要仅仅因为不存在 AGENTS.md 就创建该文件。 在获准进行的仓库变更中发现符合条件的指南时，应在适用范围最窄的目录中更新或创建文件。 在回答、审查、诊断或规划工作期间，应报告候选规则，而不是写入文件。 将规则放入匹配的现有章节；只有证据足以支持时，才添加相关的默认章节。 每条自动添加或实质性改写的规则都必须加上 [UNREVIEWED] 前缀：

- [UNREVIEWED] Run `pnpm test:web` after changing this package.

将标记的规则视为有效指示；该标记记录用户审阅状态，不表示存在不确定性或权威性较低。 只有在用户明确指示后才能移除标记。 改写或合并标记指南时保留标记；不要为用户已审阅的等效规则添加标记。 合并或修订相互重叠的标记规则，不要追加重复内容。 进行附带维护时，不要悄悄改写或删除未标记的规则；除非用户要求维护 AGENTS.md，否则应报告相矛盾的证据。 编辑后，重新阅读适用的指示链，并核实作用范围、位置、去重情况、标记保留情况，以及是否不存在敏感信息或任务日志内容。 只报告发生变化的自动维护规则。

默认章节

创建或重组 AGENTS.md 时，将这些章节用作检查清单。 检查每个未标记的章节，并在保留的章节之间维持此相对顺序。 仅在章节包含 Agent 需要且已核实的指南时才纳入。 检查后若没有此类指南，应省略该章节，而不是留空或编造规则。 只有与仓库相关时才考虑标记为 [Optional] 的章节。 [Optional] 标记是模板注释；将相应章节纳入最终文件时，应从标题中删除该标记。

## [Optional] Communication
## Documentation
## Code style
## Commands
## Boundaries
## [Optional] Security
## Testing
## [Optional] Project overview
## [Optional] Repository structure
## [Optional] Git and commits

编写规则

• 将规则归入描述性 ## 章节标题下，并将每条规则写成简洁、可执行的一句话项目符号。
• 说明预期结果、有用的背景信息、硬性限制、需要批准的操作以及成功标准。
• 仅在顺序重要时描述操作步骤。
• 每条规则只在最适合的最小范围内说明一次。
• 使用直接的措辞，并明确写出路径、命令、条件、证据和停止节点。
• 仅纳入 Agent 必需了解的范围、命令、代码与测试约定、安全或数据限制，以及协作或发布规则。
• 将产品介绍和面向人的操作指南留在面向人的文档中。
• 仅在示例或写作风格规则体现项目要求或能避免已出现的错误时保留。
• 明确指出需要提问的模糊之处。
• 不要要求对安全的本地操作一律审批。

需要规定操作策略时，请使用一个简洁的区块：

For answer, explanation, review, diagnosis, or planning requests, inspect the relevant materials and report the result.
Do not make changes unless the request asks for them.
For change, build, or fix requests, make the requested local changes and run relevant safe checks.
Ask before writing to external systems, taking destructive or costly actions, or greatly expanding the scope.

根据仓库中的证据调整策略。 明确说明安全的本地操作和项目特定例外。 不要在其他地方重复该策略。

仅为仓库实际使用的工作流添加自动化规则。 对于小型自动化工作流，请定义阶段、允许使用的工具、所需证据、限制和停止节点。 说明何时必须由人工判断或审批接手。