Split Instructions Across Files

You got serious about the harness and crammed every rule into one AGENTS.md. Six hundred lines later, the agent is somehow doing worse. Welcome to the giant-instruction-file trap.

💡A kitchen, not a junk drawer

A good cook does not keep every spice, pan, and gadget on the counter. The three things you reach for constantly stay within arm’s reach; the rest live in labelled drawers you open only when a recipe needs them. An entry file is the counter, short and essential. Topic docs are the drawers.

Why the monolith rots

The cycle feels reasonable: the agent makes a mistake, you add a rule, repeat. But the cumulative effect is destructive:

Context budget, a 600-line file can burn 10, 20k tokens before the agent has read a single source file.
Lost in the middle, a hard constraint buried at line 300 is reliably ignored; models use the start and end of long text far better than the middle.
Priority collapse, a non-negotiable ("never use eval()") looks identical to a passing preference, so the agent cannot tell a red line from a suggestion.
Contradiction drift, rules added months apart quietly conflict, and the agent picks one at random.

flowchart TB
  Mono["One 600-line AGENTS.md"] --> Bug["Even a small fix reads all the deploy rules"]
  Bug --> Miss["Critical rule buried in the middle, ignored"]
  Router["Short AGENTS.md"] --> Topic["Read API or DB docs only when needed"]
  Topic --> Room["More context left for the actual code"]

A router entry file plus on-demand topic docs beats one monolith.

The entry file is a router

Keep AGENTS.md short, 50 to 200 lines, holding only a one-line project overview, the first-run commands, a small set of non-negotiable constraints, and links to topic docs with a "read this when…" condition.

AGENTS.md

# AGENTS.md, entry / router
Overview: Rust control plane; agents run in tmux.
Setup: make setup && make test
Hard rules: no secrets in code; all PRs pass make check
Topic docs:
  docs/api.md      # when adding endpoints
  docs/tmux.md     # when touching session handling
  docs/testing.md  # when writing tests

Each topic doc is 50, 150 lines and only loaded when the task needs it. Information that belongs next to code (types, interface comments) stays in the code, where the agent sees it naturally.

Manage rules like dependencies

Every rule should record why it was added, when it applies, and when it can be removed. Audit regularly and delete the dead ones, an unused rule is not free, it is noise that lowers the signal-to-noise of everything around it. If a rule absolutely must live in the entry file, put it at the very top or bottom, never the middle.

How Agentum applies it

Agentum's .agentum-harness/AGENTS.md is the entry file done right: it is short and protocol-focused, work only the feature you are handed, make the smallest change that passes the gate, stop and wait, never touch .agentum-harness/. The per-feature detail does not live in it; it lives in each feature's description inside feature_list.json, and the engine loads exactly one at a time. Routing, not an encyclopedia.

Key takeaways

A giant instruction file lowers performance: wasted budget, buried rules, contradictions.
Make the entry file a short router; push detail into topic docs loaded on demand.
Exploit position: keep critical items at the top or bottom, never the middle.
Audit rules like dependencies, every one needs a reason, a scope, and an expiry.

Exercises

Measure the noise. For a typical bug fix, what fraction of your instruction file is actually relevant? Move the rest to topic docs.
Check the middle. Find a critical rule buried mid-file and move it to the top or into a topic doc.