I’m currently writing a comprehensive architecture documentation. And it keeps striking me how much knowledge has so far existed only in my head.
That is exactly the problem when working with AI agents.
Agents work like a flashlight: whatever falls inside the beam gets handled thoroughly. Whatever stays in the dark simply doesn’t exist for them. And most of what lies in the dark lives in our heads. Why was this built this way? What must never be touched? Which constraints apply? We know these things. The agent doesn’t.
That’s why investing energy in specification and documentation pays off more than ever. Structured templates like arc42 help enormously, especially these sections:
- Constraints: what is technically and organizationally fixed
- Crosscutting concepts: how we handle errors, transactions and logging
- Architecture decisions: not just what we decided, but why
- Glossary: so that domain terms are understood correctly
One important caveat: the documentation belongs in the repository, and it has to stay up to date. Outdated documentation is worse than none for an agent, because the agent believes it.
Documentation used to be mainly for the next colleague. Today, it’s the light the agent works by.
