A couple of years ago, a manager proclaimed that documentation should be stored as code. He was very academic and loved announcing the latest trend. Unfortunately he was never able to explain what it actually meant, how to implement it or why it mattered. Having used Spec Kit now, the penny has finally dropped — though it is worth saying upfront that it is not something easy to retro-fit onto an existing project.
Every project has a documentation graveyard. A Confluence space meticulously maintained during the discovery phase and then quietly abandoned once development started. A shared drive full of requirements documents from two major versions ago. A Notion page that was the source of truth until it wasn't. The code moves on; the documents do not. When documentation lives outside the repository, drift is not a risk — it is an issue. The only question is how long before the gap becomes embarrassing.
We have worked on several projects where all requirements, specs, roadmaps, overviews and coding standards live inside the Git repository, right next to the code. If the repo moves, the docs go with it. If a feature changes, the spec changes in the same commit. You can check out any point in history and see what the intention was at the time the code was written. With Spec Kit this goes a step further — the code is generated from the same documentation, which means alignment between spec and implementation is structurally enforced rather than relying on discipline and good intentions.
There is also a dimension here that did not exist a couple of years ago. AI agents read the repository. Your CLAUDE.md, your spec.md, your architecture notes — these are not just reference material for human developers any more. They are active instructions that shape how agents approach the codebase on every run. When those documents are accurate and up-to-date, the agents work better. When they are stale or missing, the agents fill the gaps with their own assumptions. That is rarely what you want.
One challenge is that developers live in Git and most of the rest of the organisation does not. Product managers, stakeholders, and leadership are more likely to open Confluence than clone a repository. The next step is syncing documentation between Git and a tool like Confluence — giving the whole organisation access while keeping the master copy with the code. Git is the source of truth; Confluence becomes a read-only window into it. Getting that working reliably is still a work in progress, but the direction is right.
Storing documentation with code comes with a number of challenges. The manager mentioned at the top wanted to retro-fit the approach into existing repos and this is where it falls apart. Documentation as code affects repo design and architecture and isn't well suited to single service micro repos or sprawling mono repos. Documentation has to be able to describe how an application fits together and what its boundaries are. It also shows why things are the way they are and so should grow with the application. Green field, application bounded repos are the sweet spot. This just so happens to be the easiest size of repo to work with and conceptualise, in our view at least.