Back to Details

agents-md-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AGENTS.md Guide

AGENTS.md 指南

AGENTS.md is a markdown file checked into Git that customizes how AI coding agents behave in a repository. It sits at the top of the conversation history, below the system prompt. Claude Code uses CLAUDE.md instead — symlink between them:
bash
ln -s AGENTS.md CLAUDE.md
AGENTS.md是一个提交到Git中的Markdown文件，用于自定义AI编码Agent在仓库中的行为。它会被置于对话历史的顶部，系统提示词下方。Claude Code使用CLAUDE.md替代——可通过符号链接关联两者：
bash
ln -s AGENTS.md CLAUDE.md

Core Principle: Minimize Token Cost

核心原则：最小化Token成本

Every token in AGENTS.md loads on every single request, regardless of relevance. Frontier LLMs can follow ~150-200 instructions consistently. Keep the file as small as possible.
AGENTS.md中的每个Token都会在每一次请求中被加载，无论是否相关。前沿大语言模型（LLM）能够稳定遵循约150-200条指令。请尽量保持文件精简。

What Belongs in Root AGENTS.md

根目录AGENTS.md应包含的内容

Only include what is relevant to every single task in the repo:
  1. One-sentence project description — anchors the agent's understanding of scope
  2. Package manager — only if non-standard (e.g., pnpm, yarn)
  3. Build/typecheck commands — only if non-standard
Everything else goes elsewhere via progressive disclosure.
仅需纳入与仓库每一项任务都相关的信息：
  1. 一句话项目描述——帮助Agent明确理解项目范围
  2. 包管理器——仅当使用非标准工具时（如pnpm、yarn）
  3. 构建/类型检查命令——仅当使用非标准命令时
其余所有内容都应通过渐进式披露的方式存放在其他位置。

Example Minimal AGENTS.md

极简AGENTS.md示例

markdown
This is a React component library for accessible data visualization.
This project uses pnpm workspaces.
markdown
这是一个用于无障碍数据可视化的React组件库。
本项目使用pnpm工作区。

Progressive Disclosure

渐进式披露

Point the agent to other resources instead of inlining everything. Agents navigate documentation hierarchies efficiently.
Move domain-specific rules to separate files:
markdown
For TypeScript conventions, see docs/TYPESCRIPT.md
Nest references (keep one level deep from root):
docs/
├── TYPESCRIPT.md → references TESTING.md
├── TESTING.md → references specific test runners
└── BUILD.md → references esbuild configuration
External docs (Prisma, Next.js, etc.) can also be linked.
引导Agent查看其他资源，而非将所有内容内联到文件中。Agent能够高效地浏览文档层级结构。
将领域特定规则迁移至独立文件：
markdown
TypeScript规范请参考docs/TYPESCRIPT.md
嵌套引用（从根目录开始最多嵌套一层）：
docs/
├── TYPESCRIPT.md → 引用TESTING.md
├── TESTING.md → 引用特定测试运行器
└── BUILD.md → 引用esbuild配置
也可链接外部文档（如Prisma、Next.js等）。

Monorepo Strategy

单体仓库策略

Place AGENTS.md files in subdirectories — they merge with root level.
LevelContent
RootMonorepo purpose, navigation, shared tools
PackagePackage purpose, specific tech stack, local conventions
Root example:
markdown
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.
Package example (
packages/api/AGENTS.md
):
markdown
This package is a Node.js GraphQL API using Prisma.
Follow docs/API_CONVENTIONS.md for API design patterns.
在子目录中放置AGENTS.md文件——它们会与根目录的文件合并生效。
层级内容
根目录单体仓库用途、导航说明、共享工具介绍
子包子包用途、特定技术栈、本地规范
根目录示例：
markdown
这是一个包含Web服务与CLI工具的单体仓库。
使用pnpm工作区管理依赖。
请查看各子包的AGENTS.md获取具体指南。
子包示例（
packages/api/AGENTS.md
）：
markdown
本包是一个使用Prisma的Node.js GraphQL API。
API设计模式请遵循docs/API_CONVENTIONS.md。

Anti-Patterns to Avoid

需要避免的反模式

  • Documenting file paths — paths change constantly and poison context when stale; describe capabilities and project shape instead
  • Auto-generated AGENTS.md — prioritizes comprehensiveness over restraint; never use initialization scripts to generate these
  • Accumulating rules reactively — adding a rule every time the agent misbehaves creates contradictions and a "ball of mud"
  • Redundant instructions — don't tell the agent things it already knows (e.g., "write clean code")
  • Vague instructions — not actionable; wastes tokens
  • Stale documentation — especially dangerous for agents that read docs on every request; domain concepts are safer to document than file paths
  • 记录文件路径——路径会频繁变更，过时的路径会污染上下文；应描述功能与项目架构而非具体路径
  • 自动生成AGENTS.md——这类文件优先追求全面性而非精简性；切勿使用初始化脚本生成此类文件
  • 被动积累规则——每次Agent表现不佳就添加一条规则，会导致规则矛盾，形成“一团乱麻”
  • 冗余指令——无需告知Agent它已知道的内容（如“编写整洁的代码”）
  • 模糊指令——不具备可操作性，只会浪费Token
  • 过时文档——对于每次请求都会读取文档的Agent来说尤其危险；记录领域概念比记录文件路径更安全

Refactoring a Bloated AGENTS.md

重构臃肿的AGENTS.md

When the user wants to refactor an existing AGENTS.md, follow the process in references/refactoring.md.
当用户需要重构现有AGENTS.md时，请遵循references/refactoring.md中的流程。