Keep one short instruction file per repo, written in AGENTS.md

By vibe-coding-notes · 0 stars

We recommend one short `AGENTS.md` at the repo root holding commands, the definition of done and hard rules, with each tool's own file reduced to a pointer to it.

### Arguments

1. Every session starts with empty context. The instruction file is the one thing each tool loads automatically, which makes it the cheapest reliability gain available.
2. One file serves most agents. Codex, Cursor, the Copilot cloud agent and Claude Code all read `AGENTS.md`; Gemini CLI reads `GEMINI.md` and can import other Markdown files.
3. Duplicated rules drift. Separate `CLAUDE.md`, `.cursor/rules/*.mdc` and `.github/copilot-instructions.md` files written by hand end up contradicting each other, and an agent facing contradictory rules may follow either one.
4. Shorter files get followed. Anthropic advises keeping each `CLAUDE.md` under about 200 lines, and Codex caps combined `AGENTS.md` content at 32 KiB by default.

### Risks and counterarguments

- Tools differ in scoping. Claude Code loads parent-directory files at launch and subdirectory files on demand; Codex concatenates files from root to working directory, closer ones winning; Cursor scopes rules by globs. Split rules by path when a monorepo needs it (nested `AGENTS.md`, `.claude/rules/`, Cursor globs).
- The file is guidance, not enforcement. To block an action for certain, use permission rules or hooks.
- Personal preferences don't belong in the shared file. Use `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` or a gitignored `CLAUDE.local.md`.

### What to do next

- Put in: exact build, test, lint and run commands; what "done" means ("`npm test` and `npm run typecheck` both pass"); one line per important directory; conventions a linter can't enforce; hard rules; gotchas such as a flaky test or a required env var.
- Leave out: anything a formatter enforces, history and marketing prose, secrets and internal URLs.
- When an agent makes the same mistake twice, add a line. Delete lines that no longer hold.
- Start from this template:

~~~
Project: <name>

Commands:
- Install: <cmd>
- Test: <cmd>          (must pass before you say "done")
- Type check / lint: <cmd>
- Run locally: <cmd>

Layout:
- src/        application code
- tests/      unit tests, mirror src/ paths

Rules:
- Work on a feature branch; never commit to main.
- Do not add dependencies without asking.
- Do not edit files under generated/.
- Keep changes minimal; do not reformat unrelated code.

Gotchas:
- <anything that surprised you or the agent before>
~~~

### Sources

- https://code.claude.com/docs/en/memory
- https://agents.md/
- https://github.com/openai/codex
- https://cursor.com/docs/rules
- https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
- https://geminicli.com/docs/cli/gemini-md/