review-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md Skill

Overview

概述

Creates and refactors AGENTS.md files following progressive disclosure principles. Keeps files minimal and focused—avoiding the "ball of mud" that hurts agent performance.

遵循渐进式披露原则创建和重构AGENTS.md文件。保持文件简洁聚焦——避免形成影响代理性能的“一团乱麻”。

When to Use

使用场景

Proactively when a project has no
```
AGENTS.md
```
at the root — check for this when starting work in a new project
Creating a new AGENTS.md from scratch
Refactoring a bloated AGENTS.md
Reviewing an existing file for best practices
Setting up AGENTS.md for a monorepo
When
```
AGENTS.md
```
exists but
```
CLAUDE.md
```
is missing (should be symlinked)

主动触发：当项目根目录下没有
```
AGENTS.md
```
时——在新项目中开始工作时检查此情况
从零开始创建新的AGENTS.md
重构臃肿的AGENTS.md
审查现有文件是否符合最佳实践
为单体仓库设置AGENTS.md
当
```
AGENTS.md
```
存在但
```
CLAUDE.md
```
缺失时（应创建符号链接）

Core Principles

核心原则

Minimal by default: Only include what's relevant to every single task
Progressive disclosure: Point to separate files, external docs, or agent skills for domain-specific rules
Never document file structure: It goes stale fast and poisons agent context
Describe capabilities, not locations: "Auth uses JWT" not "Auth is in src/auth/"

默认精简：仅包含与所有任务相关的内容
渐进式披露：指向独立文件、外部文档或代理技能以获取特定领域规则
绝不记录文件结构：文件结构会快速过时，污染代理上下文
描述能力而非位置：例如“认证使用JWT”而非“认证位于src/auth/”

The Instruction Budget

指令预算

Frontier LLMs can follow ~150-200 instructions with reasonable consistency. Every token in AGENTS.md loads on every request, regardless of relevance. The ideal file should be as small as possible.

前沿大语言模型（LLMs）在合理一致性下可遵循约150-200条指令。AGENTS.md中的每个标记都会在每次请求时加载，无论是否相关。理想的文件应尽可能精简。

Why Files Get Bloated

文件臃肿的原因

Agent does something wrong → you add a rule → repeat hundreds of times → "ball of mud." Different developers add conflicting opinions. Nobody does a full style pass. Auto-generated files make this worse by prioritizing comprehensiveness over restraint.

代理执行出错 → 你添加一条规则 → 重复数百次 → 形成“一团乱麻”。不同开发者添加相互矛盾的观点。没人进行完整的风格统一。自动生成的文件更甚，因为它们优先考虑全面性而非克制。

Stale Docs Poison Context

过时文档污染上下文

Humans can be skeptical of outdated docs. Agents can't — they trust what they read on every request. File paths are especially dangerous since they change constantly. Describe capabilities and domain concepts instead.

人类会对过时文档产生怀疑，但代理不会——它们会信任每次请求中读取的内容。文件路径尤其危险，因为它们经常变化。应描述能力和领域概念而非路径。

Process

流程

Phase 0: Detect Missing Files

阶段0：检测缺失文件

Check the project root for

AGENTS.md

and

CLAUDE.md

If neither exists, offer to create
```
AGENTS.md
```
and symlink
```
CLAUDE.md
```
to it

AGENTS.md

exists but

CLAUDE.md

does not, create the symlink:

ln -s AGENTS.md CLAUDE.md

CLAUDE.md

exists but

AGENTS.md

does not, rename it to

AGENTS.md

and create a symlink:

mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

If both exist but
```
CLAUDE.md
```
is not a symlink to
```
AGENTS.md
```
, merge any unique content into
```
AGENTS.md
```
, remove the standalone
```
CLAUDE.md
```
, and create the symlink

检查项目根目录下的

AGENTS.md

和

CLAUDE.md

：

