Update or create documentation so Cursor, Claude Code, and humans can orient fast. Prefer accurate, short, linked text over long dumps that will go stale.
- Preferred: Add or update
AGENTS.mdat the repository root. Many tools and agents treat this as the machine-oriented map. Keep it factual: build, test, layout, conventions. - If the repo already has a strong human
README.md: Add a short “For contributors / agents” subsection that links toAGENTS.mdinstead of duplicating everything.
AGENTS.md should include, in this order (skip sections that do not apply):
- One-line purpose — what this repo is for.
- Tech stack — languages, frameworks, major runtime (Node version, etc.), package manager.
- How to run — install, dev server, build, test (exact commands; quote scripts from
package.json/ Makefile if present). - Layout map — top-level folders and what each is responsible for (not every nested folder).
- Important paths — config files, env examples, CI, deployment.
- Conventions — naming, where new features go, patterns the codebase already uses.
- Known footguns — optional: auth, secrets, paths that differ in dev vs prod.
Do not paste entire dependency lists or full directory trees unless the repo is tiny; summarize and point to files.
Create or refresh README.md where it pays off:
| Location | Action |
|---|---|
| Repo root | Human README.md if missing; otherwise ensure link to AGENTS.md |
Each top-level app, package, service, or major area (apps/, packages/, services/, src/ domains) |
Required when non-obvious or shared by several contributors |
| Deep nested folders | Only if the folder has a distinct role, confusing name, or many entrypoints |
Each folder README.md should be short (aim under ~40 lines). Use this template:
- Purpose — one paragraph: why this folder exists.
- Contents — bullet list of meaningful files or subfolders (names + one line each), not a copy of
tree. - Depends on / used by — what it imports or what imports it (packages, apps), if non-obvious.
- See also — links to
AGENTS.md, parent README, or key source files.
If a folder only holds a few obvious files and adds no navigation value, omit the README and document it from the parent.
- Update existing docs if structure, commands, or stack changed; remove outdated sections instead of appending contradictions.
- Do not create duplicate docs that say the same thing in two places—link once, maintain once.
- Scannable: headings, bullets, tables over long prose.
- Actionable: another agent can run, test, and find the right folder without guessing.
- Honest: if something is unclear from the code, say “unclear from repo; verify with …” rather than inventing architecture.
After changes, sanity-check that links resolve and commands you quoted still exist in the repo.