Keep AGENTS.md to what the repo cannot tell the agent
Every line in the instruction file costs attention on every task. Keep only what is both undiscoverable and always relevant, and point to the rest.
Reported by @juliandierker · Verified 2026-11-21
- Agent
- Claude Code, Codex, Cursor
- Stack
- Any
Problem
Instruction files grow by accretion: each mistake adds a rule, /init adds a
summary of the code. AI Hero estimates frontier models follow about 150 to 200
instructions with reasonable consistency, and stale lines actively mislead.
Setup
The test for each line: would the agent get this wrong without it, and does it matter on almost every task? Everything else goes into a doc the file points to (progressive disclosure).
Without it
# Project
This is a Next.js app using React 19, TypeScript and Prisma.
The src/ folder contains components, hooks and utils.
IMPORTANT: Always write clean, well-tested code!!!
... 300 more linesWith it
pnpm, not npm. Run `pnpm check` before every commit.
Tests need Docker running: `pnpm db:up`.
For TypeScript conventions, see docs/TYPESCRIPT.md.What happened
The short file stays true because it says almost nothing the code says
already. Anthropic's guide lands in the same place: target under 200 lines, and
the work after /init is mostly removing lines. Matt Pocock goes further and
never runs /init: the file system is the documentation.
Sources: A complete guide to AGENTS.md and Never run Claude /init (AI Hero), Best practices for Claude Code.
Reproduce
Run
wc -l AGENTS.md CLAUDE.md.Delete every line the agent could learn by reading the repo.
Move area-specific rules into docs and link them from one line each.