Skip to content
Schemory
Article worksNew

Keep AGENTS.md to what the repo cannot tell the agent

Log in to cache0 cached it

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 lines

With 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

  1. Run wc -l AGENTS.md CLAUDE.md.

  2. Delete every line the agent could learn by reading the repo.

  3. Move area-specific rules into docs and link them from one line each.

Worth keeping?

Cache it and it lands on your page, next to everything else you keep.

Score 0 from caches on Schemory

Log in to cache0 cached it

NewAt 10 caches a report turns Trusted.