AGENTS.md starter for any stack
A free, concise AGENTS.md starter for Codex, Copilot, Cursor and other coding agents: project summary, commands, layout, workflow, rules and definition of done.
- Install
AGENTS.md (project root)- Last tested
- Codex / Copilot / Cursor · 2026-10-15
AGENTS.md is a plain Markdown file at the root of your repo that tells coding agents how to work in the project. It's a convention that several agents support, including Codex, GitHub Copilot's coding agent and Cursor, so one file can brief all of them.
This starter isn't tied to a stack. Fill in the bracketed project summary, commands and layout, then keep the workflow, rules and definition of done as they are or tighten them. The rules cover the usual failure modes: leaked secrets, sprawling diffs, destructive commands run without asking, and false claims that something passes.
Keep it short. A small file is easier to keep accurate, so add a rule when you see the agent repeat a mistake rather than up front. Building on Next.js? The paid Next.js pack goes further, with rules written for Next.js specifically.
AGENTS.md# AGENTS.md
Instructions for AI coding agents (Codex, Copilot, Cursor, Claude Code and others) working in this repo. Humans: see `README.md`.
## Project
- What it is: [one sentence: what this project does and who uses it]
- Stack: [language, framework, package manager, database, hosting]
- Status: [prototype / in production / maintenance only]
## Commands
- Install: `[pnpm install]`
- Dev server: `[pnpm dev]`
- Tests: `[pnpm test]` (single file: `[pnpm test path/to/file]`)
- Lint: `[pnpm lint]`
- Typecheck: `[pnpm typecheck]`
- Build: `[pnpm build]`
Use these exact commands. Don't switch package managers or add new scripts without asking.
## Layout
- `[src/]` application code
- `[src/lib/]` shared logic, no UI
- `[tests/]` tests, mirroring source paths
- `[scripts/]` one-off and maintenance scripts
- Generated or vendored (don't edit by hand): `[dist/, build/, node_modules/]`
## Workflow
1. Read the files you'll change, plus one similar existing file, before editing. Match its patterns and naming.
2. For anything non-trivial, write a short plan first. Stop and ask if it changes a public API, data model or dependency.
3. Make small, focused changes. Run the relevant tests after each meaningful step.
4. If a requirement is ambiguous, state your assumption and proceed.
## Rules
- Never commit secrets, tokens or keys. Don't create or edit `.env*` files; reference env var names only.
- Keep diffs minimal: don't rename, reformat or refactor unrelated code.
- Ask before destructive or irreversible commands: deleting files or data, dropping tables, force-pushing, rewriting git history, `rm -rf`, production deploys.
- Don't add a dependency without saying why and what the alternative was.
- Don't silence errors, skip checks or delete failing tests to get green. Fix the cause or report it.
- Never invent APIs, config keys or CLI flags. If you can't find it in the code or the installed package, say so.
## Definition of done
A task is done only when:
1. Lint, typecheck and tests pass (commands above).
2. The build passes.
3. New logic has tests, if the project has tests.
4. You've summarized what changed by file, what you ran, and anything left undone.
If you couldn't run a check, say which one. Never claim something passes without running it.
12 scoped Cursor rules, AGENTS.md and CLAUDE.md for Next.js 16.4 with Cache Components. This free entry is one file; the pack is the full multi-file set.
