AGENTS.md50–200 lines
Hard constraints
- Non-negotiable
- Global
- Short and testable
Routing map
- API → api.md
- Database → database.md
- Testing → testing.md
Context budget
10–20K tokens of instructions crowd out code, tool output, and reasoning.
Why one giant instruction file fails
An entry file should route attention—not consume it.
Notes from Learn Harness Engineering · Lecture 04
AGENTS.md · 600+ lines
vs.
AGENTS.md · 50–200 lines
Overview · Commands · Hard constraints · Routes
Overview · Commands · Hard constraints · Routes
api.md
database.md
testing.md
The failure loop
1Mistake
2Add a rule
3Temporary fix
4More bloat
Lost in the middle
Critical rules buried in long text are less likely to be retrieved and followed.
Priority conflicts
Hard constraints, guidelines, and old lessons look equally important.
Maintenance decay
Adding feels free; deleting feels risky. Signal-to-noise steadily declines.
Contradictions
Rules written at different times diverge, leaving the agent to choose.
Core concepts
A quick vocabulary map for remembering why routing beats accumulation.
- Instruction bloat
- Instructions consume 10–15% of the context window, leaving less room for code, tool output, and reasoning.
- Signal-to-noise ratio
- The share of loaded instructions that actually matter to the current task. Higher SNR means less irrelevant context.
- Entry file
- A short starting point that gives the overview, commands, global constraints, and routes to deeper documentation.
- Reveal on demand
- Load broad orientation first and detailed topic rules only when needed: frequent nearby, occasional tucked away, never-used omitted.
- Can't tell what matters
- When constraints and suggestions look identical, the agent cannot reliably distinguish red lines from preferences.
The better
architecture
api.md · 50–150 linesSource · Applicability · Expiry
database.md · 50–150 linesSource · Applicability · Expiry
testing.md · 50–150 linesSource · Applicability · Expiry
Evidence
Task success rate
45% → 72%
before → afterSecurity compliance
60% → 95%
before → afterEntry file size
600 → 80
linesHow to split
1
Project overviewOne or two sentences: what the project is.
2
First-run commandsSetup, test, full verification.
3
≤15 global hard constraintsOnly rules that truly apply everywhere.
4
Topic links + conditionsSay when each document must be read.
5
50–150-line topic docsFocused guidance, near the relevant work.
6
Instruction metadataRecord source, applicability, and expiry.
Refactor checklist
- Audit instruction SNRMark relevance across five common task types.
- Split into 3–5 topic docsKeep the entry file under 100–200 lines.
- Convert historical notes to tests—or deleteDurable behavior beats narrative baggage.
- Rerun the same task setCompare success and compliance rates.
- Review regularlyRemove stale, redundant, and contradictory rules.
Takeaway