review-agents-md

AGENTS.md 技能

概述

按照渐进式披露原则创建和重构 AGENTS.md 文件。保持文件精简、重点明确，避免形成损害 Agent 性能的“一团乱麻”。

适用场景

• 主动检查：项目根目录没有 AGENTS.md 时——开始处理新项目时请检查
• 从头创建新的 AGENTS.md
• 重构臃肿的 AGENTS.md
• 按照最佳实践审查现有文件
• 为单体仓库设置 AGENTS.md
• 存在 AGENTS.md 但缺少 CLAUDE.md 时（应创建符号链接）

核心原则

1. 默认精简：只包含与每一项任务都相关的内容
2. 渐进式披露：将特定领域规则指向独立文件、外部文档或 Agent 技能
3. 绝不记录文件结构：它很快就会过时，并污染 Agent 上下文
4. 描述能力，而非位置：写“身份验证使用 JWT”，而不是“身份验证位于 src/auth/”

指令预算

前沿大模型通常能以较好的稳定性遵循约 150–200 条指令。AGENTS.md 中的每个 Token 都会在每次请求时加载，无论内容是否相关。理想的文件应尽可能精简。

文件为何会变得臃肿

Agent 做错事 → 你添加一条规则 → 如此重复数百次 → 最终变成“一团乱麻”。不同开发者会加入相互冲突的意见。没有人全面检查文档风格。自动生成的文件则会让情况更糟，因为它们优先追求面面俱到，而非有所克制。

过时文档会污染上下文

人类可能会对过时文档持怀疑态度。Agent 不会——每次请求中，它们都会相信自己读到的内容。文件路径尤其危险，因为它们总在变化。请描述能力和领域概念，而不是位置。

流程

阶段 0：检测缺失文件

检查项目根目录中的 AGENTS.md 和 CLAUDE.md：

1. 如果两者都不存在，提出创建 AGENTS.md 并为其创建 CLAUDE.md 符号链接
2. 如果存在 AGENTS.md，但不存在 CLAUDE.md，创建符号链接：ln -s AGENTS.md CLAUDE.md
3. 如果存在 CLAUDE.md，但不存在 AGENTS.md，将其重命名为 AGENTS.md 并创建符号链接：mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
4. 如果两者都存在，但 CLAUDE.md 并未指向 AGENTS.md，则将独有内容合并到 AGENTS.md 中，删除独立的 CLAUDE.md，并创建符号链接

阶段 1：评估当前状态

对于新项目：

• 询问项目的用途（一句话）
• 询问包管理器（如果不是 npm）
• 询问非标准构建命令

对于现有文件：

• 阅读当前的 AGENTS.md
• 统计行数并估算 Token 开销
• 找出适合放在其他位置的内容

阶段 2：进行必要性测试

根目录的 AGENTS.md 中只应包含以下内容：

包含项	原因
一句话的项目描述	为 Agent 的每个决策提供依据
包管理器（如果不是 npm）	避免使用错误的命令
非标准构建／测试命令	减少试错
特定领域文档的链接	实现渐进式披露

其他内容应移至独立文件或删除。

阶段 3：识别反模式

标记以下内容，以便删除或移至其他位置：

• 文件树结构：总会过时，浪费 Token
• 显而易见的指令：“编写整洁的代码”“使用有意义的名称”
• 相互矛盾的规则：通常来自多个贡献者
• 特定语言的约定：移至 docs/TYPESCRIPT.md 等文件
• 工作流说明：移至 docs/GIT.md 或 docs/TESTING.md

阶段 4：创建渐进式披露结构

对于不应删除的内容：

docs/
├── TYPESCRIPT.md    # TS conventions
├── TESTING.md       # Test patterns
├── API.md           # API design rules
└── GIT.md           # Commit/PR conventions

在 AGENTS.md 中用简洁的指引链接到这些文件。保持语气自然，不要使用“务必”或全大写的强制措辞：

For TypeScript conventions, see docs/TYPESCRIPT.md

每个文件都可以链接到下一个文件，让 Agent 按需浏览目录树，只加载相关内容。

与其复述权威外部文档，不如链接到它们：

For database migrations, follow the Prisma migration guide.

Agent 技能是渐进式披露的另一层。不要把操作流程写进 AGENTS.md，而应将其打包成 Agent 需要时才加载的技能。根文件专注于是什么和在哪里；技能负责如何做。

阶段 5：处理单体仓库

对于单体仓库，使用嵌套的 AGENTS.md 文件：

根目录 AGENTS.md：

Monorepo for [purpose]. Uses [pnpm/yarn] workspaces.
See each package's AGENTS.md for specifics.

包目录 AGENTS.md（例如 packages/api/AGENTS.md）：

GraphQL API using Prisma. See docs/API_CONVENTIONS.md for patterns.

阶段 6：输出

提供：

1. 新建或重构后的 AGENTS.md 内容
2. 为渐进式披露而创建的所有新文件
3. 已删除内容的列表及删除理由

输出格式

创建新的 AGENTS.md 时：

# [Project Name]

[One-sentence description of what this project does.]

[Package manager if not npm]

[Non-standard commands if any]

[Light-touch pointers to separate docs if needed]

示例：精简的 AGENTS.md

# Acme Dashboard

React admin dashboard for managing customer accounts and billing.

Uses pnpm. Run `pnpm check` for type checking.

For API conventions, see docs/API.md
For component patterns, see docs/COMPONENTS.md

共 6 行。每个词都物尽其用。

重构提示词

重构现有的臃肿文件时，请按以下步骤操作：

1. 查找矛盾：找出相互冲突的指令，并询问应保留哪一条。
2. 确定必要内容：只提取适合放在根目录的内容——项目说明、包管理器、非标准命令，以及与每项任务都相关的内容。
3. 归纳其余内容：按逻辑类别整理，并创建单独的文件。
4. 创建结构：输出精简的根目录 AGENTS.md，并链接到单独的文件。
5. 标记待删除内容：找出冗余、含糊或显而易见的指令。

决策框架

在向 AGENTS.md 添加任何内容之前：

位置	适用情况
根目录 AGENTS.md	与每一项任务都相关
单独的文件	与某个领域相关
嵌套文档	适合分层组织
删除	显而易见、冗余或含糊

跨工具兼容性

AGENTS.md 是一项开源标准，受 20 多种工具支持，包括：

• GitHub Copilot（编码 Agent）
• Cursor
• Codex（OpenAI）
• Gemini CLI（Google）
• Windsurf、Devin（Cognition）
• Zed、Warp、VS Code
• Aider、goose、RooCode

Claude Code 使用 CLAUDE.md。AGENTS.md 始终是唯一事实来源。CLAUDE.md 必须始终是指向它的符号链接：

ln -s AGENTS.md CLAUDE.md

切勿创建独立的 CLAUDE.md。切勿在 CLAUDE.md 中放入 AGENTS.md 中没有的内容。

资源

• https://agents.md — AGENTS.md 规范
• https://www.aihero.dev/a-complete-guide-to-agents-md — 为本技能最佳实践提供参考的指南