Home › Coding & Cursor Rules

AGENTS.md Starter Template for Claude Code, Codex & Cursor

A drop-in AGENTS.md (or CLAUDE.md) that tells coding agents how your repo works, how to verify changes, and what never to touch.

Copy template

# AGENTS.md
<!-- Save as AGENTS.md in your repo root. Copy or symlink to CLAUDE.md for Claude Code. Keep it under ~150 lines; agents read every word. -->

## Project
- What this is: [ONE SENTENCE: WHAT THE APP DOES AND FOR WHOM]
- Stack: [e.g. TypeScript, Next.js 15, Postgres via Drizzle, Tailwind]
- Package manager: [pnpm / npm / uv / cargo]. Never switch it or add a second lockfile.

## Layout
- [src/app/]: routes and pages
- [src/lib/]: shared logic. Put new helpers here, not in components.
- [tests/]: mirrors src/. Every new module gets a test file here.
- Generated or vendored, never edit by hand: [dist/, migrations/meta/, *.gen.ts]

## Commands (run these, don't guess)
- Install: [pnpm install]
- Dev server: [pnpm dev]
- Typecheck: [pnpm typecheck]
- Lint and format: [pnpm lint --fix]
- Tests: [pnpm test]; one file: [pnpm test path/to/file]

## How to work
1. Before editing, restate the task in one line and list the files you expect to change.
2. Read the nearest existing example of the same kind of code and match its patterns.
3. Make the smallest change that solves the task. No drive-by refactors or renames.
4. After editing, run typecheck, lint, and the relevant tests. Fix what you broke before reporting done.
5. If a check fails for a reason unrelated to your change, say so instead of "fixing" it.

## Hard rules
- Never commit secrets, .env files, or real customer data. Use [.env.example] for new variables.
- Never delete or rewrite tests to make them pass.
- Never run destructive commands (drop tables, force-push, rm -rf, migrations on prod) without asking.
- Don't add a dependency without naming it and saying why the standard library or an existing dep can't do it.
- Ask before changing public APIs, database schemas, or auth logic.

## Style
- [Named exports. Functions under ~40 lines. Descriptive names over comments.]
- Errors: [throw typed errors; never swallow them silently].
- Comments explain why, not what.

## When you finish
Reply with: what changed (file list), how you verified it (commands + results), and anything left undone or risky.

## Handoff (switching agents mid-task)
If you stop before finishing, append to [HANDOFF.md]: goal, what's done, what's next, open questions, and the exact command to resume.

How to use it

1. Click Copy template.
2. Paste into ChatGPT, Claude, Grok, Cursor, or your agent framework.
3. Replace the [BRACKETED] parts with your details.

FAQ

AGENTS.md or CLAUDE.md?

Codex, Cursor, and many other agents read AGENTS.md; Claude Code reads CLAUDE.md. Keep one file and symlink or copy it to the other name.

How long should AGENTS.md be?

Short. Under about 150 lines works best, because agents load it into context on every task. Put deep detail in linked docs.

Do I still need Cursor rules?

Optional. AGENTS.md covers project-wide behavior; use .cursor/rules/*.mdc files for rules that only apply to certain file globs.

Related templates

Browse all Coding & Cursor Rules templates

New on PromptLoot