Better with Kent · draft

You Don't Need That Giant AGENTS.md

Same energy as useMemo — for your agent's always-on context

2019 called

“Performance optimizations are not free. They ALWAYS come with a cost but do NOT always come with a benefit.”

kentcdodds.com/blog/usememo-and-usecallback

Same disease, new file

  • System prompt ≈ CLAUDE.md ≈ AGENTS.md ≈ rules ≈ fat skills
  • Every line rides along on every request
  • Adding one more rule feels responsible
  • That feeling is the cargo cult

The receipt

Anthropic deleted most of Claude Code's prompt

System prompt cut ~80%
Evals held

“The new rules of context engineering” — claude.com blog · Thariq, Jul 2026

The cargo-cult loop

agent does something wrong → add a rule → repeat for months → ball of mud

Thoughtworks Radar named it: agent instruction bloat

Not just vibes

Measured: more context, worse results

Human-written files ≈ +4%
  • success — at higher cost
LLM-generated files ≈ −3%
  • success · +20% inference cost

ETH Zurich / LogicStar — “Evaluating AGENTS.md” · arxiv.org/abs/2602.11988

What's in the giant ones

apache/airflow 519 lines
  • repo tree + PR process novel
langchainjs 440 lines
  • package tables + env tours
cal.com 244 lines
  • tech-stack list + folder tree
the pattern discoverable
  • good docs, wrong layer

The filter

Can the agent find this by reading the repo?

Yes → cut it from the always-on file. (Same as: measure before memo.)

Keep the landmines

  • home-assistant/core (~55 lines): Python gotchas, “don't amend after PR open”
  • openai-python (~71 lines): generated-SDK landmines
  • Non-default commands · things you only learn by getting burned
  • Wait until it screams before it goes always-on

Anthropic's new rules

Then → Now

“NEVER” rule walls → judgement
put it all upfront → progressive disclosure
repeat yourself → once, in the right place

Router, not encyclopedia

my real files · always-on

kcd-youtube AGENTS.md 36 lines
kody AGENTS.md 84 lines

Behavior rules + a task router table — depth lives one link away in docs/ and skills.

Don't take Anthropic's word for it

So I audited my own agents

Pulled the transcripts. Checked what they actually read.

One day of my agents

Agents analyzed 37
Re-read AGENTS.md 0
Pulled docs / skills 86%
Opened docs/* leaves 70%

Cloud + local transcripts across kcd-youtube, kody, kentcdodds.com

Finding 1

The always-on file is a map they're handed — not a manual they study.

Zero of 37 opened it. The value is entirely in what it links to.

Finding 2

Progressive disclosure just… works

  • Agents go straight to the leaf — often skipping the index
  • Typecheck-hang bug → read exactly one doc: docs/use/execute.md → fixed
  • Entitlements task → architecture/entitlements.md, nothing else
  • Linked docs get used; ambient docs get ignored

Finding 3

The cargo cult recurses

  • Ritual reads: same “responsible” docs loaded every run, needed or not
  • Missed leaves: execute-performance agent read zero docs — execute.md was right there
  • Both are selection problems — shrinking the root file fixes neither

The actual skill

Routing quality

tiny always-on map → indexes one link away → leaf loaded on demand

Right context · right layer · right time — not zero context.

Homework (15–30 min)

  • Open your root AGENTS.md / CLAUDE.md / rules / fat skills
  • Delete everything discoverable from the repo itself
  • Keep landmines + non-default commands
  • Link the rest from a short router table

Better with Kent

Less permanent context. Better routing.

  • Stuffing instructions felt responsible — it was mostly theater
  • My own agents' transcripts back it up

Subscribe · comment · get better with me