Record what an agent would otherwise guess incorrectly. Read existing context files and their scope before editing; keep one authoritative home for each rule.
Work
- Verify project purpose, commands, runtime, paths, and architecture from the workspace. Never invent a test command or an existing component.
- Capture consequential boundaries: where secrets and authorization live, who owns cached data, token/component sources, and generated files.
- Include the actual checks and observable evidence expected for the work. Distinguish lint/build from rendered or behavioral verification.
- Separate durable conventions from task-specific plans. Link focused supporting docs instead of embedding complete manuals.
- Reconcile contradictions and stale instructions, including blanket lockfile bans, duplicate formatting stacks, and obsolete paths. Preserve explicit user policies unless asked to change them.
- Match the client and file format already in use. If adding client-specific discovery rules, verify current client documentation; do not claim every client loads every filename.
Deliver
Update the requested file, or provide a ready-to-use draft when edits were not requested. Usually include purpose, commands, important paths, non-obvious constraints, and verification. Omit empty sections and generic coding advice.
# AGENTS.md
[One line: what the product is and who it serves]
Commands
Where things live
Rules an agent would otherwise get wrong
Verification
Add a section only when it holds something an agent would otherwise get wrong.
Example: “Tokens live in app/globals.css. Docs styles consume them in app/docs-theme.css. Run pnpm build to validate MDX routes.” This is more useful than “write clean code.”
Check every referenced local command and path; label external or future dependencies. The file guides authorized work, not permission to publish or expand a task.
## Worked example
**Detected:** pnpm lockfile; `check` and `test` scripts in `package.json`; tokens in `src/styles/tokens.css`; server actions in `src/server/`; no end-to-end script. The old file banned lockfile edits and named a `dev` branch that no longer exists.
**Changed:** replaced the lockfile ban with the package-manager rule, removed the stale branch rule, and cut generic style advice.
```markdown
# AGENTS.md
Scheduling dashboard for a construction client. Versions and dependencies: see `package.json`.
## Commands
- `pnpm check`: lint and type checks; run before every PR
- `pnpm test`: unit tests. There is no end-to-end suite yet; do not claim one ran.
- Change dependencies with `pnpm add` or `pnpm remove` so `pnpm-lock.yaml` updates with them; do not hand-edit it.
## Where things live
- `src/styles/tokens.css` is the only token source; feature code uses token names, not raw color values
- `src/components/ui/` holds primitives; check it before creating a component
- `src/server/` enforces permissions for every write; hiding a button in the UI is not access control
## Verification
- UI changes need a rendered check at narrow and wide widths plus a keyboard pass; `pnpm check` alone does not verify them
Gotchas
- The usual invented command is a plausible one:
npm testin a pnpm repository, or a script the README mentions but the manifest dropped. - Context files load on every task, so a generic line ("write clean code") costs attention and changes nothing.
- A blanket ban ("never touch the lockfile") blocks legitimate work and gets ignored; state the safe way instead.
- Copies of the same rules in several client files drift apart; keep one source and point the others at it.
- A line that mentions a ticket, a date, or "for now" is a task plan; it belongs in the pull request.
Boundaries
- Do not use to create the repository's structure, commands, or environment strategy; use
$setupinstead. This skill records what exists. - Do not use to decide branch, review, or merge policy; use
$gitto plan it, then record the outcome here.