AGENTS.md Examples & Templates for AI Coding Agents

# AGENTS.md

## Project
[One line: what this repo is and who uses it.]

## Setup
- Install: `npm install`
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Conventions
- Language: [TypeScript, strict mode]
- Run the formatter before committing; do not hand-format.
- Keep changes small and focused; match the style of the file you are editing.

## Definition of done
- The change builds and all tests pass.
- No new lint errors.
- You ran the affected feature and saw it work, not just "it should work."

## Do not
- Do not edit generated files or lockfiles by hand.
- Do not add dependencies without noting why.
- Do not touch anything outside the task.

AGENTS.md is the tool-neutral version of CLAUDE.md: Codex, Cursor and others read it, so one file steers every agent.

# AGENTS.md

## The one rule
Prove your work ran. For every change, report what you ran and what you saw. "I think this works" is not done.

## Workflow
1. Reproduce the bug, or state the feature's expected behavior, first.
2. Make the smallest change that fits the surrounding code.
3. Run the tests and the affected path; paste the real output.
4. Revert any change outside the task.

## Commands
- Test: `[your test command]`
- Lint: `[your lint command]`
- Run locally: `[your run command]`

## Never
- Never weaken or delete a test to make it pass; fix the code under test.
- Never commit secrets, keys or .env files.
- Never break backwards compatibility without saying so.

The 'paste the real output' rule is what stops an agent from confidently reporting a fix that never ran.

# AGENTS.md

## Stack
Next.js (App Router), TypeScript, Tailwind. Server Components by default.

## Setup
- `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`

## Rules
- Use Server Components unless you need interactivity; add "use client" only when required.
- Fetch data in Server Components or route handlers, never in useEffect for the initial load.
- Keep components small; colocate files by feature under app/.
- Style with Tailwind; no inline style objects.

## Done
- `pnpm typecheck` and `pnpm test` pass, the page renders, nothing else broke.

Naming the exact commands and the 'done' bar up front means the agent verifies itself instead of guessing.

# AGENTS.md

## Stack
Python 3.12, uv for dependencies, ruff for lint and format, pytest.

## Setup
- `uv sync`
- Test: `uv run pytest`
- Lint: `uv run ruff check .`
- Format: `uv run ruff format .`

## Rules
- Type-hint public functions; keep functions small and pure where you can.
- Add or update a test with every behavior change.
- No bare `except:` clauses; catch specific exceptions.
- Run ruff before you finish.

## Done
- pytest is green, ruff is clean, and the feature runs on a real input.

A short, exact toolchain block stops the agent from inventing pip/venv commands your project does not use.

# AGENTS.md (root)

This is a monorepo. Each package may have its own AGENTS.md that overrides this one for that package.

## Layout
- apps/ - deployable apps
- packages/ - shared libraries

## Rules
- Change only the package the task names; do not edit sibling packages to "fix" an import.
- Shared code goes in packages/, never copy-pasted between apps.
- Run the affected package's tests, plus anything that imports it.

## Commands
- Install: `pnpm install`
- Test one package: `pnpm --filter <pkg> test`
- Build all: `pnpm build`

The per-package override rule plus 'change only the named package' is what keeps agents from sprawling across a monorepo.

# CLAUDE.md

This project uses AGENTS.md as the single source of truth for agent instructions.
Read ./AGENTS.md and follow it.

Claude-specific notes only below this line:
- [Any Claude Code-only preferences, e.g. which subagents to use, hooks, or slash commands.]

One AGENTS.md, referenced from a tiny CLAUDE.md, keeps Claude Code and every other tool in sync instead of drifting across two files.