Chapter 30 · AGENTS.md Standard: A README for Agents

Chapter goals: Understand the positioning and design philosophy of the AGENTS.md open standard; master the typical content structure and monorepo nesting rules; learn to write a high-quality agentinstruction manual for your project.

30.1 What Is AGENTS.md

AGENTS.md is a simple, open format standard for guiding coding agents to work in your project. The official definition is incisive:

Think of AGENTS.md as a README for agents —— treat it as a README for agents to read.

It was发起 by teams at OpenAI Codex, Amp, Google Jules, Cursor, Factory, etc. It is currently hosted by the Agentic AI Foundation under the Linux Foundation, and has been adopted by 60,000+ open-source projects. Repository: agentsmd/agents.md.

README.md   → Written for humans: quickstart, project intro, contributing guide
AGENTS.md   → Written for agents: build steps, test commands, code conventions, and other machine-executable context

Why split into two files? Because the audiences differ:

• Information for humans讲究简洁聚焦; too many details and nobody reads;
• Agents need precise, executable instructions — build commands, testing methods, code style; stuffing these into README makes it bloated;
• After the split, agents have a明确, predictable instruction entry point; no need to guess which doc to read.

One file, universal across the ecosystem

AGENTS.md was designed to avoid reinventing a私有 format: the same file can被 Codex, Jules, goose, opencode, Zed, Devin, Cursor, Gemini CLI, GitHub Copilot coding agent, Windsurf, and dozens of other tools直接 read.

30.2 Typical Content and Format Conventions

AGENTS.md is pure Markdown, no强制 schema, no required fields — the agent simply parses the text you write. The official建议覆盖 these high-frequency topics:

Common Section	Content Example
Project overview	One sentence explaining what the project does
Build and test commands	Exact commands for installing deps, starting the dev server, running tests
Code style guidelines	Formatting rules, language特性 preferences
Testing instructions	CI plan location; how to run only a specific test
Security considerations	Secret management, sensitive directories
PR instructions	Commit message format; pre-submit checklist

Below is a realistic-style example (adapted from the official sample):

# Sample AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump directly to the对应包;
  don't use ls to翻目录 one by one.
- When adding a new包, use `pnpm install --filter <project_name>`;
  so Vite / ESLint / TypeScript can see it.

## Testing instructions
- CI plans are in the .github/workflows directory.
- Run `pnpm test` directly at the包 root; must be全部 green before merge.
- After moving files or modifying imports,补 run `pnpm lint --filter <project_name>`.

## PR instructions
- Title format: [<project_name>] <title>
- Must跑 `pnpm lint` and `pnpm test` before committing.

Note the共性 of these instructions: executable and verifiable. The official FAQ明确 — as long as you list test commands in the file, the agent will真正执行 them and尝试修复 failures before结束. So writing "run pnpm test" is远 more effective than writing "please ensure质量."

30.3 Nesting and Priority Rules

Large monorepos can放 more AGENTS.md files in subdirectories:

my-monorepo/
├── AGENTS.md                  # Root-level: conventions通用 to the whole repo
├── apps/
│   └── web/
│       └── AGENTS.md          # Frontend子项目专属 conventions
└── services/
    └── api/
        └── AGENTS.md          # Backend子项目专属 conventions

Two core rules (from the official FAQ):

1. Nearest wins: when the agent edits a file, it自动 reads the AGENTS.md on the directory tree closest to it; the closer the higher the priority. So each子项目 can give定制指令 — OpenAI's own主 repo had 88 AGENTS.md files when writing this article;
2. Conversation wins: if instructions冲突, the user's explicit prompt in the chatoverrides everything;其次 is the nearest AGENTS.md.

Priority (high → low):
User's explicit要求 in the current conversation  >  the nearest AGENTS.md  >  a higher-level AGENTS.md

30.4 Ecosystem Support and Similar Conventions

Mainstream coding agents have very广泛 support for AGENTS.md: OpenAI Codex, Google Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin (Cognition), Cursor, RooCode, Gemini CLI, GitHub Copilot coding agent, Windsurf, etc.

Two practicalcompatibility details:

• Claude Code uses the同类约定 CLAUDE.md (内容思路一致); many projects直接软链 one to the other, or keep the content同步;
• Some tools需要一行 config to enable support, e.g. Aider and Gemini CLI:

# .aider.conf.yml — let Aider read AGENTS.md
read: AGENTS.md

// .gemini/settings.json — let Gemini CLI use AGENTS.md as the context file
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Have an old file to migrate? The official command is one line rename plus soft-link fallback:

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

30.5 Division of Labor vs Skills:常驻 Context vs On-Demand Capability

After learning Chapter 16 on Agent Skills, a natural question: what's the difference between AGENTS.md and SKILL.md? When to use which?

Dimension	AGENTS.md	Skill (SKILL.md)
Load timing	常驻 context at session start	On-demand load when the task匹配s (progressive disclosure)
Positioning	Project-level conventions and facts	Reusable capability packs (workflow + scripts + resources)
Scale	Keep concise; within几十 lines	Can be very long; can also携带 scripts and reference docs
Scope	One repo/directory	Distributed with the skill directory;可跨-project reuse

One-sentence memory: AGENTS.md tells the agent "what the rules of this project are"; Skill tells it "the standard operating procedure for doing this kind of thing." The two are互补, not替代 — in Chapter 19 you'll see Loop Engineering纳入 them together into the loop's blocks.

30.6 Writing Best Practices

Combining实战经验 from 60k+ projects in the official示例 repo, summarize five principles:

1. Executable commands first:写 exact command lines (pnpm test), not抽象 requirements ("ensure tests pass");
2. Be concise: it's a常驻 context; every line consumes tokens. Delete content duplicated with README; only留 the增量 info the agent needs;
3. Write "new hire onboarding": the判断 criterion is simple — anything you'd tell a新同事 on their first day belongs here;
4. Treat as a living doc: update it when conventions change; stale instructions are worse than无 instructions;
5. Use nesting in monorepos:下沉包级别的特殊约定 to subdirectories; don't堆成百宝箱 in the root file.

Chapter Summary

• AGENTS.md is an open standard: "a README for agents"; adopted by 60k+ projects; hosted by the Linux Foundation;
• Pure Markdown, no强制 schema; common sections: build/test commands, code style, PR conventions, security considerations;
• Monorepos support nesting; nearest wins; explicit instructions in user conversationsoverride everything;
• Division of labor vs Skills: AGENTS.md is the常驻 project convention; Skills are the on-demand capability packs;
• Best practices: executable commands first, concise and non-duplicated, treat as a living doc.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the core reason for separating AGENTS.md from README.md?

2. In a monorepo where both the root and apps/web/ subdirectory have AGENTS.md, which oneprevails when the agent edits apps/web/src/App.tsx?

3. Regarding test commands listed in AGENTS.md, what does the official FAQ say?

4. Which of the following tasks is most适合 putting into AGENTS.md rather than writing as a Skill?

🛠️ Hands-on Practice

After completing, proceed to Next chapter: Capstone — Wiring the Five-Piece Set into a Complete Workflow.