The AI Context and Documentation Problem

At Normal, we are constantly thinking about how to accelerate engineering productivity with AI. AI coding assistants have come a long way, particularly at generating self-contained functions and simple zero-to-one features. But as feature complexity scales, code quality degrades.

Anyone who’s used coding assistants like Claude Code has likely experienced a version of the following frustrating exchange:

Efficiency gains vanish as the engineer spends more time explaining system constraints than writing code.

But the problem isn't the AI tools themselves. It's that the standard development workflow wasn't designed to give AI agents the context they need. Modern software systems are dense with implicit contracts - architectural boundaries, data model invariants, cross-service expectations - that are difficult for AI to infer. Expecting AI agents to contribute to a complex codebase without prerequisite context and then being frustrated with the output is like assigning a contractor a feature request without a PRD, then being surprised when the implementation violates unwritten assumptions.

As AI coding assistants become ubiquitous, context becomes currency. So why not just supply them with more documentation?

At fast-moving startups, documentation debt can accumulate faster than anyone can pay it down. Product specs lag behind reality and architecture docs get stale the moment a service is refactored. And even when documentation does exist, the type of documentation most helpful for humans—narrative explanations, design rationale, architectural diagrams - is not always structured or explicit enough for an AI agent to reliably parse and apply. Simply producing more documentation doesn’t solve the problem. AI needs something different.

Rethinking the Development Process: Spec-Driven Development

Our workflow looked like most modern teams: context lived across multiple repos, scattered docs, Slack threads, and institutional memory. Without a single, authoritative source of truth, AI assistants could help with isolated tasks, but anything touching system behavior required long explanations. We realized the bottleneck wasn’t the AI agents — it was the development process. Instead of treating specifications as static documentation, we made them a first-class, continuously generated part of the engineering workflow itself.

To close the context gap, we built a spec-driven development (“SDD”) system that makes specifications a living, automatically maintained part of our codebase. Before any new code is written, our SDD system analyzes the existing codebase and automatically generates AI-readable specifications of system architecture, data flow, and constraints for both legacy and new features. These specs become the control surface for all AI contributions.

In effect, SDD enforces the decomposition of large, ambiguous product goals into precise, agent-compatible units while building the source of truth that both AI agents and humans can rely on. It answers questions such as: What is the system supposed to do? What are the non-negotiable contracts? Which behaviors must never regress?

By surfacing and resolving ambiguity early, SDD fundamentally changes where effort is spent in the development process. Most software projects follow a two-stage arc. The first stage, the 0 → 80%, is the foundational work required to get something minimally functional. This is where AI excels, provided the requirements are explicit. The second stage, the final 20%, involves the hard human work: navigating user experience nuances, making complex architectural tradeoffs, and applying judgment rooted in context. SDD is designed to maximize leverage in the first stage so that engineers can spend their time where human insight compounds: in the last mile of robustness and refinement.

What SDD Unlocks for Normal

At Normal, investing in the spec layer has paid dividends.

SDD lowers the barriers to contribution, for both PMs and engineers. As a PM, I have been able to build and ship features by leveraging Claude Code not as naive code autocomplete, but as a collaborator that understands why a feature exists and the technical constraints it must respect. New engineers also onboard dramatically faster. Instead of spelunking through repos to infer architecture and crowdsourcing legacy knowledge, engineers can rely on SDD for a centralized, always-updated map of the system.

The most valuable contributors now aren’t just those who can implement solutions quickly. They’re the ones who can translate ambiguous product intent into atomic, unambiguous requirements, simultaneously considering existing system behavior, intended behavior, edge cases, and the technical decisions that define the shape of a solution. In other words, they become high-fidelity context providers. SDD gives them the tooling to express that context and shape the constraints in a way AI can reliably operationalize.

SDD also enables more predictable and higher quality AI contributions. When AI tools are prompted with vague, ambiguous instructions, the quality of the output is a lottery: it occasionally gets things right, but just as often it hallucinates while filling in gaps with its own assumptions. The moment those assumptions differ from the system’s actual constraints, the implementation veers off course. But when AI is supplied with specific, well-structured context, the probability of high-quality output dramatically increases. These specs become the “API” between human intent and AI execution. For example, with the login flow documented, Claude Code stopped proposing breaking changes to our OIDC setup, eliminating repetitive context-setting. Code reviews are also smoother because AI suggestions align with system constraints from the start.

We’ve also seen improvements in test coverage and QA efficiency. AI excels at generating tests, but only when requirements are explicit. With SDD, we automatically generate end-to-end tests covering all functional requirements, validate specs against existing test suites, and detect regression risks before they leak into production. These AI-generated tests also now cover edge cases that were previously implicit only in engineers’ heads. As the spec layer becomes more complete, the test suite becomes more comprehensive and reliable, turning what used to be hours of manual QA into a largely automated safety net.

A New Development Paradigm

Spec-driven development is part of a broader shift in how software is built in the era of AI collaborators. GitHub’s open-source Spec Kit has started to explore what “specs as code” could look like inside modern development workflows. It reinforces what we’ve seen firsthand: the future of AI-assisted engineering depends on structured, machine-readable context as a first-class artifact.

By integrating SDD into our engineering workflow, Normal is demonstrating how AI can reliably build, test, and evolve complex enterprise systems in environments with real-world constraints and high-stakes correctness requirements. The living, automatically generated knowledge base aligns PMs with engineers, engineers with product intent, and AI agents with both. With a structured, shared source of truth, AI becomes a predictable collaborator instead of an unpredictable autocomplete engine. Fewer debates with Claude. More shipping.

Read Part 2 for a deep dive into why existing SDD tooling fell short for our use case and how we built a custom SDD system tailored to enterprise constraints.

‍