A couple of years ago I worked with a manager who 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 or why it mattered. Having used Spec Kit for a couple of months now, the penny has finally dropped — though I will say 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.
I 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.
The remaining 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.