For a long time, we were careful with documentation in codebases. Not because it didn't matter, but because it had a tendency to grow without much restraint. We usually kept it intentional, like a README with context and setup instructions. Or a high-level architectural overview with sometimes a few ADRs when a decision was hard to reverse.
Everything else lived elsewhere.
Product context in Notion. Domain knowledge in Confluence. Places where people outside the engineering team could contribute to. That split worked because code stayed focused and clean. Documentation stayed accessible for everyone, and most of the time, people knew where to look.
AI has changed that balance.
When the reader changes, the responsibility shifts
With tools like Claude Code, documentation inside the repository suddenly matters more. Not because engineers have changed how they work (yet), but because the reader of your documentation is no longer only human.
AI reasons best with direct access to context. The code itself, the structure around it, and the decisions that shaped it over time. When that information lives outside the repository, gaps appear and assumptions creep in. Explanations become inconsistent.
Keeping relevant documentation close to the code reduces that friction. The system becomes easier to reason about, both for people and for machines. Hallucinations do not disappear, but they become easier to spot and easier to correct.
The repository stops being just something you build from. It becomes something that carries understanding forward.
Volume is no longer the real concern
A common worry is that AI produces too much documentation. Pages of it. More than most engineers would ever write, and certainly more than most people want to read.
That concern made sense before.
You no longer have to read everything end to end. You can ask the AI to summarise or to extract decisions. To explain a single flow or dependency. To answer a question that would otherwise send you digging through commits, tickets, and half-remembered conversations.
By moving documentation closer to the code, you add something teams often lack over time: continuity. A record of why decisions were made, even when the people who made them are no longer around. That changes how knowledge ages inside a team.
Documentation becomes something you query when you need it, instead of something you promise to clean up later.
Code first, but not code only
This does not mean all documentation suddenly belongs in the repository.
Markdown files can feel awkward to work with, especially for non-technical team members. Product documentation, use cases, and exploratory thinking are often easier to manage outside the codebase, where tools and workflows are more familiar.
At the same time, AI benefits from that context as well. If product documentation explains why a feature exists, it can use that information when reasoning about changes. If a feature passport describes an intended approach, deviations can be recorded when reality inevitably diverges. Those deviations are easy to forget and expensive to rediscover.
The goal is not to enforce a single source of truth. It is to be explicit about what lives where, and to keep the important parts connected.
A setup that can carry the work forward
What we deliberately keep simple is the setup.
Think of a structured docs folder inside the repository, written in plain markdown. There is a clear scope: architecture notes and key decisions. And where it matters, we add links to higher-level product documentation.
The README becomes an entry point, not just for developers, but for anyone trying to understand the system through GitHub. That includes non-technical stakeholders. And it certainly includes AI.
The main discipline is knowing when to stop. When something is clear enough to be useful, and solid enough to carry forward without becoming noise. Left unchecked, AI will happily document everything. Restraint remains part of the job.
Documentation as an act of care
The bigger shift is mental. Documentation is no longer something you maintain only for people. It becomes part of how the system itself is understood, evolved, and handed over. Writing things down pays off faster, and keeping them close to the code makes them more useful over time.
This fits how we already work at madewithlove: we optimise for clarity, we reduce key person risk and help teams carry the work further than they could on their own. Good documentation has always supported that. It just has a new reader now, and this one helps keep the work moving.
