Document as Code in the Age of AI - Part 1

Part 1: Why Co-Location Changes Everything

The strategic insight — what's broken, why AI changes the math, and why product leaders should care

A Good Idea Whose Time Has Come

Document as Code has been around for years. The concept is simple: treat your documentation the same way you treat your code—version-controlled, reviewed, and living right alongside the software it describes.

For most teams, though, it's stayed optional. A "nice to have" for disciplined engineering orgs, something that made sense in theory but often fell by the wayside when deadlines loomed. The immediate payoff never quite justified the cultural shift required to make it work.

AI changes that calculus entirely.

When your AI assistants can see the full picture—the why, the what, and the how, all in one place—they stop being clever autocomplete tools and start becoming genuine collaborators. Co-locating briefs, PRDs, designs, and specs with your codebase creates a feedback loop that makes both the documents and the code dramatically better.

AI turns Document as Code from a good idea into a great one. That's the thesis I want to explore.

The Problem: Product Docs and Code Live in Different Worlds

I saw this play out at Chegg while building subject-specific AI agents for the student Q&A platform. The original brief was explicit: for strategic reasons, we needed to use fine-tuned open source models rather than out-of-the-box ChatGPT. Cost control, data ownership, avoiding vendor lock-in—all valid business considerations.

The development team, naturally focused on producing the highest quality answers, went with ChatGPT. At the time, it was clearly superior. They made a defensible technical decision based on the goal they understood: best answers for students.

The disconnect wasn't discovered until much later. By then, we had built the wrong thing—not wrong from a quality standpoint, but wrong from a business strategy standpoint. If the brief had lived in the repo alongside the code, this misalignment would have surfaced in code review. Someone would have asked: "Why are we using the ChatGPT API when the brief specifies open source models?" The team could have aligned on the right solution—or revised the strategy—before significant work was invested.

This pattern is everywhere. PRDs live in Confluence or Google Docs. Design mocks live in Figma. Code lives in GitHub. And from the moment each artifact is created, they start drifting apart.

The PRD describes v1 of the feature. The mocks show v2, after the designer iterated based on feedback. The code is on v3, because engineering discovered technical constraints that required pivots. Nobody updates anything because everyone was too busy shipping.

This isn't a failure of discipline—it's structural. When documents live in different tools with different workflows, synchronization becomes a constant tax that teams simply can't afford to pay.

The consequences compound. Anyone—human or AI—who needs the full picture is assembling it from five different tools, hoping they found the latest version of everything, making educated guesses about which conflicts matter.

Your code generators are flying half-blind. They can write impressive code, but without access to the brief, the PRD, or the design mocks, they don't understand why they're writing it. They don't know what business outcome it's supposed to serve. They can't catch the subtle misalignment between what product intended and what's actually being built.

For product and business leaders, this isn't a developer workflow problem—it's a decision-making and quality problem that compounds with every sprint.

The AI Multiplier: Why Good Becomes Great

Document as Code already had value before AI. When docs, designs, and code share the same versioning, branching, and review process, something powerful happens. When a feature branches, so does its PRD and its design specs. Review cycles improve because reviewers can see the intent and the implementation together. Changes are traceable. History is preserved.

Valuable, yes. But hard to enforce and easy to skip, because the benefits were mostly about organizational hygiene—important, but not urgent.

AI changes the urgency calculation.

AI-generated docs get better because they can see the code and the designs. When your AI assistant has access to the actual codebase alongside the brief, it can write PRDs that reflect what's actually built—not what someone remembers was built three sprints ago. Draft specs reference real APIs, actual data models, and current system constraints instead of aspirational architectures. PRDs and briefs can reference actual UI patterns, and AI can flag inconsistencies between what the design shows and what the spec describes.

AI-generated code gets better because it can see the docs and designs. When your coding agent has the PRD, acceptance criteria, UX mocks, and product context right there in the repo, it writes code that's aligned with intent—visually and functionally. Frontend code generation in particular improves dramatically when the AI can reference the actual design, not just a text description of it. QA and test generation improve because the AI knows what the feature is supposed to do, not just what the function signature looks like.