如果两者都不存在，提议创建
```
AGENTS.md
```
并将
```
CLAUDE.md
```
符号链接到它
如果
```
AGENTS.md
```
存在但
```
CLAUDE.md
```
不存在，创建符号链接：
```
ln -s AGENTS.md CLAUDE.md
```

如果

CLAUDE.md

存在但

AGENTS.md

不存在，将其重命名为

AGENTS.md

并创建符号链接：

mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

如果两者都存在但
```
CLAUDE.md
```
不是指向
```
AGENTS.md
```
的符号链接，将
```
CLAUDE.md
```
中独有的内容合并到
```
AGENTS.md
```
，删除独立的
```
CLAUDE.md
```
并创建符号链接

Phase 1: Assess Current State

阶段1：评估当前状态

For new projects:

Ask about the project's purpose (one sentence)
Ask about package manager (if not npm)
Ask about non-standard build commands

For existing files:

Read the current AGENTS.md
Count lines and estimate token cost
Identify content that belongs elsewhere

对于新项目：

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

对于现有文件：

读取当前的AGENTS.md
统计行数并估算标记成本
识别应移至其他位置的内容

Phase 2: Apply the Essential Test

阶段2：应用必要性测试

Only these belong in root AGENTS.md:

Include	Why
One-sentence project description	Anchors every agent decision
Package manager (if not npm)	Prevents wrong commands
Non-standard build/test commands	Saves trial and error
Links to domain-specific docs	Progressive disclosure

Everything else goes in separate files or gets deleted.

只有以下内容应放在根目录的AGENTS.md中：

包含内容	原因
一句话项目描述	为每个代理决策提供锚点
包管理器（如果不是npm）	避免执行错误命令
非标准构建/测试命令	减少试错
指向特定领域文档的链接	渐进式披露

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

Phase 3: Identify Anti-Patterns

阶段3：识别反模式

Flag these for removal or relocation:

File tree structures: Always go stale, waste tokens
Obvious instructions: "Write clean code", "Use meaningful names"
Contradictory rules: Often from multiple contributors
Language-specific conventions: Move to
```
docs/TYPESCRIPT.md
```
etc.
Workflow instructions: Move to
```
docs/GIT.md
```
or
```
docs/TESTING.md
```

标记以下内容以便删除或迁移：

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

Phase 4: Create Progressive Disclosure Structure

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

For content that shouldn't be deleted:

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

Reference these from AGENTS.md with light-touch pointers. Keep the tone conversational — no "ALWAYS," no all-caps forcing:

markdown

For TypeScript conventions, see docs/TYPESCRIPT.md

Each file can reference the next — agents walk the tree on demand, only loading what's relevant.

Link to external docs when they're the authoritative source rather than restating them:

markdown

For database migrations, follow the Prisma migration guide.

Agent skills are another layer of progressive disclosure. Instead of embedding procedures in AGENTS.md, package them as skills the agent pulls in when needed. The root file stays focused on what and where; skills handle how.

对于不应删除的内容：

docs/
├── TYPESCRIPT.md    # TS约定
├── TESTING.md       # 测试模式
├── API.md           # API设计规则
└── GIT.md           # 提交/PR约定

在AGENTS.md中用轻量指向引用这些文件。语气保持对话式——不要使用“ALWAYS”或全大写强制表述：

markdown

TypeScript约定请参阅docs/TYPESCRIPT.md

每个文件可以引用下一个文件——代理会根据需要遍历目录树，仅加载相关内容。

当外部文档是权威来源时，直接链接而非重述：

markdown

数据库迁移请遵循Prisma迁移指南。

代理技能是渐进式披露的另一层。不要在AGENTS.md中嵌入流程，而是将它们打包为代理需要时调用的技能。根文件始终聚焦于内容是什么和在哪里；技能负责处理如何操作。

Phase 5: Handle Monorepos

阶段5：处理单体仓库

For monorepos, use nested AGENTS.md files:

Root AGENTS.md:

markdown

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

