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.