agents-md

此技能为创建、验证和改进 AGENTS.md 文件提供专业指导。AGENTS.md 是一种用于指导 AI 编码 Agent 的开放标准格式。

什么是 AGENTS.md？

AGENTS.md 是一种用于指导编码 Agent 的简单开放格式，已被超过 60k 个开源项目采用。可以把它看作面向 Agent 的 README：一个专门、明确的位置，用于提供上下文和指令，帮助 AI 编码 Agent 在你的项目中工作。

核心原则： 与面向人类的 README.md 不同，AGENTS.md 包含编码 Agent 所需的额外详细上下文：构建步骤、测试、约定，以及可能让 README 显得杂乱的指令。

了解更多： https://agents.md/ | https://www.aihero.dev/a-complete-guide-to-agents-md

快速入门

用户想要创建 AGENTS.md 文件时

首先提出以下澄清问题：

1. 项目类型： 单体仓库还是单个软件包？
2. 技术栈： 使用哪些语言／框架？
3. 软件包管理器： npm、pnpm、yarn、bun，还是其他工具？
4. 构建／测试命令： 是否有非标准命令？
5. 具体关注点： 有哪些希望鼓励或避免的模式？

然后按照下方模板创建精简的 AGENTS.md。

用户想要验证现有 AGENTS.md 时

按照验证清单进行检查（参见下方的验证）。

用户想要改进现有 AGENTS.md 时

评估文件并建议采用渐进式披露进行重构（参见下方的改进）。

核心原则

1. 精简根目录 AGENTS.md

根目录的 AGENTS.md 应尽可能精简。每个词元都会在每次请求时加载，因此只保留适用于每一项任务的内容。

仅保留必要内容：

• 一句话的项目描述（作为基于角色的提示词）
• 软件包管理器（如果不是 npm；或使用 corepack 提示相关注意事项）
• 非标准构建／类型检查命令
• 指向渐进式披露文件的链接

2. 渐进式披露

不要把所有内容都塞进 AGENTS.md，而是只向 Agent 提供当前所需的信息，并在需要时指向其他资源。

示例——不要这样做：

## Code style

- Always use const instead of let
- Use interface instead of type when possible
- Prefer functional patterns
- No semicolons
- Single quotes only
- ... (50 more lines)

应这样做：

For TypeScript conventions, see docs/TYPESCRIPT.md

优点：

• 只有在 Agent 编写 TypeScript 时才会加载 TypeScript 规则
• 其他任务不会浪费词元
• 文件保持重点明确，并能适应模型变化

3. 描述能力，而非文件结构

文件路径经常变化。记录文件结构会导致信息过时，并主动污染上下文。

不要这样做：

Authentication logic lives in src/auth/handlers.ts

应这样做：

Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.

4. 在单体仓库中使用嵌套的 AGENTS.md

在子目录中放置 AGENTS.md 文件——它们会与根目录层级的文件合并。

层级	内容
根目录	单体仓库的用途、导航、共享工具
软件包	软件包用途、技术栈、特定约定

根目录 AGENTS.md：

This is a monorepo containing web services and CLI tools.

Use pnpm workspaces to manage dependencies.

See each package's AGENTS.md for specific guidelines.

软件包 AGENTS.md（packages/api/AGENTS.md）：

This package is a Node.js GraphQL API using Prisma.

Follow docs/API_CONVENTIONS.md for API design patterns.

内容建议

创建或改进 AGENTS.md 内容时，建议添加有助于提高代码质量的项目专属指导。只有在适用于每一项任务时，才将这些内容放在根目录文件中；否则，请链接到专门的渐进式披露文件，例如 docs/QUALITY.md、docs/TYPESCRIPT.md、docs/TESTING.md、docs/ARCHITECTURE.md 或 docs/FRONTEND.md。

代码质量

• 遵循 DRY 原则：复用现有工具、组件和模式，而不是重复实现逻辑。
• 不要重复造轮子：优先使用成熟的项目依赖和现有模块。
• 优先采用模块化架构，将代码拆分为小型、内聚且边界清晰的单元。
• 不要创建上帝组件、上帝函数或过大的文件；当代码变得难以理解时，应拆分职责。
• 质量优先于速度；如果任务留下了本可避免的设计、类型或测试债务，就不能算完成。

类型安全

• 在类型化语言中，保持完整的类型安全。
• 不要使用 any、as any 或 : any；应使用精确类型、泛型、判别联合类型或从 schema 派生的类型。
• 框架拥有生成类型的文件可例外。

验证与测试

• 完成工作时，类型检查、构建和相关测试都必须通过；如果未通过，工作就尚未完成。
• 如果无法运行验证，请说明原因以及还有哪些内容未经验证。
• 对有意义的行为（包括边界情况和回归问题）进行全面测试。
• 如果用户已在运行开发服务器，请勿再次启动；改用构建、类型检查、测试和静态检查。

前端架构

• 使用小型、可复用且职责明确的组件构建前端 UI，再将它们组合成更大的区块和页面。
• 优先使用可复用、专注的组件，而非大型的一次性组件。
• 为前端应用添加全局错误边界，确保意外的 UI 故障能得到安全处理。

模板

