agents-md

AGENTS.md

概述

编写或完善项目的 AGENTS.md：提供简洁、可执行且不依赖特定运行框架的指引，供编码 Agent 作为始终生效的项目上下文加载。应以帮助 Agent 成功完成任务为目标，而非帮助人类入门（后者由 README.md 负责）。

本技能面向开放的 AGENTS.md 格式（纯 Markdown，无必填字段）。不要将其与 .github/agents/ 中 GitHub Copilot 的自定义 Agent 角色（frontmatter + 角色文件）混淆。关于命令、示例和边界的经验仍适用；角色文件则不适用。

模式

选择一种：

• 创建 — 没有可用的 AGENTS.md（或用户要求搭建初始文件）。
• 审查 — 根据质量标准检查现有文件；报告不足，除非用户要求，否则不重写。
• 改进 — 重写或编辑文件，使其达到质量标准。
• 嵌套 — 在单体仓库中添加或修复包/子目录的 AGENTS.md 文件。

如果不明确，只询问一次：创建、审查、改进，还是嵌套？

核心规则

• 优先使用一个根目录 AGENTS.md。仅当某个子树有不同的命令、边界或约定时，才添加嵌套文件。
• 必需： 每个根目录 AGENTS.md 都必须包含 references/communication.md 中的 Communication (ASD-STE100) 部分。原样粘贴。嵌套文件无需包含，除非它们要覆盖写作规则。
• 默认必需： 每个根目录 AGENTS.md 都包含 references/testing.md 中的 Testing（优先 E2E 和集成测试）部分。只列出仓库已有的 E2E 和集成测试配置；绝不能新增。只有当用户说明仓库遵循不同的测试政策时，才省略此部分。
• 编辑 AGENTS.md 时绝不要删除测试。对于信号较弱的单元测试，可另行提出清理方案，并等待批准。
• 每一行内容都必须有价值。判断标准：删掉这行，是否会导致 Agent 犯下原本不会犯的错误？ 如果不会，就删除。
• 根目录文件目标长度为 ≤150 行；小型仓库 30–50 行 足够。超出时拆分文件或添加索引。
• 尽早列出准确的可执行命令（包含项目实际使用的标志和筛选条件）。Agent 会重新运行这些命令。
• 优先使用指引链接和概览表，而不是粘贴架构长文、完整风格指南或 README 副本。
• 说明 Agent 无法自行推断的信息：包管理器、特殊目录结构、隐含约定、禁止访问的路径、安全注意事项，以及“先询问”的变更。
• 使用具体示例（简短代码片段或标准路径），避免含糊的风格描述。
• 需要时分三个层级说明边界：始终允许 / 先询问 / 绝不允许。
• 保持与运行框架无关：不依赖某个产品的工具名称、界面或隐藏行为。可笼统提及可选能力（计划模式、审批、子 Agent），并提供手动替代方案。
• 绝不要在 AGENTS.md 中放入机密、令牌、私钥或真实凭证。
• 将文件视为持续维护的文档：当用户报告 Agent 反复犯错时，将解决方法写入此文件（或链接的文档）。
• 优先采用项目在 package.json / Makefile / justfile / CI 中实际使用的包管理器和脚本；不要编造命令。
• 仅当目标仓库已使用 Bun 时，才在本技能的示例中优先使用 bun / bunx；否则应遵循仓库实际使用的工具。

质量标准（必须通过）

优秀的 AGENTS.md 应涵盖以下适用内容（省略空章节，不要凑内容）。根目录文件中必须包含沟通规范。

1. 技术栈 — 语言、框架、关键库；对于不常见的技术，注明版本。
2. 命令 — 安装、开发、测试、lint／类型检查、构建；单体仓库还应列出指定范围的命令。
3. 沟通规范 — 来自 references/communication.md 的 ASD-STE100 区块（根目录文件必需）。
4. 目录布局 — 源码、测试、配置和生成产物的存放位置（仅在布局不常见时说明）。
5. 约定 — Agent 容易弄错的项目专属风格／架构规则；其他情况链接到 lint／格式化配置。
6. 测试 — 来自 references/testing.md 的区块，只列出实际存在的端到端和集成测试配置及真实命令。
7. Git／PR — 与默认做法不同的提交／PR 规范（标题格式、必需检查项）。
8. 边界 — 始终允许／先询问／绝不允许（机密信息、供应商目录、生产配置、架构、依赖项）。
9. 索引 — 链接或表格，指向更深入的文档（架构、ADR、安全模型），而不是将其内联。

完整清单：references/quality-bar.md。

工作流

1. 检查仓库

开始编写前：

• 阅读现有的 AGENTS.md、README.md、CONTRIBUTING.md、CI 工作流和软件包脚本。
• 记录软件包管理器、测试运行器、lint／格式化工具、单体仓库布局和不安全区域。
• 浏览之前的 Agent 指令文件（CLAUDE.md、.cursor/rules、GEMINI.md 等），迁移其中独有的内容；不要盲目重复。

2. 起草或编辑

• 使用 references/template.md 作为初始结构；删除未使用的章节。
• 始终将 references/communication.md 中的沟通区块原样粘贴到根目录文件。
• 在沟通区块后粘贴 references/testing.md 中的测试区块。根据实际脚本填写配置行；删除仓库中不存在的配置对应行。
• 将常用命令放在靠前位置。接着放沟通区块，再放测试区块。
• 只写项目专属约束；删去 Agent 已知的通用建议。不要删去沟通区块或测试区块。
• 对于单体仓库，遵循 references/nesting.md。

3. 验证

根据以下内容检查：

• 上述质量标准和 references/quality-bar.md。
• 沟通区块存在且未经修改：references/communication.md。
• 测试区块存在、规则未弱化、占位符已填写，且只列出了实际存在的配置：references/testing.md。
• references/anti-patterns.md 中的反面模式。
• references/examples.md 中的好／坏模式。

确认所有链接路径均存在。确认命令与脚本／CI 一致。确认不含机密信息。

4. 交付

• 创建／改进／嵌套：在约定的路径创建文件，通常是仓库根目录下的 AGENTS.md。
• 审查：返回简短报告，说明通过项、未通过项和建议的修改；除非收到要求，否则不要重写。
• 最后简要说明行数、已包含的章节，以及有意省略的内容。

冲突与优先级说明

在相关时为维护者记录以下事项（不要在每个文件中反复说教）：

• 按此方式解决冲突的 Agent 会优先采用距离所编辑文件最近的嵌套 AGENTS.md，而非父级指导；用户聊天内容始终优先于文件。
• 有些 Agent 会将根目录到当前工作目录的文件内容串联起来（越靠后、越具体的内容优先）。嵌套文件应作为补充，并明确说明覆盖项。
• 某些工具设有宽松的大小上限（例如 Codex 的项目文档字节数限制）。优先拆分文件或采用嵌套结构，避免根目录文件过长。
• 如需兼容 Claude Code，可使用一个精简的 CLAUDE.md 引用 @AGENTS.md（并添加仅适用于 Claude 的补充内容），避免重复整份指南。

不在范围内

• 当用户需要精细的文件模式规则时，替换按路径限定的 IDE 规则系统（例如使用 glob 的 .cursor/rules）——AGENTS.md 是简单、可移植的默认选择。
• 除非用户明确提出要求，否则不编写 .github/agents/ 下的 Copilot 自定义 Agent 人设包。
• 将整份面向人类读者的 README 复制到 AGENTS.md。