agents-md

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