Why AI docs are different
Documentation for humans can be narrative and exhaustive. Docs for an AI agent need to be high-signal and compact, because the agent reads them into a finite context window where every token competes for attention.
The goal isn't completeness — it's giving the agent exactly the facts it needs to act correctly.
What to include
Cover the architecture at a glance, the main entry points, the conventions you enforce, the hard constraints, and the landmines (intentional weirdness not to 'fix'). That's what keeps an agent aligned.
Leave out long tutorials and anything the agent can read straight from the code.
Point, don't duplicate
Reference where things live ('auth logic is in lib/auth, all HTTP goes through lib/http') rather than pasting implementations. The agent can open the files; it just needs the map.
Duplicated code in docs goes stale fast and burns context.
Keep it compact
A bloated doc is self-defeating: it pushes the important facts out of the window and dilutes attention. Ruthlessly trim to what changes the agent's behavior.
If a line wouldn't affect how the agent acts, it probably doesn't belong.
Put it where agents read it
Store the doc in the project memory file (or referenced from it) so the agent loads it every session, and review it like code so it stays current.
Documentation the agent never sees might as well not exist.