Design Doc

A design doc translates requirements into a technical plan — the bridge between knowing what to build and deciding how to build it.

Understand This First

• Specification – a specification describes what the system should do; a design doc describes how.
• Architecture – the design doc records architectural decisions before they get buried in code.
• Tradeoff – every design doc contains tradeoffs, whether the author names them or not.

Context

This is a strategic pattern. You have a Specification (or at least solid requirements), and now you need to figure out how the system will actually work. Which components exist? How do they talk to each other? What data flows where? What libraries, frameworks, or services will you use? These are design decisions, and they deserve a written record.

Design docs have been standard practice at companies like Google, Meta, and Uber for over a decade. What has changed is the reader. When a human developer reads a design doc, they fill in gaps from experience. When an AI agent reads one, it treats the document as ground truth and builds exactly what it describes. A vague design doc produces vague architecture. A precise one gives the agent a blueprint it can follow without inventing structural decisions on its own.

Problem

How do you make technical design decisions visible, reviewable, and durable before committing to code?

Requirements say what the system must do. Code says how it does it. But between those two artifacts is a gap full of decisions: which database, which API style, which module boundaries, which error-handling strategy, which authentication flow. If nobody writes those decisions down, they get made piecemeal during implementation. Different developers (or different agent sessions) make contradictory choices. The resulting system works, but its architecture is accidental rather than intentional.

Forces

• Design decisions made during coding are hard to review and easy to forget. Writing them down slows you down now but saves time later.
• A design doc can become stale the moment implementation begins, creating a misleading reference. But no reference at all is worse.
• The right level of detail depends on context. Too little and the doc doesn’t constrain anything. Too much and you’re writing the code twice in English.
• Reviewers need enough detail to evaluate the approach, but not so much that the review becomes as expensive as the implementation.

Solution

Write a document that describes the technical approach you’ll take to satisfy the requirements. A design doc sits above code but below a specification: where the spec says what the system must do, the design doc says how you plan to build it.

A typical design doc covers:

• Goal and scope. What problem this design solves and what it explicitly does not address. A clear non-goals section prevents scope creep during implementation.
• Background. Enough context for a reviewer to evaluate the design without reading every related document. A paragraph or two.
• Proposed design. The core of the document. Describe the components, their responsibilities, and how they interact. Name the data flows, the interfaces, and the major abstractions. Include diagrams when they clarify structure that prose alone can’t convey.
• Alternatives considered. What other approaches you evaluated and why you rejected them. This is the most undervalued section. It prevents future developers from relitigating decisions that have already been thought through, and it gives reviewers confidence that the author didn’t just pick the first approach that came to mind.
• Security, privacy, and operational concerns. How the design handles trust boundaries, data sensitivity, failure modes, and deployment. Not every design doc needs a long section here, but every design doc needs to show that the author considered these dimensions.

The format matters less than the habit. Some teams use structured templates with numbered sections. Others use informal prose. Google’s design docs tend toward long-form narrative; Amazon’s six-pagers enforce a specific structure. What they share is the practice of writing the design down and having others review it before building starts.

In spec-driven agentic workflows, the design doc occupies a distinct phase. Tools like Kiro enforce a three-stage pipeline: requirements first, then a design document that translates those requirements into technical architecture, then a task breakdown the agent executes. GitHub’s Spec Kit treats the design phase as the place where human judgment shapes the system’s structure before the agent takes over implementation. The pattern is the same regardless of tooling: separate the what from the how, write the how down, and review it before anyone (or anything) starts coding.

How It Plays Out

A team is adding real-time notifications to their product. The requirements are clear: users should see updates within seconds, notifications should persist if the user is offline, and the system should handle thousands of concurrent connections. Three approaches are plausible: WebSockets through their existing API layer, a managed service like AWS AppSync, or a polling fallback with server-sent events.

Without a design doc, the developer (or agent) picks whichever approach they’re most familiar with. With one, the team evaluates all three on cost, complexity, and latency guarantees before writing a line of code. The “alternatives considered” section means nobody revisits this decision six months later wondering why they didn’t use WebSockets.

A solo developer directs an agent to build a CLI tool. They write a short design doc (just a page) covering the command structure, how configuration is loaded, and which third-party libraries to use. They paste it into the agent’s context alongside the spec. The agent builds the CLI in one pass because every structural question already has an answer. Without the design doc, the agent would have chosen its own library preferences, its own config format, and its own command naming convention. The output might work, but it wouldn’t match what the developer had in mind.

Consequences

A design doc makes architectural intent explicit. Reviewers catch structural problems before they’re embedded in code. The document survives the implementation and becomes a reference for anyone who later needs to understand why the system is built this way, not just how it works.

For agentic workflows, a design doc reduces the number of structural decisions the agent makes on its own. This matters because agents make reasonable-looking choices that may conflict with your constraints, your team’s conventions, or your operational environment. A design doc constrains the solution space to the region you’ve already evaluated.

The cost is time. Writing a good design doc for a medium-sized feature takes a few hours. For a large system, it might take days. Some of that time produces genuine insight because the act of writing forces you to think through problems you’d otherwise hit mid-build. Some of it feels like overhead, especially for small changes where the design is obvious. Not every change needs a design doc. A useful heuristic: if the change involves more than one component, more than one team, or a decision you’d want to explain to someone later, write it down.

Design docs can also create inertia. Once a design is written and approved, people resist changing it even when new information makes a different approach better. Treat the document as a plan, not a contract. Update it when reality diverges from the design, or mark it as superseded and write a new one.

Related Patterns

• Depends on: Specification – specs describe what to build; design docs describe how to build it.
• Depends on: Requirement – a design doc translates requirements into technical decisions.
• Depends on: Tradeoff – the “alternatives considered” section makes tradeoffs explicit.
• Informed by: Architecture – the design doc records the architecture before it exists in code.
• Enables: Acceptance Criteria – a design doc makes it easier to derive criteria for verifying the implementation.
• Enables: Decomposition – the proposed design section naturally decomposes the problem into buildable pieces.
• Complements: Judgment – the design doc captures the output of judgment calls made during design.

Sources

• Google’s engineering culture popularized the long-form design doc as a prerequisite for significant software changes. Their internal template (since adapted publicly by many companies) emphasizes context, proposed design, alternatives considered, and cross-cutting concerns.
• Addy Osmani’s writing on specification and design for AI agents (O’Reilly Radar, 2026) codified the principle that AI raises the cost of ambiguity. Unclear design decisions don’t just slow things down; they actively create risk when agents build from them.
• AWS Kiro formalized the three-phase spec workflow (requirements, design, tasks) as a first-class IDE feature, making the design doc phase explicit in agentic development tooling.
• GitHub’s Spec Kit treats the design document as a distinct artifact in spec-driven development, separating problem definition from technical approach.