Document as Code in the Age of AI - Part 2

Part 2: Making It Real

The practical guide — what it looks like, how to get started, and what's actually hard about it

Another Misalignment Story

In Part 1, I told the Chegg story — how a disconnect between the product brief and the codebase led to building the wrong thing. I wish that were an isolated incident.

More recently, I was advising a team building an automated AI quality evaluation system. The brief was clear: the system needed to serve two use cases. First, offline evaluation during development — letting engineers test and score model outputs as they iterated. Second, a daily automated run that scored the previous day's live chats for quality monitoring.

Two use cases. One brief. Shouldn't have been complicated.

The developers built the first use case and delivered it. The daily scoring workflow? Nobody on the engineering side had internalized that requirement. It wasn't that the brief was ambiguous — it spelled both use cases out plainly. But the brief lived in one place and the code lived in another, and in between, half the requirements evaporated.

When the gap was discovered, the team had to go back and retrofit the second use case into a system that hadn't been designed with it in mind. It took longer than building it right the first time would have. Worse, the disruption pushed back deadlines on other features the team had committed to.

If that brief had been in the repo, co-located with the code, the AI toolchain catches this at multiple points. When the AI generates JIRA tickets from the brief, it creates stories for both use cases — not just the one the developers happened to focus on. When the AI coding assistant generates the evaluation system, it references the brief and scaffolds for daily scoring from the start, because it can see the requirement right there in the context window. And even if both of those somehow miss, the AI QA process compares what was built against what was specified and flags the gap: the brief describes a daily scoring workflow, but nothing in the codebase implements it.

Three chances to catch a misalignment that humans missed entirely. That's what co-location enables when AI is part of the workflow, and it's what this post is about.

What the Destination Looks Like

A product manager writes a brief for a new feature. Instead of a Google Doc that will be stale in three weeks, it's a markdown file in the feature branch — reviewed alongside the pull request, versioned with the code, available to anyone working on that feature.

Designers export their mocks and UX specs into the same branch. Not buried in Figma where you need the right permissions and the right link, but sitting next to the brief and the code.

PRDs evolve with the implementation. When engineering discovers constraints that require product changes, the PRD updates in the same commit. Version control keeps the history. Pull request reviews catch the drift.

AI assistants can reference the "what" (the brief), the "look" (the designs), and the "how" (the code) in a single context window. They're not guessing about intent. They have the full picture.

None of this requires product people to become engineers. It's about putting related things in the same place and letting existing infrastructure — version control, branching, code review — work for everyone's artifacts, not just the code.

Getting Started: Crawl, Walk, Run

You don't need to move everything at once. You definitely shouldn't. The teams that succeed start small and expand once they can point to real results.

Crawl: One Feature, Docs in the Repo

Pick one high-priority feature. Get its PRD, acceptance criteria, and exported design mocks into the repository alongside the feature code.

Someone will push back. Probably several someones. The most common version is some flavor of "we already have Confluence" — and they're right, for documentation that doesn't move. Company policies, onboarding guides, architectural decision records — Confluence is fine for all of that. But specs tied to active feature development need to live where the code lives, because when the brief is in Confluence and the code is in GitHub, they drift. That's not a discipline problem. It's a structural one.

You'll also hear concerns about forcing product people to learn Git. They don't have to. Modern AI assistants can take a Google Doc, convert it to well-formatted markdown, and commit it to a branch without anyone touching a command line. The workflow is: write wherever you're comfortable, then let AI handle the mechanics. Yes, it adds a small amount of friction. But think about the quality evaluation team — the time they spent retrofitting a missed use case dwarfed whatever time co-locating docs would have cost.

The goal at this stage is just presence. Docs in the repo, in the same branch as the feature. Let the team experience what it's like to have everything in one place.

Walk: Make It Part of How Work Happens

Once the docs are there, the next step is making them part of the actual workflow rather than a parallel artifact nobody looks at.

Product teams start updating briefs as the feature evolves — not as a separate task, but as part of the development cycle. When scope changes, the PRD changes in the same commit. Designers export updated mocks at each milestone instead of pointing people to "the latest Figma."

The real shift happens in code review. Instead of reviewing code in isolation, the team reviews code alongside the brief and the designs. Reviewers can ask: does this implementation match what the PRD says we're building? Does it look like what the design shows? AI assistants flag inconsistencies automatically.

This is where you move from "docs happen to be in the repo" to "docs are part of how we build."

Run: The Loop Closes

At this stage, AI starts maintaining the docs alongside the code. When a frontend implementation drifts from the design mocks, the AI flags it. When the code adds capabilities that aren't in the PRD, the AI drafts an update. Product teams use AI to generate first drafts of new specs informed by the existing codebase and current designs — starting from what's actually built rather than from memory.

Getting here takes months, not weeks. And not every team needs to get all the way here — even crawl-stage co-location is a meaningful improvement over the status quo.

What's Actually Hard About This

The tooling is straightforward. What's hard is everything else.

People have been working in their own tools, with their own workflows, for years. Asking a product manager to put their PRD in a repo instead of Confluence isn't really about Confluence versus GitHub — it's about changing habits. And habits don't change because someone sends a Slack message about a new process. It takes repetition, patience, and visible wins before the new way starts to feel natural. You don't need new software or a migration project. Git, your code review system, your AI assistants — they're sufficient. What you need is for non-engineering teams to see the repository as a shared workspace rather than a mysterious place where engineers do engineer things. That reframing takes time.

The thing that catches teams off guard is the leadership piece. A VP of Product says "great idea, let's do it" in a meeting, and the team assumes they have support. But support isn't a one-time declaration. It's showing up three months later when adoption is uneven and some teams are pushing back and asking "do we still have to do this?" If leadership doesn't reinforce the change consistently, it quietly dies. I've seen it happen more than once — the initial enthusiasm fades, the old workflows creep back, and six months later you're right where you started.

AI does make the learning curve gentler than it would have been even two years ago. AI can translate between formats, explain Git concepts in plain language, and handle the mechanical parts while humans focus on content. But AI doesn't solve the organizational commitment problem. That part is on you.

What's Next

The path is incremental — crawl, walk, run. Start with one feature. Prove the value. Expand.

The real investment isn't in tooling. It's in showing up consistently for the cultural change, and having leadership that does the same.

In Part 3, we'll see what this looks like when a team actually implements it end to end — what worked, what was harder than expected, and what the results looked like after living with this approach across multiple development cycles.

---

This is Part 2 of a three-part series on Document as Code in the Age of AI. Part 1: Why Co-Location Changes Everything covers the strategic case. Part 3: Case Study — Closed Loop shows how one team put these principles into practice.