AGENTS.md starter for engineering teams

One file at the root of your repo, read by the agent on every task. Name it AGENTS.md, or CLAUDE.md for Claude Code. Six sections, kept short.

🃏 Why each section matters

Tap a card to flip it

What this isOne paragraph of context so the agent knows what the system does and who uses it before it touches anything.CommandsExact install, test, lint and typecheck commands. Without them the agent guesses, and guessing burns turns.ArchitectureA map of the main folders and boundaries, so new code lands in the right place instead of wherever is closest.ConventionsNaming, error handling, logging and preferred libraries. The agent copies what it sees, so tell it what to copy.GuardrailsWhat never to edit and what to ask about first. Each line here prevents a mistake you already paid for once.Definition of doneThe checks a change must pass before the agent calls it finished. Turns "looks done" into "is done".

🎮 Belongs in AGENTS.md or not?

1 / 10 · Score: 0

Would this line earn its place in a file the agent reads on every task?

BelongsLeave it out

Next →

/ 10

↺ Try again

The template

# Project: <name>

## What this is
One paragraph: what the system does and who uses it.

## Commands
- Install: `...`
- Dev server: `...`
- Tests: `...` (run a single test: `...`)
- Lint / typecheck: `...`

## Architecture
- `src/api/` — ...
- `src/domain/` — ...
Key boundaries and where new code should go.

## Conventions
- Naming, error handling, logging patterns to follow.
- Libraries to prefer, and ones to avoid.

## Guardrails
- Never edit: generated files, migrations already applied, ...
- Ask before: adding dependencies, changing public APIs, ...

## Definition of done
- Tests added or updated and passing.
- Lint and typecheck clean.

Fill it in

✅ Your first version

0 / 9 completed

• Write one paragraph on what the system does and who uses it
• Paste the exact install, dev, test and lint commands
• Add how to run a single test
• List the main folders and what lives in each
• Note two or three conventions the agent should copy
• Add at least one "never edit" and one "ask before" guardrail
• Define done: tests, lint and typecheck
• Save it at the repo root as AGENTS.md or CLAUDE.md
• Give an agent a small task and check it followed the file

↺ Reset

How to use it

1. 1

   Day 1

   Start with commands

   Fill in the commands section first. It saves the most wasted agent turns.

2. 2

   Ongoing

   Grow the guardrails

   Add a guardrail every time an agent makes the same mistake twice.

3. 3

   Quarterly

   Review it

   Review the file quarterly, like any other documentation. Cut what is stale.