AGENTS.md example
Context
This is the standing brief for the repo. Cursor loads it from the root. Other agents load it when their own file points here.
The problem
If the brief is missing, the agent invents the stack, the privacy rules, and a tour of the whole tree. The next chat does the same work again.
What you do
You write a short AGENTS.md: what the product is, how to run it, the rules that apply to every change, and which doc to open for which task.
What this achieves
Later chats start from that brief. A privacy task opens the privacy doc. A layout task does not.
Who reads it
Cursor reads AGENTS.md from the repo root. Claude Code reads it when CLAUDE.md imports it. Other coding agents that follow the AGENTS.md convention read the same file.
What it is for
This is the one rules file. It loads often, so it stays short: what the product is, how to run it, the rules that apply to every change, and pointers to longer notes.
Put the detail in docs/ and name the task that should open each file. An agent that opens every doc at the start of a chat spends the context window before it writes any code.
What goes in
- Two lines on what the product is and who it is for.
- The real stack and the commands for install, dev, test, and build.
- A folder map of a few lines, not a dump of the tree.
- Standing rules for secrets, consent, analytics, children, and legal drafts.
- Links that say which doc to open for which task, and a list of folders not to open.
Sample
AGENTS.md
# Your product name
One or two lines: what this product is, and who it is for.
## Stack
- App: Next.js, or whatever this repo actually uses
- Data: the database, if there is one
- Hosting: where it is deployed
## Commands
- Install: npm install
- Dev: npm run dev
- Test: npm test
- Build: npm run build
## Where things live
- app/ or src/ — screens and routes
- lib/ — shared logic
- docs/ — the notes linked below
## Standing rules
- Do not put secrets, customer data, or live keys in prompts, client code, or logs.
- Do not load analytics, session replay, ad tags, or remote fonts until there is a real opt-in. Reject leaves them unloaded.
- A form that collects personal data needs an explicit consent checkbox, checked again on the server. No pre-ticked box.
- Do not build for children, and do not add tracking aimed at children, unless a parent-consent path is an explicit requirement.
- Do not sell personal data. Do not add a marketing-email sender without an unsubscribe path.
- Privacy and legal pages are drafts for a lawyer. Do not invent fines, ages, or a claim that the product is a Significant Data Fiduciary.
- Before launch, run the Vibe Coding Security Checklist. These files do not replace that audit. https://papatechsolutions.com/resources/vibe-coding-security-checklist/
## Open a doc only when the task needs it
- Personal data, forms, analytics, or email: docs/data-and-privacy.md
- A new module, route, or data store: docs/architecture.md
- A trade-off worth remembering: add one paragraph to docs/decisions.md
## Do not read unless asked
node_modules/, lockfiles, .next/, out/, dist/, build/, coverage/, images, and PDFs.
## Keep the docs true
If a change makes one of those docs wrong, update that doc in the same change. Do not start a task by summarizing the whole repo.What stays out
- A second copy of the architecture or the privacy note. Link them.
- A history of every chat, or a summary of the whole repo.
- Secrets, customer data, or production URLs that are credentials.
Before launch, run the Vibe Coding Security Checklist. These files do not replace that audit. Open the Vibe Coding Security Checklist.