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
markdown
# 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.