Every software company has a dead wiki. It's full of pages written with real enthusiasm eighteen months ago, half of them describe a system that no longer exists, and everyone has quietly learned not to trust it. You look something up, find an answer that sounds plausible, apply it, and discover the architecture changed three releases back.
The problem isn't that people are lazy writers. It's structural: when documentation lives away from the code, it ages without anyone noticing. Nothing forces it to change when the system changes. Nothing puts it in front of the one person who knows it went stale.
Our answer is easy to state and demanding to sustain: documentation lives as code, in the same repository. Specs, design decisions, and bug history, versioned alongside what they describe.
Before the how, it's worth naming the cost, because it doesn't reduce to "we have no docs". It's more expensive than that.
The knowledge that matters in a software system isn't what the code does, since you can read that. It's why it's like this: which constraint forced it, which alternative was tried and failed, which rare case demanded that odd condition on line 240.
That knowledge normally lives in three bad places: two or three people's heads, a chat channel nobody is going to search, and the comments on a pull request closed a year ago. The symptoms are ones any CTO recognizes instantly:
Certain people can't take vacation without the team slowing down.
A new engineer takes months to become autonomous, not because the code is hard but because the context is invisible.
Someone "cleans up" a strange condition that was actually the fix from an incident, and the incident returns.
That's bus factor. It rarely shows up as a crisis. It shows up as a steady drag that gets blamed on other things.
One placement rule: if it's knowledge about the system, it goes in the system's repository, in plain text, reviewed like code.
Three bodies of documentation:
1. Specs. Written before the code, in numbered phases: spec, technical design, implementation plan, test plan, deploy plan. They're not a process artifact you file away at the end. They're the record of what we were trying to achieve, and they remain the best answer to "is this a bug or is it the intended behavior?".
2. Design decisions. Including, above all, the alternatives we rejected and why. It's the section nobody wants to write and the only one that answers the most repeated question in a system's life: "why didn't they just do the obvious thing?".
3. Bug history. A living log of everything triaged: reproduction, root cause with exact file and line, fix strategy, alternatives, test and rollback plans. In practice, it's the map of where the system is fragile.
One policy cuts across all three: secrets appear by reference only, never by value. A document can say which credential is needed and where it lives; never what it is. If documentation is going to sit in the repo, it has to be safe to read for anyone who has the repo.
When we started building Hura, our technical assessment platform, with AI agents inside the flow, documentation stopped being a future benefit and became the day's raw material.
An agent has no memory of your project. Every session starts knowing whatever you hand it, and the quality of what comes back depends almost entirely on that. Teams complaining that the agent "makes things up" or "rewrites what was already decided" usually share one root cause: the context it needed lived in someone's head instead of in the repo.
We already wrote specs, decisions, and bug docs for human reasons. They turned out to be exactly the material an agent needs. Three things changed in how we write them:
Constraints get written as rules, not culture. "Everything user-facing ships in Spanish and English" was a team habit. Now it's written in the repo, because a habit doesn't travel into an agent's context and a rule does. A PR delivering a string in one language gets rejected, whoever wrote it.
Rejected alternatives are worth double. They used to prevent a repeated argument among humans. Now they also stop the agent from confidently proposing, again, the option we tried and discarded eight months ago.
The spec became the deliverable, not the paperwork. When much of the code is written by an agent from the document, the quality of the document and the quality of the product stop being separate things.
The other half needs saying. None of this replaces review: we mark agent co-authorship in the git history and a person reviews the diff and answers for it. "The AI wrote it" is never an accepted answer in a code review. Documentation improves what the agent proposes; it doesn't transfer responsibility.
The fair objection is that this sounds heavy, and there is a version of docs-as-code that genuinely is. The difference comes down to three choices:
It lives where you already look. Nobody has to remember to open another tool. Documentation shows up in the diff, gets reviewed in the PR, and gets updated in the same commit that changes behavior. Keeping it current stops depending on goodwill and starts depending on the normal flow of work.
It's an input, not a summary. The spec doesn't describe what was already built; it's what you write first to decide what to build. Documenting stops being a tax at the end and becomes the activity that makes the work possible.
It has a specific reader. We write for the engineer who'll touch this in six months, often yourself, not for an imaginary auditor. That keeps the volume honest: if a section doesn't help that person, it's cut.
Seen from outside engineering, it comes down to three things: resilience, because one person leaving doesn't take a system with them; shorter onboarding, because context is read rather than transmitted in meetings; and auditability, because every decision and fix leaves a written trail, dated and attributed, for whenever you have to show how something was built. With agents in the flow that last one matters more, not less: being able to say what a machine wrote, what a person reviewed, and against which criteria.
And the flip side, which also needs saying: documentation in the repo rots too, if nobody reviews it. The repository isn't magic. It only puts the docs in the path of review, which is where they have a chance of surviving. If your PR culture doesn't treat documentation changes as seriously as code changes, what you'll end up with is a better-located dead wiki.
Move specs, design decisions, and bug history into the same repository as the code, in plain text, under the same review cycle. If you also have AI agents in the flow, there's a more immediate reason: that repository is the context they work from. Write your team's constraints as explicit rules instead of leaving them as culture, always document the rejected alternatives, and keep secrets by reference, never by value.
About Aztia. We're a software development firm. We build Hura, our technical assessment platform (huraapp.com), holding ourselves to the same process we describe in this series. More at aztia.co.
Thirty minutes, no pitch. Tell us what you're building.
Talk to us →