Documentation for agents that actually do the job
A practical documentation setup for giving coding agents enough context to work properly without drowning them in noise.
The Usual Docs Problem
Most project documentation is either too thin to help or too big to read.
A README with three outdated commands and a dream.A planning folder full of old decisions nobody trusts anymore.A pile of notes that made sense to one person six months ago.
Good luck out there.
So we took a different route.
The goal was not to document everything. The goal was to give coding agents enough context to work properly without drowning them in noise.
Because that is the real problem now.
Modern agents can read code. They can infer patterns. They can follow tests, inspect components, trace data flow, and figure out a lot from the repo itself. What they cannot magically know is where the sharp edges are. Which integrations have weird failure modes. Which files are source of truth. Which decisions are intentional. Which "obvious fix" is actually the thing that broke production last time.
That is where the documentation setup matters.
Not big documentation. Useful documentation.
The Agent Guide
The first layer is simple: one root guide.
The agent should know what the project is, what stack it uses, how to run it, how to validate changes, and what boundaries not to cross.
That sounds basic, but it makes a big difference.
If a project uses a frontend framework, a CMS, database views, external listing data, server-side forms, notification flows, metadata routes, and a handful of deployment constraints, an agent should not have to rediscover all of that from scratch every time.
But it also should not read a novel before fixing a button.
So the guide stays lean. It gives the default loop: understand the request, inspect relevant code, load extra context only when needed, make the smallest coherent change, validate properly, report what happened.
Very grown-up. Very unglamorous. Very useful.
The Context Router
The strongest part is the routing system.
Instead of telling agents to read every doc before every task, the project has a small context router. If the task touches CMS content, read the CMS docs. If it touches listings, read the listing data and backend notes. If it touches forms, read the form submission and notification docs. If it touches metadata, read the metadata routing docs.
That means the agent gets the right context at the right moment.
Not all context all the time.Not "please study our entire company history before changing a label."
Just the smallest useful map for the job in front of it.
That is the difference between documentation as storage and documentation as tooling.
A real task lands. The agent reads the lean guide, pulls only the docs the job needs, then lets the repo do the rest of the teaching.
Enough map to move, not enough paper to sink
What the agent reads
One guide is always loaded. The rest only shows up when the job touches that part of the repo.
Starting point
A real task lands
A button fix, form bug, or weird route arrives with repo state and risk.
Always loaded
Agent guide
Stack, commands, validation, and lines not to cross.
Selective context
Context router
CMS, listings, forms, metadata. Pull only the map the task touches.
Loaded on demand
Sharp edges
Source truth, failure modes, and the fix that broke prod last time.
What the agent does
The docs do not do the thinking. They stop the boring mistakes, then get out of the way.
Source material
The repo still teaches
Components, tests, routes, data flow, habits. Most answers stay in the code.
Execution loop
Patch, validate, explain
Make the smallest proper change, run the right checks, say what happened.
Feedback loop
Keep it alive
Add real rules, delete old fear, keep the docs small.
Gotchas Where They Belong
The other important layer is gotchas.
Not vague warnings. Not generic framework advice. Actual failure prevention.
Things like: this media source needs guarded headers. This build mode has a local quirk. This form flow must not leak server diagnostics. These CMS fields are optional until they suddenly hit a strict media or link API. These listing records come from the sync pipeline, not a local data file someone felt like making.
That kind of knowledge is expensive.
Usually it lives in someone's head, a team chat thread, or the memory of a production bug. Here, it gets turned into small targeted docs that agents only read when the task enters that domain.
The important part is restraint.
Every rule has to earn its place. What mistake does it prevent? Has that mistake actually happened? Could the agent infer it from code? Should this be always-loaded guidance, or just a scoped gotcha?
Because too much guidance becomes its own bug.
Planning Without Ceremony
There is planning too, but it is not allowed to take over.
Feature files are for work that benefits from sequencing: new functionality, integration changes, redesigns, significant refactors, decisions that span more than one session.
They are not for typo fixes.They are not for tiny bugs.They are not for pretending every change needs a project management ritual.
That matters because agent work gets worse when the process becomes heavier than the task.
Small change? Inspect the code and do it.Big change? Read the plan, update the plan, leave the next person with something useful.
No big deal.
Maintenance Is Part Of The System
The setup also includes maintenance rules, which is where this becomes more than a tidy docs folder.
The docs have size budgets. The guidance has pruning rules. Stale instructions should be deleted. Duplicate rules should go. Tool-specific files should not drift into separate little religions. If a rule does not prevent a real mistake, reduce task time, improve validation, or lower context volume, it probably does not belong.
That sounds strict, but it is the only way documentation stays alive.
Otherwise every incident becomes a new permanent paragraph. Every preference becomes policy. Every old workaround becomes sacred.
And then one day the agent is reading twelve files before changing one component.
That is how documentation turns from help into drag.
The Real Point
The point of this setup is not "we wrote docs."
The point is that the project can be worked on by agents without losing judgment.
An agent lands in the repo and knows the basics.It has a router for deeper context.It has gotchas for the dangerous parts.It has feature plans when the work is genuinely planned.It has validation rules that scale with risk.And it has maintenance rules so the whole thing does not slowly become a museum of old fear.
Under the hood, that means root guidance, context routing, domain architecture notes, gotcha shards, feature plans, validation expectations, pruning rules, source-of-truth boundaries, and just enough process to keep the work sane.
The boring grown-up stuff.
But this is exactly the kind of boring grown-up stuff that makes ambitious work easier to keep moving.
Because the best documentation does not try to explain the whole project every time.
It helps the next person, or the next agent, make the right move faster.