Package AGENTS.md (e.g.,

packages/api/AGENTS.md

markdown

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

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

根目录AGENTS.md：

markdown

[用途]单体仓库。使用[pnpm/yarn]工作区。
请参阅每个包的AGENTS.md了解详细信息。

包级AGENTS.md（例如

packages/api/AGENTS.md

）：

markdown

使用Prisma的GraphQL API。API设计规则请参阅docs/API_CONVENTIONS.md

Phase 6: Output

阶段6：输出

Provide:

The new/refactored AGENTS.md content
Any new files created for progressive disclosure
List of removed content with reasoning

提供以下内容：

新的/重构后的AGENTS.md内容
为渐进式披露创建的所有新文件
已删除内容的列表及原因

Output Format

输出格式

When creating a new AGENTS.md:

markdown

undefined

创建新AGENTS.md时：

markdown

undefined

[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]

undefined

[一句话描述项目用途。]

[包管理器（如果不是npm）]

[非标准命令（如有）]

[指向独立文档的轻量引用（如有需要）]

undefined

Example: Minimal AGENTS.md

示例：简洁AGENTS.md

markdown

undefined

markdown

undefined

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


That's 6 lines. Every token earns its place.

用于管理客户账户和账单的React管理面板。

使用pnpm。运行

pnpm check

进行类型检查。

API约定请参阅docs/API.md 组件模式请参阅docs/COMPONENTS.md


仅6行。每个标记都有其存在的价值。

Refactoring Prompt

重构提示

When refactoring an existing bloated file, follow these steps:

Find contradictions: Identify conflicting instructions. Ask which to keep.
Identify essentials: Extract only what belongs in root — project description, package manager, non-standard commands, content relevant to every task.
Group the rest: Organize into logical categories. Create separate files.
Create structure: Output minimal root AGENTS.md with links to separate files.
Flag for deletion: Identify instructions that are redundant, vague, or obvious.

重构现有臃肿文件时，请遵循以下步骤：

查找矛盾点：识别相互冲突的指令，询问保留哪些。
提取必要内容：仅提取根目录应保留的内容——项目描述、包管理器、非标准命令、与所有任务相关的内容。
分组其余内容：将其余内容按逻辑分类，创建独立文件。
创建结构：输出精简的根目录AGENTS.md，并链接到独立文件。
标记待删除内容：识别冗余、模糊或显而易见的指令。

Decision Framework

决策框架

Before adding anything to AGENTS.md:

Location	When to use
Root AGENTS.md	Relevant to every single task
Separate file	Relevant to one domain
Nested docs	Fits hierarchical organization
Delete it	Obvious, redundant, or vague

向AGENTS.md添加内容前，请确认：

位置	使用场景
根目录AGENTS.md	与所有任务相关
独立文件	与单个领域相关
嵌套文档	适合层级化组织
删除	显而易见、冗余或模糊

Cross-Tool Compatibility

跨工具兼容性

AGENTS.md is an open standard supported by 20+ tools including:

GitHub Copilot (Coding Agent)
Cursor
Codex (OpenAI)
Gemini CLI (Google)
Windsurf, Devin (Cognition)
Zed, Warp, VS Code
Aider, goose, RooCode

Claude Code uses

CLAUDE.md

instead.

AGENTS.md

is always the source of truth.

CLAUDE.md

must always be a symlink pointing to it:

bash

ln -s AGENTS.md CLAUDE.md

Never create a standalone

CLAUDE.md

. Never put content in

CLAUDE.md

that isn't in

AGENTS.md

AGENTS.md是一种开放标准，已被20多种工具支持，包括：

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

Claude Code使用

CLAUDE.md

替代。

AGENTS.md

始终是事实来源。

CLAUDE.md

必须始终是指向它的符号链接：

bash

ln -s AGENTS.md CLAUDE.md

切勿创建独立的

CLAUDE.md

。切勿在

CLAUDE.md

中放入未在

AGENTS.md

中存在的内容。

Resources

资源

https://agents.md — The AGENTS.md specification
https://www.aihero.dev/a-complete-guide-to-agents-md — Guide that informed this skill's best practices

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