© Nink AI Engineering GmbH

Can Your Agent Repo Document Itself?

How do you produce the architecture documentation for your agent systems?

That question arose during the Agentic AI Cohort while building one agent system after another producing ~20 subagents using tools and web apps. The real question underneath is more interesting: how do you document a growing fleet of AI agents without the documentation going stale the week after you write it?

The answer is that I do not write the documentation, but I have Claude Code generate it from the repository itself. That works because the repository already contains a machine-readable account of what each agent actually is. Without that, the same approach produces confident prose about a system that does not exist.

As-built, not as-designed

Construction has a useful distinction here: as-designed drawings — what the architect intended — versus as-built drawings, surveyed from the finished building, recording what was actually constructed, including every deviation. Facility managers work from as-built drawings, because the building does not care what the design said.

Most software documentation is as-designed. It records an intention at writing time and drifts from that moment on. But an agent system built with Claude Code has a property that classic software mostly lacks: the agents themselves are markdown files. Each subagent in .claude/agents/ declares its purpose, its prompt, and—critically—its tools: frontmatter, the exact list of tools it is allowed to call. Each command in .claude/commands/ declares how the orchestration flows. That is not documentation about the system; it is the system, in the same files the runtime executes.

So the documentation job changes character. You do not describe your architecture from memory—you send a surveyor into the building. Claude Code reads the agent and command files and writes as-built pages from what it finds there. When an agent changes, you send the surveyor back in; regenerating a page is one prompt, not an afternoon.

The four decisions

The setup is small. What matters is four decisions, each one fencing off a way such documentation usually fails.

1. The agent files are the single source of truth. The generator is instructed to document what the tools: grants and command flows actually say, not what a README claims, not what I remember intending. A guardrail worth showing is one that is enforced in the tool grant; a page that lists the real grant proves it.
2. One index, one page per system, one page per concept. Each system page answers the same questions: what does it do, how does the flow run, which tools may each agent touch, what does the output look like. Cross-cutting ideas—how subagents pass work to each other, where the safety boundaries live—get their own concept pages so nothing is explained twice. I started with one monolithic page and had to split it later, when it hit 139 KB and predated a quarter of my systems. Start modular.
3. Plain HTML, one shared CSS file, no build step. The pages open straight from file:// in any browser, which is everything a demo needs. No static-site generator, no bundler, no dependency that can rot. The styling is iterated once, on the first page; every later page inherits it. If publishing is a need you can deploy it to some web server (or vercel or alike).
4. Diagrams as inline Mermaid source, not images. A <pre class="mermaid"> block plus a local copy of mermaid.min.js renders the flow diagram in the browser—and the diagram source stays editable text in the page. When the agent changes, the surveyor updates the diagram the same way it updates the prose. My first version inlined pre-rendered SVGs at 25–33 KB each; they were opaque blobs nobody could maintain. Editable source won.

The prompt that starts it all is unglamorous: "Read my .claude/agents and .claude/commands, then write an index.html plus one HTML page per agent system—purpose, Mermaid flow diagram, tool grants and guardrails—sharing one style.css, no build step."

Conclusion

The as-built frame explains why this works and where it stops. The generated pages are a survey, and a survey is only as good as what is surveyable: tool grants, flows, and file layouts regenerate cleanly, while the why behind a design decision still has to be written down once by a human—the surveyor can transcribe reasoning it finds, but it cannot recover reasoning that was never recorded. The two complement each other; neither replaces the other.

For readers from the MBSE world this will feel familiar, and it should. It is the same principle we argue for in model-based engineering—data over visualization and documents, one source of truth with views generated from it—applied to the tooling we are now building with AI rather than the systems we model. The agent definitions are the model. The documentation is a view. Regenerate the view; never let it become the master.