agents-md

根据仓库证据维护 AGENTS.md

概述

创建或改进 Agent 指令，帮助编码 Agent 正确修改仓库，而不必重新摸索工作流。所有特定于仓库的命令、路径和规则，都必须以当前检出内容中的证据为依据。

优先采用范围明确的差异，而非彻底重写。没有通用的行数限制、必需章节清单、符号链接布局或提交归属策略；应遵循仓库自身的需求和维护者意图。

适用场景

• 用户要求创建、更新、精简或审核 AGENTS.md。
• 单体仓库需要根目录指令以及更细化的包级覆盖规则。
• 现有 Agent 指令包含过时命令、重复策略或缺乏依据的说法。
• 用户希望协调 AGENTS.md 与 CLAUDE.md、.github/copilot-instructions.md 或其他仓库指令文件。

只有当任务明确要求使用 @agents-generator 随附的生成模式、素材或备份工作流时，才改用它。若主要目标是进行便于维护者阅读、以证据为先的编辑，则使用此技能。

工作方式

1. 保留现有意图

开始编写前，阅读所有适用于目标路径的指令文件，包括现有的 AGENTS.md，以及相关工具专用文件，如 CLAUDE.md、GEMINI.md、.github/copilot-instructions.md 和 .github/instructions/*.instructions.md。

• 尽可能直接改进现有的 AGENTS.md。
• 保留准确的维护者编写规则和特定于仓库的策略。
• 除非用户提出要求，且仓库证据表明需要相同内容，否则不要将其他工具的指令文件替换为符号链接。
• 不要擅自处理相互冲突的指令。遵循优先级更高且适用的规则；如果无法根据仓库确定预期策略，则应询问用户。

2. 建立范围明确的证据图

只检查足以确认实际工作方式的仓库内容：

1. 阅读项目概览和贡献指南，例如 README*、CONTRIBUTING* 及相关文档。
2. 阅读清单文件、锁文件、工作区文件、任务运行器和构建配置，以确定受支持的工具和准确命令。
3. 阅读 CI 工作流，了解必需的检查项。不要假设所有 CI 或部署任务都适合或可安全地在本地运行。
4. 检查有代表性的源文件和测试文件，了解命名、布局和测试惯例。
5. 识别生成文件、迁移文件、供应商代码、大型测试夹具、机密信息边界以及仅限生产环境的操作。

如有可用工具，优先使用 rg --files 和 rg 进行查找。记录每条不明显的命令或规则所依据的来源，避免在最终文件中加入缺乏依据的说法。

3. 确定指令范围

使用根目录中的 AGENTS.md 提供全仓库通用指南。只有当某个子树在命令、架构、惯例或安全边界方面存在实质差异时，才添加或修改嵌套的 AGENTS.md。

将共享规则保留在根目录，仅在嵌套文件中说明差异。对于遵循公开 AGENTS.md 规范的工具，应根据目标宿主的优先级规则，应用根目录或祖先目录中的指南，以及范围更窄的子树指令。最近的文件不会悄然抹去无关的祖先规则。不要在每个包中复制整份根目录文件。

4. 编写高信号指引

选择适合该仓库的标题，而不是强行套用固定模板。 仅在证据支持时才包含以下内容：

• 仓库地图： Agent 必须了解的几个目录及其边界。
• 安装与命令： 确切的安装、开发、构建、lint、类型检查和测试命令， 以及在工作目录不明显时标明工作目录。
• 针对性验证： 针对小型改动的定向检查，以及交接前所需的更广泛检查。
• 变更规则： 生成文件的所有权、迁移、schema、API、 依赖项以及跨包协调。
• 安全边界： 密钥、生产数据、破坏性命令、 部署以及需要明确授权的操作。
• 贡献规则： 影响实现或交接的仓库特定命名、格式、提交或 拉取请求要求。

编写直接、可测试的陈述。优先使用：

- From the repository root, run `npm test -- path/to/file.test.ts` for a focused test.

而非：

- Make sure tests pass and follow best practices.

链接到维护中的文档，而不是复制它。区分必需 检查与可选、缓慢、需特权或仅用于部署的检查。

5. 交接前验证

1. 完整重读每个已更改的 AGENTS.md。
2. 移除矛盾、重复规则、占位符和过时声明。
3. 确认每个提到的文件和目录都存在。
4. 对照 manifest 或 CI 交叉检查命令，并在有用时运行安全、适度的 检查。
5. 如果嵌套文件发生更改，确认每个文件仅包含子树特定的规则， 并且不会意外与根文件冲突。
6. 以维护者的视角审查 diff：每一行新增内容都应改变 Agent 的 决策或防止现实中的错误。

报告更改的文件、使用的证据、实际运行的检查以及未解决的 不确定性。绝不要在仅从配置中读取命令时就声称已测试该命令。

示例

创建聚焦的根文件

发现的证据：

• package-lock.json 选择了 npm。
• package.json 定义了 lint、typecheck 和 test 脚本。
• CI 从仓库根目录运行这三项检查。
• src/generated/ 由 npm run generate 生成。

一个有用的结果可能包含：

# Agent instructions

## Commands
- Run commands from the repository root.
- Install with `npm ci`.
- For handoff, run `npm run lint`, `npm run typecheck`, and `npm test`.

## Generated code
- Do not edit `src/generated/` directly; update its source and run `npm run generate`.

不要添加证据未确立的包管理器、命令或生成文件规则。

修订而不抹除策略

如果现有文件有准确的发布限制但测试命令过时，仅更改过时的命令 及任何直接受影响的说明。 保留发布限制，即使更短的替换看起来更整洁。

最佳实践

• 保持指令简洁到足以快速浏览，但让仓库复杂度 决定长度。
• 优先采用仓库特定的决策，而非通用工程建议。
• 在项目支持时包含定向命令；不要为仅支持套件级运行的工具 虚构文件范围的调用。
• 说明命令在何处运行以及是否会修改文件。
• 引用格式化器和 linter 配置，而不是重述每条规则。
• 当工具特定文件的语义不同时，使其可叠加；不要假设 所有 Agent 对格式或优先级的解释完全相同。

安全与安保注意事项

• 将此视为会改变状态的技能，因为它可能会编辑仓库文件。 交接前审查 diff。
• 绝不要在 Agent 指令中包含密钥、凭据、内部 URL、个人数据或本地 环境值。
• 不要仅为验证文档而运行部署、发布、数据库变更、历史重写或 其他有后果的命令。
• 保留仓库策略中已有的审批门。
• 不要将私有仓库指令上传到第三方服务。在将任何仓库内容 传输到外部之前，请求明确同意。

常见陷阱

• 猜测命令： 从 manifest 和 CI 推断工具，而不是凭流行度。
• 强制统一布局： 符号链接或固定的章节列表可能会抹去 工具专属或维护者编写的指引。
• 覆盖现有文件： 做出有证据支持的最小改动。
• 照搬 README： 只收录会改变 Agent 行为的信息。
• 重复嵌套文件： 将共享指引放在根目录，将局部 差异放在相关代码附近。
• 声称进行了实际未运行的验证： 在交接中区分检查与 执行。

局限性

• 仓库证据可能不完整或相互矛盾；当某项重要的 策略选择无法安全解决时，请主动询问。
• 已记录的命令仍可能需要本地无法提供的凭据、服务或 操作系统支持。
• 不同编码工具对 AGENTS.md 的支持和优先级各不相同；当互操作性 很重要时，请核实目标工具。
• 本技能可提升指令质量，但无法证明未来每个 Agent 都会正确遵循该文件。

相关技能与工具

• @agents-generator - 打包生成、试运行、更新和备份模式。
• @folder-specific-claude-and-agents-md - 针对限定范围的 Claude/AGENTS 指令布局的深入指引。
• agents.md - 公开格式与适用范围指引。