Root, Route, Check, or Remove
Explore methods to optimize instruction placement in AI coding agent guidance files. Understand how separating instructions into Root, Route, Check, or Remove categories prevents conflicts, reduces stale knowledge, and enhances session task focus. Learn to design a clear and effective instruction map that supports reliable multi-session coding workflows.
We'll cover the following...
- Didn’t we just say to write everything down?
- How do you choose the right placement?
- What earns space in the root file?
- Should every critical rule stay in Root?
- What makes a route useful?
- Which instructions belong near the work?
- When should prose become a check?
- What should you remove instead of moving?
- Can you turn the manual into a working map?
- How do you audit an existing instruction file?
- What’s next?
Wrenfold fixed the discovery problem we worked through earlier. The team created AGENTS.md, linked every useful document, then added advice whenever an agent made a mistake. Each addition was reasonable the day it was written.
Four months later the file reached 612 lines: startup command, booking invariants, deployment runbook, a copied database schema, formatting preferences, and notes from an old timezone incident. Wrenfold had rebuilt the six-hundred-line document, this time one addition at a time, and nothing marked which sections were still current.
A fresh session opened CLIN-482 and read all of it. Line 84 told appointment services to convert local time before storage. Line 391 linked to docs/domain.md, where the current rule put conversion at the HTTP boundary. One was an instruction already in context; the other was a pointer to a file the session had not opened. It followed line 84, converted a second time, and every recurring appointment was stored an hour off the slot the patient booked. The unit tests agreed, because their fixtures converted the same way.
The repository was no longer silent. It was talking over itself.
Fix the guidance before the next session starts. Choose which instructions should remain in AGENTS.md, then select a test that would catch the second conversion. Challenge your repair to see whether you resolved both problems.
Didn’t we just say to write everything down?
Yes, but making knowledge reachable does not mean loading all of it at startup.
The Recovery Audit needs a path to each answer, not every answer inside one file. A useful entry point tells the session what the system is, what cannot be violated, where detail lives, and how completion is judged.
A manual tries to answer questions before the task is known. A map helps the session find the answer once the task is known.
Instructions compete with the ticket, source code, tool output, and working history. The problem is not a line limit: a forty-line file can be harmful if it repeats stale rules, and a longer one is justified when every line applies to every task.
Judge each instruction by placement, not length.