最精简的单包 AGENTS.md

# AGENTS.md

[One-sentence description of what this project is]

## Package Manager

This project uses [pnpm/yarn/bun]. [Optional: brief note if workspaces/monorepo]

## Build & Test

- Build: `command here`
- Test: `command here`
- Typecheck: `command here` (if non-standard)

## Progressive Disclosure

- [Domain-specific]: [path/to/file.md]

最精简的 Monorepo 根目录 AGENTS.md

# AGENTS.md

This is a monorepo containing [brief description of packages].

## Package Manager

Use [pnpm workspaces/yarn workspaces] to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines

## Packages

- [`package-name`](packages/package-name): [brief purpose]
- [`package-name`](packages/package-name): [brief purpose]

Monorepo 中包级别的 AGENTS.md

# AGENTS.md

[One-sentence description of this package]

## Tech Stack

- [Framework]
- [Language]
- [Key libraries]

## Commands

- Build: `command here`
- Test: `command here`
- Dev: `command here`

## Progressive Disclosure

- [Domain]: [path/to/file.md]

验证

验证现有的 AGENTS.md 时，请检查以下问题：

冗长指标

• 文件超过 50-75 行
• 包含应放在单独文件中的详细编码风格规则
• 详细记录文件路径
• 包含大量本应放在文档中的示例
• 包含本应放在 CONTRIBUTING.md 中的 Git 工作流说明

矛盾检测

查找相互冲突的指令：

• “使用函数式模式”与“在 X 中使用类”
• “优先使用组合”与“在 Y 中使用继承”
• “始终使用 X”与“在 Y 情况下使用 Z”

过时信息风险

• 具体文件路径（尤其是 src/ 目录）
• 文件或模块列表
• 特定版本的工具链命令
• 过时的架构说明

最佳实践合规性

• 用一句话描述项目
• 指定包管理器（如果不是 npm）
• 链接到渐进式展开文件
• 在适用时，包含或链接涵盖架构、类型安全、测试和前端要求的代码质量指南
• 使用对话式语气（而非“始终”“必须”“绝不”）
• 描述能力，而非结构

改进

重构臃肿的 AGENTS.md

使用以下流程重构臃肿的 AGENTS.md：

1. 查找矛盾：找出相互冲突的指令，并询问应保留哪些
2. 提取要点：只保留适合放在根目录 AGENTS.md 中的内容
3. 对其余内容分组：将其余指令归入合乎逻辑的类别
4. 创建文件结构：设置渐进式展开层级
5. 标记待删除内容：删除冗余、含糊或显而易见的指令

使用的提示词模板：

I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")

创建渐进式展开文件

建议的结构：

docs/
├── QUALITY.md          # Cross-cutting code quality expectations
├── TYPESCRIPT.md       # TypeScript patterns and conventions
├── TESTING.md          # Testing strategies and frameworks
├── FRONTEND.md         # Component architecture, reuse, error boundaries
├── API_CONVENTIONS.md  # API design patterns (if applicable)
├── ARCHITECTURE.md     # High-level architecture (capabilities, not file paths)
└── Git workflow items → CONTRIBUTING.md

每个文件都应：

• 专注于一个领域
• 链接到相关文件以便导航
• 描述原则，而非规定
• 在有帮助时提供示例

常见问题与解决方案

问题	解决方案
Agent 使用了错误的包管理器	明确指定：“本项目使用 pnpm”
Agent 生成了错误的命令	列出非标准的构建/测试命令
文件变得过大	采用渐进式展开——将领域规则移至单独文件
指令相互冲突	检查矛盾并予以解决
Agent 查找了错误的位置	描述能力，而非文件路径
约定随时间变得不一致	将 AGENTS.md 视为持续维护的文档，并定期审查

AGENTS.md 与 CLAUDE.md

Claude Code 使用 CLAUDE.md 而非 AGENTS.md。如需保持兼容性：

# Create a symlink from AGENTS.md to CLAUDE.md
ln -s AGENTS.md CLAUDE.md

这两个文件用途相同——用于自定义 AI 编码 Agent 在代码仓库中的行为。

支持 AGENTS.md 的工具

AGENTS.md 是许多工具支持的一项开放标准：

• OpenAI Codex、Jules（Google）、Factory、Aider、goose、opencode
• VS Code、Devin（Cognition）、Cursor、RooCode、Gemini CLI
• GitHub Copilot 编码 Agent、Windsurf（Cognition）等

完整列表请参阅 https://agents.md/。

你的方法

1. 从精简开始：仅提供必要信息
2. 逐步披露：将特定领域的规则移至单独的文件
3. 避免文件路径：描述功能，而非结构
4. 保持对话式表达：使用自然语言，而非僵化的命令
5. 定期审查：将其视为持续更新的文档
6. 使用嵌套文件：对于单体仓库，将 AGENTS.md 放在子目录中
7. 链接而非重复：指向其他资源，而不是重复内容

逐步披露

深入了解特定主题：

• 验证清单：VERIFICATION.md
• 重构指南：REFACTORING.md
• 模板集：TEMPLATES.md
• 单体仓库模式：MONOREPO.md
• 常见反模式：ANTI_PATTERNS.md