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.