Key takeaways
- AGENTS.md is not a prompt dump; it is an operating contract.
- The file should define context, stack, rules, verification, and boundaries.
- A good operating doc reduces drift across sessions and tools.
Short Answer
An AGENTS.md file tells AI coding agents how to operate inside a project. It should define the product context, stack, folder rules, coding standards, verification commands, design expectations, and boundaries. The goal is not to make the agent obey a magic prompt. The goal is to give every future agent session the same operating context.
What An AGENTS.md Should Contain
- Project identity: what this product is and what it is not.
- Current strategic frame: goals, audience, funnel, offer, and proof assets.
- Architecture rules: stack, routes, data, env vars, integrations, and known constraints.
- Design rules: visual direction, component habits, accessibility, and mobile standards.
- Execution rules: how to inspect, edit, verify, document, commit, and deploy.
- Hard boundaries: what agents must not rename, fake, overbuild, or silently break.
Template Preview
# AGENTS.md
## Project Identity
This project is [product/company]. It exists to [business outcome]. It is not [common wrong frame].
## Current Goal
The active milestone is [specific slice]. Success means [observable acceptance criteria].
## Product Context
- Audience: [who uses it]
- Primary job: [what they are trying to do]
- Conversion/action: [what the app should drive]
## Engineering Rules
- Stack: [framework/runtime/deploy target]
- Do not introduce new dependencies unless they remove real complexity.
- Keep changes scoped to the requested slice.
- Preserve existing patterns before inventing new abstractions.
## Design Rules
- Follow the existing design system.
- Verify desktop and mobile.
- No text overlap, clipped CTAs, fake screenshots, or decorative filler.
## Verification
Run:
- npm run typecheck
- npm run lint
- npm run build
Record what changed and what remains open.Operator Proof
Bad AGENTS.md Patterns
- A giant motivational prompt with no project facts.
- Tool-specific instructions that ignore the actual product.
- Rules that say be careful but never define verification commands.
- A stale file that contradicts the current architecture.
- Instructions that hide business context from the agent and then blame the agent for drifting.