AGENTS.md Template
Minimal sections every repo-level AGENTS.md should include. Adapt stack lines to your project.
Last reviewed: June 2026
Full guide: Project Rules · Comparison: Rules vs AGENTS.md vs Skills
Full template
Copy to repo root as AGENTS.md:
# Project instructions for AI agents
## Stack
- Next.js 15 App Router, React 19, TypeScript 5.7 strict
- Tailwind CSS 4
- Package manager: npm
## Commands
- Install: npm install
- Dev: npm run dev
- Lint: npm run lint
- Test: npm test
- Build: npm run build
## Conventions
- Match existing file structure and naming
- Minimal diffs — do not refactor unrelated code
- Named exports unless framework requires default
## Do not modify
- package-lock.json unless adding a dependency I requested
- CI workflow files unless the task requires it
- .env and secret files
- Generated migration files
## Verification
After code changes, run npm run lint and npm test.
Report failures with exact command output.
Section reference
| Section | Purpose |
|---|---|
| Stack | Framework versions — stops App Router vs Pages mistakes |
| Commands | Exact lint/test/build — agent runs correct verification |
| Conventions | Style and scope — reduces drive-by refactors |
| Do not modify | Protected paths — migrations, lockfiles, CI |
| Verification | Required gates before task is "done" |
Optional sections
| Section | When to add |
|---|---|
| Architecture | Monorepo layout, service boundaries |
| Auth | How session checks work on API routes |
| Testing | Where tests live; coverage expectations |
| PR process | Branch naming, commit format |
| Links | CONTRIBUTING.md, internal runbooks |
Size limits
| Target | Reason |
|---|---|
| 500–2,000 tokens | Loaded every session |
| Procedural checklists | Move to Agent Skills |
| Path-specific rules | Use .cursor/rules/*.mdc with globs |
Tool-specific mirrors
| File | Tool |
|---|---|
AGENTS.md | Cursor, Claude Code, generic agents |
.github/copilot-instructions.md | GitHub Copilot |
.cursor/rules/*.mdc | Cursor path-scoped rules |
Keep stack/commands in sync across files — one source of truth in AGENTS.md; others reference or duplicate minimally.