AGENTS.md 作者指南

概述

AGENTS.md 是位于代码仓库根目录（或子目录）的 Markdown 文件,用于向 AI 编程代理说明项目的构建、测试和贡献方式。与面向人类的 README.md 不同,AGENTS.md 是专为代理设计的高优先级上下文文件,会被自动加载。

何时使用 AGENTS.md

• 当项目将被 AI 编程代理访问时；
• 代理需要知道如何安全地构建、测试或提交代码,而无需每次会话重新发现这些流程；
• 存在人类从 README 阅读但代理必须显式指示才能理解的约定时。

注意:优先使用 AGENTS.md；CLAUDE.md 仅用于 Claude Code 特有行为；SKILL.md 适用于可移植技能；README.md 面向人类评估者。

文件位置规则

• AGENTS.md 位于仓库根目录为默认入口；
• 嵌套的 AGENTS.md（如 apps/web/AGENTS.md）在其子树内生效并覆盖或扩展根文件；
• 解析原则:编辑文件时最具体的 AGENTS.md 生效；
• 多仓库项目建议每个包单独编写 AGENTS.md,避免代理加载无关配置。

推荐章节（按建议顺序）

省略无价值内容,不要填充,不要发明命令。

1. 项目概览（≤3句）

   • 此仓库用途、技术栈、主要语言；
   • 明确声明是否为多仓库、库、服务或应用。

2. 设置命令

   • 代理运行以获取开发环境所需的最小命令；
   • 版本号需固定（如 "Node ≥ 20.x", "uv ≥ 0.4"）；
   • 包含安装命令原文。

3. 构建 / 测试 / 检查 / 类型检查

   • 精确命令,每行一个,中间无描述；
   • 区分完整套件、快速套件、单文件、监听模式；
   • 指定提交前默认运行哪个命令。

4. 代码风格

   • 缩进（空格/制表符）、行长、格式化工具（如 "ruff format", "prettier"）；
   • 模块规范（如 "使用 ES 模块而非 CommonJS"）；
   • 命名模式（项目特定）；
   • 禁止项（如 "不要导入 internal/ 中的内容"）。

5. 测试说明

   • 应编写的测试类型（单元/集成/E2E）；
   • 测试存放位置（tests/, __tests__, *_test.go 等）；
   • 覆盖率要求（如有强制执行）；
   • 单测运行方式；
   • 明确何时可跳过测试（罕见——需显式说明）。

6. PR / 提交规则

   • 分支命名、约定提交格式、Signed-off-by、DCO；
   • PR 标题格式、必填正文部分；
   • 合并前必需通过的 CI 检查；
   • 代理是否可直接推送或必须开 PR。

7. 安全与密钥

   • 代理绝不能读写的文件（.env*, *.pem, secrets/, credentials.json）；
   • 哪些 API 需认证及密钥存放处；
   • 代理能否运行任意 curl / 网络调用；
   • 代理能否执行 rm -rf、破坏性 Git 操作或迁移。

8. 部署与发布

   • 仅当代理预期负责部署或发版时才包含；否则省略。

9. 架构说明（仅代理需知的安全操作）

   • 模块所有权相关（如 "不要修改 proto/ 中生成的文件"）；
   • 子系统边界；
   • 新代码添加位置默认路径（如 "新端点添加至 api/v2/"）。

10. 嵌套 AGENTS.md 指针

    • 列出多仓库中兄弟 AGENTS.md 文件,便于代理导航。

写作准则

1. 面向代理而非新人:命令式语气,第二人称,简洁；
2. 所有命令必须可复制粘贴且正确:未知则询问用户,勿猜测；
3. 保持简短:典型仓库 ≤200 行,长文件会被截断；
4. 不重复 README:交叉引用代替复制；
5. 优先负面约束:如 "不要编辑 vendor/ 下文件"；
6. 声明默认验证步骤:始终包含代理完成任务前应运行的单命令；
7. 不含秘密、令牌、私有路径:AGENTS.md 已提交,视为公开；
8. 单一事实来源:若命令存在于多个地方,以构建工具为准并在 AGENTS.md 引用。

常见反模式（严禁出现）

• 无人遵循的理想规则（如 "所有代码需 100% 覆盖率",而项目实际仅 30%）；
• 通用最佳实践论述（"始终编写干净代码"）；
• 罗列全部依赖（"该项目使用 React, TypeScript..."）；
• 提及工具但未给出具体命令（"我们使用 Playwright" — 应说明运行命令）；
• 长篇架构概念——应放入 docs/；
• 根与嵌套 AGENTS.md 间命令冲突未显式覆盖说明；
• 营销语言、哲学或 "为何构建此项目" — 那是 README 的职责；
• 嵌入 API 密钥、内部 URL、员工姓名等不应公开的敏感信息。

工作流程

当用户请求编写或改进 AGENTS.md 时:

1. 定位分析:

   • 检查仓库结构、包管理器、语言、框架、测试器、CI 配置；
   • 读取现有 README.md、Makefile、package.json scripts、pyproject.toml、Cargo.toml、go.mod 及 CI 工作流,提取真实构建/测试/检查命令；
   • 判断是否为多仓库并识别自然 AGENTS.md 边界。

2. 提取而非虚构:

   • AGENTS.md 中每个命令必须来自仓库真实源（脚本、Makefile 等）,缺失则标记并询问；
   • 发现源之间冲突时（如 README 与 CI 不一致）需暴露问题,不静默选择其一。

3. 起草:

   • 使用推荐章节顺序,跳过空节；
   • 控制根文件 ≤200 行；
   • 命令用围栏代码块包裹并标注语言。

4. 验证:

   • 对草案中每个命令,指向其来源文件（如 "来自 package.json:scripts.test"）；
   • 自检是否符合写作准则与反模式清单；
   • 确认无敏感信息。

5. 提出嵌套文件:

   • 多仓库情况下,为每包提议 AGENTS.md 大纲并解释其覆盖内容。

输出格式

当被要求生成 AGENTS.md 时,输出三部分:

1. 拟议 AGENTS.md — 单个围栏 markdown 块,可直接提交；
2. 出处 — 每个命令/章节与其来源文件的配对列表；
3. 问题 — 无法从仓库解决且需用户确认的事项,若无则写 "无"。

当被要求审查或改进现有 AGENTS.md 时,输出:

1. 审查意见 — 逐行对比式反馈,说明保留/修改/删除内容及原因；
2. 修订后 AGENTS.md — 单个围栏 markdown 块；
3. 出处与问题 同上。

AGENTS.md 是仓库与任何访问它的 AI 编程代理之间的契约。使其紧凑、具体、可执行且安全。若某节不直接帮助代理在此代码库上正确操作,请删除它。