To see what this looks like in practice, consider a typical feature repo structure:

/features/student-qa-agent/

├── README.md # Feature overview

├── docs/

│ ├── brief.md # Original business brief

│ ├── prd.md # Product requirements

│ ├── technical-spec.md # Architecture decisions

│ └── designs/

│ ├── user-flow.png

│ └── mockups.figma

├── src/

│ ├── agent/

│ │ ├── model_config.py # Model selection & config

│ │ └── response_handler.py

│ └── api/

│ └── qa_endpoint.py

└── tests/

└── test_agent_responses.py

When an AI coding assistant reads model_config.py and sees the brief alongside it, it can catch misalignments immediately. If the code says model = "gpt-4" but brief.md specifies "fine-tuned open source models for strategic reasons," that's a flag-able conflict.

Here's what that looks like in practice:

Without context (AI only sees the code):

# model_config.py
class QAAgentConfig:
    def __init__(self):
        self.model = "gpt-4"  # Best quality for student answers
        self.temperature = 0.7
        self.max_tokens = 500

The AI sees the comment and thinks: "Makes sense, GPT-4 gives the best answers."

With context (AI sees the brief + code):

# model_config.py
# Context from ../docs/brief.md:
# "Use fine-tuned open source models (Llama 2 or Mistral) for strategic
#  reasons: cost control, data ownership, vendor independence"

class QAAgentConfig:
    def __init__(self):
        self.model = "gpt-4"  # ⚠️ Conflicts with brief requirement
        self.temperature = 0.7
        self.max_tokens = 500

Now the AI—or a human reviewer—can immediately spot the disconnect and ask: "Should we align with the strategic direction, or do we need to revisit the strategy given quality constraints?"

Similarly, when generating test cases, the AI can pull acceptance criteria directly from prd.md rather than inferring them from function signatures. Tests become specification-driven instead of implementation-driven.

The virtuous cycle emerges. Better docs lead to better code. The code updates, and the docs update to reflect it. The next iteration starts from a stronger foundation. Each sprint builds on the last instead of starting from a partially outdated baseline.

Context proximity is everything for large language models. The more relevant context you can fit into that window, the better the output. And there's no context more relevant to a piece of code than the product brief that explains why it exists and the design that shows what it should look like. AI doesn't just benefit from co-location—it thrives on it.

The Business Case: Why Product Leaders Should Care

Yes, this makes developers more productive. But the business case extends well beyond engineering efficiency.

Reduced rework. When AI generates code that already reflects product requirements and design specs, you catch misalignment earlier. The bug that would have been discovered in QA—or worse, by a customer—gets caught in code review because the reviewer can see the PRD and the mock right alongside the implementation. In the Chegg example, a simple code review would have surfaced the ChatGPT vs. open source model disconnect before any integration work began.

Fewer "lost in translation" gaps. The space between product intent and engineering execution is where quality goes to die. Every handoff is an opportunity for miscommunication. When the brief, the design, and the code live together and evolve together, those translation layers collapse. What product meant sits right next to what engineering built.

Faster onboarding. New team members—and new AI agents—can understand a feature's intent, design, and implementation in one place. The ramp-up time to productivity drops significantly when context isn't scattered across a half-dozen tools that the new person doesn't even know to check.

Compounding returns. Every sprint starts with better context than the last. Your documentation gets more accurate over time instead of less. Your AI assistants get more effective because they're working with better inputs. The gap between intent and execution narrows instead of widening. This matters more than any individual productivity gain.

What's Next

The feedback loop between docs, designs, and code is the unlock. AI makes co-location not just tidy, but transformative.

Knowing why this matters is only half the battle. The real question is how—how to actually make this happen without disrupting your team, without requiring everyone to become Git experts overnight, and without adding overhead that negates the benefits.

Part 2 tackles exactly that: the practical guide to making Document as Code real in your organization, with a crawl-walk-run framework that meets teams where they are.

---

This is Part 1 of a three-part series on Document as Code in the Age of AI. Part 2: Making It Real provides the practical implementation guide.