I think most product teams are documenting in the wrong place, and we have just been slow to admit it.

Something has shifted in how I work. I find myself spending far less time writing product specs and decisions in Confluence, Google Docs, or Notion, and much more time writing them directly in the GitHub repo. It doesn’t feel like a tradeoff. It feels like a correction.

Traditionally, product thinking lived in documents. Specs, PRDs, decision logs, and system design write-ups were neatly organized in Confluence or Docs. These tools were optimized for human consumption: easy to write, easy to share, easy to comment on. But they were always slightly detached from the system they described. Over time, they drifted. The code evolved, but the docs didn’t, and everyone learned to live with that gap.

But that model starts to break in an agent-first world.

As I have started building more with AI agents, something has become obvious: the system that builds also needs to read. Agents don’t navigate Confluence well, and they struggle with fragmented context spread across tools. What they work best with is a structured, versioned context that lives close to the code. In other words, they work best inside the repo.

There’s another shift happening in parallel: documentation itself is increasingly being generated by agents. The first draft of a spec, a system overview, or even decision summaries often comes from an agent. And if agents are both producing and consuming this context, it makes even less sense to store it in tools they can’t reliably operate in. Git becomes the natural home for code and machine-readable context.

So naturally, my workflow is shifting. Specs, decisions, and even early product thinking are moving closer to the codebase, not as static documents, but as living artifacts that evolve with the system.

A small example from my own workflow- instead of writing a PRD in a doc, I now create a structured spec directly in the repo alongside the service it impacts. It includes context, assumptions, API contracts, and even prompts for agent workflows. As the system evolves, the spec evolves in the same pull requests. When someone new joins, they don’t read a static doc; they explore the repo, and increasingly, use AI to generate a personalized walkthrough of the system based on the latest state.

This raises a bigger question. In a world where the source of truth is the codebase, does it even make sense to maintain parallel documentation in Confluence? Or are we just maintaining a second, eventually inconsistent version of reality?

If the code is the most up-to-date representation of the system, why not keep documentation alongside it, generate documentation directly from it, and allow both humans and agents to query the system itself for answers?

And think about the operational side of this: updating documentation is now often just one good prompt away. Compare that to the traditional process of tracking down context, talking to multiple people, reconciling different versions of truth, and manually updating a document that will likely drift again. The friction difference is massive. In traditional confluence documentation, I always hear, “The documentation is not up to date. We made the change but forgot to update the documentation.”

The idea of onboarding someone with a set of static, potentially stale documents is starting to feel outdated.

Instead, imagine this: a new team member joins, connects to the repo, and gets a dynamically generated, personalized understanding of the system “how it works, why decisions were made, what trade-offs exist” all based on the current codebase and its history. Not a snapshot from six months ago, but a reflection of reality tailored to them.

Are teams already building this kind of instant, personalized documentation layer on top of their repos? It feels like the obvious next step.

This doesn’t mean tools like Confluence or Notion disappear. They still have a role to play in broader communication, narrative building, and cross-functional alignment. But calling them the source of truth increasingly feels incorrect.

The repo is becoming the source of truth.

This isn’t an overnight shift. It’s a slow change in where gravity sits, “from docs as a separate artifact to docs as part of the system.”

And if agents are becoming part of how we build, then the repo isn’t just where code lives anymore, it’s where understanding lives.

Everything else is a lagging copy. We are not just moving documentation. We are collapsing the gap between thinking and building. And once you see that, it’s hard to go back.

Disclaimer: https://vinaysachdeva.com/disclaimer/. The opinions expressed in the blog post are my own and do not reflect the view(s) of my employer.