AGENTS.md
Overview
AGENTS.md is a community convention for providing project-specific guidance to AI coding agents. Think of it as a README for agents — containing the tribal knowledge that senior engineers carry: build steps, test commands, architectural conventions, and coding standards. Adopted by 60,000+ open-source projects and supported by Claude Code, Codex, Gemini CLI, Jules, Factory, and Cursor.
File Placement
| Location |
Scope |
AGENTS.md (repo root) |
Applies to the entire repository |
src/AGENTS.md |
Applies to the src/ directory and below |
src/api/AGENTS.md |
Applies to src/api/ specifically |
Agents read the most specific AGENTS.md for the files they're working on, inheriting from parent directories.
Recommended Structure
# AGENTS.md
## Build & Test
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Single test: `npm test -- --grep "test name"`
## Architecture
- Monorepo with packages in `packages/`
- API server in `packages/api/` (Express + TypeScript)
- Frontend in `packages/web/` (React + Vite)
- Shared types in `packages/shared/`
## Conventions
- Use TypeScript strict mode
- Prefer `async/await` over `.then()` chains
- Use named exports, not default exports
- Error messages must be user-facing strings, not developer jargon
## Testing
- Unit tests live next to source files: `foo.test.ts`
- Integration tests in `tests/integration/`
- Use `vitest` for all tests
- Mock external APIs, never hit real endpoints in tests
## Do NOT
- Do not modify `generated/` files — they are auto-generated
- Do not add dependencies without checking `package.json` first
- Do not use `any` type in TypeScript
Content Guidelines
- Aim for under 150 lines — concise beats comprehensive
- Use concrete rules, not vague guidance: "Use vitest" not "Use a good test framework"
- Include exact commands:
npm run build, not "run the build"
- Organize by category: Build, Architecture, Conventions, Testing, Do-NOTs
- Use bullet points for scanability
- Include code examples where conventions aren't obvious
What to Include
- Build, test, and lint commands (exact CLI invocations)
- Project structure and key directories
- Naming conventions (files, variables, branches)
- Technology choices and versions
- Error handling patterns
- Things to avoid (common mistakes agents make in this codebase)
What NOT to Include
- General programming advice agents already know
- Full API documentation (link to it instead)
- Sensitive information (secrets, internal URLs)
- Information that changes frequently (use links to living docs)
AGENTS.md vs Agent Skills
| Aspect |
AGENTS.md |
Agent Skills (SKILL.md) |
| Scope |
One specific project/repo |
Reusable across any project |
| Content |
Build steps, conventions, architecture |
Framework guidance, tool knowledge |
| Discovery |
Found in repo directories |
Discovered via skill registries |
| Format |
Freeform Markdown |
YAML frontmatter + Markdown |
They complement each other: AGENTS.md provides project-specific context while Agent Skills provide domain knowledge.
Best Practices
- Keep it under 150 lines — agents have limited context, so density matters.
- Put the most important commands (build, test) at the top.
- Update AGENTS.md when you change build processes or conventions.
- Use directory-scoped AGENTS.md files for large monorepos instead of one giant root file.
- Test your AGENTS.md by asking an agent to perform a task and seeing if it follows the guidance.
- Don't duplicate README content — AGENTS.md is for agent-specific instructions that would clutter a README.
1---2name: agents-md-43description: Use when creating or updating AGENTS.md files to guide AI coding agents. Covers file structure, placement, content guidelines, and best practices for project-level agent instructions. USE FOR: project-specific agent instructions, build/test commands for agents, coding conventions, repository-level guidance DO NOT USE FOR: reusable cross-project skills (use agent-skills), agent runtime definition (use adl)4license: MIT5---6
7# AGENTS.md
8
9## Overview
10AGENTS.md is a community convention for providing project-specific guidance to AI coding agents. Think of it as a README for agents — containing the tribal knowledge that senior engineers carry: build steps, test commands, architectural conventions, and coding standards. Adopted by 60,000+ open-source projects and supported by Claude Code, Codex, Gemini CLI, Jules, Factory, and Cursor.
11
12## File Placement
13| Location | Scope |
14|----------|-------|
15| `AGENTS.md` (repo root) | Applies to the entire repository |
16| `src/AGENTS.md` | Applies to the `src/` directory and below |
17| `src/api/AGENTS.md` | Applies to `src/api/` specifically |
18
19Agents read the most specific AGENTS.md for the files they're working on, inheriting from parent directories.
20
21## Recommended Structure
22```markdown
23# AGENTS.md
24
25## Build & Test
26- Build: `npm run build`
27- Test: `npm test`
28- Lint: `npm run lint`
29- Single test: `npm test -- --grep "test name"`
30
31## Architecture
32- Monorepo with packages in `packages/`
33- API server in `packages/api/` (Express + TypeScript)
34- Frontend in `packages/web/` (React + Vite)
35- Shared types in `packages/shared/`
36
37## Conventions
38- Use TypeScript strict mode
39- Prefer `async/await` over `.then()` chains
40- Use named exports, not default exports
41- Error messages must be user-facing strings, not developer jargon
42
43## Testing
44- Unit tests live next to source files: `foo.test.ts`
45- Integration tests in `tests/integration/`
46- Use `vitest` for all tests
47- Mock external APIs, never hit real endpoints in tests
48
49## Do NOT
50- Do not modify `generated/` files — they are auto-generated
51- Do not add dependencies without checking `package.json` first
52- Do not use `any` type in TypeScript
53```
54
55## Content Guidelines
56- **Aim for under 150 lines** — concise beats comprehensive
57- **Use concrete rules**, not vague guidance: "Use vitest" not "Use a good test framework"
58- **Include exact commands**: `npm run build`, not "run the build"
59- **Organize by category**: Build, Architecture, Conventions, Testing, Do-NOTs
60- **Use bullet points** for scanability
61- **Include code examples** where conventions aren't obvious
62
63## What to Include
64- Build, test, and lint commands (exact CLI invocations)
65- Project structure and key directories
66- Naming conventions (files, variables, branches)
67- Technology choices and versions
68- Error handling patterns
69- Things to avoid (common mistakes agents make in this codebase)
70
71## What NOT to Include
72- General programming advice agents already know
73- Full API documentation (link to it instead)
74- Sensitive information (secrets, internal URLs)
75- Information that changes frequently (use links to living docs)
76
77## AGENTS.md vs Agent Skills
78| Aspect | AGENTS.md | Agent Skills (SKILL.md) |
79|--------|-----------|------------------------|
80| Scope | One specific project/repo | Reusable across any project |
81| Content | Build steps, conventions, architecture | Framework guidance, tool knowledge |
82| Discovery | Found in repo directories | Discovered via skill registries |
83| Format | Freeform Markdown | YAML frontmatter + Markdown |
84
85They complement each other: AGENTS.md provides project-specific context while Agent Skills provide domain knowledge.
86
87## Best Practices
88- Keep it under 150 lines — agents have limited context, so density matters.
89- Put the most important commands (build, test) at the top.
90- Update AGENTS.md when you change build processes or conventions.
91- Use directory-scoped AGENTS.md files for large monorepos instead of one giant root file.
92- Test your AGENTS.md by asking an agent to perform a task and seeing if it follows the guidance.
93- Don't duplicate README content — AGENTS.md is for agent-specific instructions that would clutter a README.
majiayu000