Your Design Doc Quality Sets Claude Code's Speed Limit: Spec-First AI Development

When I first heard "16 person-days of development finished in 2 hours," I assumed it was a story about how impressive Claude Code is. But the person who did it kept emphasizing something else entirely: "It wasn't that the AI was fast. It was that the design doc left nothing for the AI to decide."

That framing stuck with me. When you're building apps with AI assistance and things feel slower than they should, the bottleneck is almost always the same thing: the design document — or the lack of one.

This guide digs into how to write specs that let Claude Code operate at full speed, with a practical three-file system you can use immediately.

Why the Design Doc Sets the Speed Ceiling

AI coding agents like Claude Code are excellent at implementation and poor at judgment.

Judgment means: "Should I use this design or that one?" "How much error handling do we need here?" "How does this spec change fit with the existing architecture?" Answering those questions is the human's job. When Claude Code encounters ambiguity, it stops and asks.

Here's what happens when you hand Claude Code a vague spec:

AI: What format should the API error response use?
You: { error: string }
AI: Should network errors use the same format?
You: Yes
AI: Should auth errors include the status code?
You: Yes, 401
AI: What about 404 errors?
(continues)

That back-and-forth is what kills your speed. The case of 16 person-days becoming 2 hours involved a design doc of 3,500 lines across 20 sections — detailed enough that the AI almost never needed to make a judgment call. It could just implement.

Three Conditions for a Spec That Leaves Nothing to the AI

Condition 1: Every decision is recorded, including the reasoning

The most important thing to capture in a design doc is why you made each decision — not just what you decided.

Good:

## Authentication
 
Using JWT (reason: no session management needed in serverless environment)
Token expiry: 24 hours (reason: matches our mobile app usage patterns; 
  refresh tokens add implementation cost without proportional benefit)

Not good:

## Authentication
 
Implement JWT authentication

With the first version, the AI can make informed choices when it encounters edge cases around token expiry or exception handling. With the second, it asks you every time.

Condition 2: Out-of-scope items are explicitly listed

"What we are NOT building" is the most underrated section in any design doc.

## Out of Scope (not in this phase)
 
- Internationalization (post-MVP consideration)
- Social login (low priority)
- Email notifications (replaced by push notifications)
- Admin panel (CSV export is sufficient for now)

When "don't implement X" isn't stated, the AI may generate extra code for X "just in case" or stop to ask whether it should. Explicit exclusions eliminate that entirely.

Condition 3: File structure, components, and naming conventions are predefined

Defining the project's structure before implementation begins keeps the AI's output consistent across sessions.

## Directory Structure
 
src/
  components/    # React components (PascalCase)
  hooks/         # Custom hooks (use* prefix required)
  api/           # API call functions (camelCase)
  types/         # TypeScript types (PascalCase, .types.ts extension)
  utils/         # Utility functions (camelCase)
 
## Naming Conventions
 
- Components: UserCard.tsx (feature + component type)
- Hooks: useUserData.ts (use + feature name)
- API functions: fetchUserById.ts (verb + target + condition)

The Three-File System: DESIGN.md, TASK.md, DECISION.md

Working with Claude Code regularly, I've found that splitting design information across three separate files — each with a different purpose — works significantly better than one large document.

DESIGN.md: The System Design Document

The primary document covering what you're building and how. A solid baseline structure:

# Project Name
 
## Scope of this article
(1-2 paragraphs on the product's purpose and the problem it solves)
 
## User Stories
- User A can do X
- User B can do Y
 
## Tech Stack
(Frameworks and libraries with reasons for choosing them)
 
## Data Model
(Core entities and their relationships)
 
## API Design
(Endpoint list with request/response formats)
 
## State Management
(What state lives where)
 
## Error Handling
(Error classification and response strategy)
 
## Out of Scope
(What is explicitly not being built this phase)

TASK.md: The Implementation Breakdown

Where DESIGN.md answers "what to build," TASK.md answers "in what order and how to verify it's done."

The critical detail is a completion condition for each task:

## Tasks
 
### Phase 1: Foundation
- [ ] Project setup
  - Done when: `npm run dev` runs, ESLint/Prettier pass
- [ ] Auth API
  - Done when: /api/auth/login returns { token: string }, tests pass
  - Depends on: nothing
 
### Phase 2: Core Features
- [ ] User list page
  - Done when: /users shows DB users, error toast appears on failure
  - Depends on: Auth API

When completion conditions are explicit, the AI can judge for itself whether an implementation is finished — no check-in required.

DECISION.md: The Design Decision Log

A record of the judgment calls made during development. This is especially important in AI-assisted work, where the reasoning behind past decisions gets lost between sessions.

# Design Decisions
 
## 2026-04-15: Chose Zustand for state management
 
**Context**: Global state became necessary
**Options**: Context API / Redux / Zustand
**Decision**: Zustand
**Reasoning**:
- Redux is over-engineered for this project's scale
- Context API has performance concerns at this component depth
- Zustand has minimal boilerplate and low learning curve
**Future**: If the project grows significantly, revisit Redux

How to Hand Context to Claude Code

With the design docs ready, the way you open each Claude Code session matters.

Please read @DESIGN.md and @TASK.md.
We're implementing "Phase 1: Auth API" now.
Review the completion conditions, then begin implementation.
If you have any questions, list them all upfront before starting — 
don't pause mid-implementation to ask.

The instruction to ask all questions upfront is worth emphasizing. It changes the interaction from repeated interruptions into one focused clarification round, followed by uninterrupted implementation.

When Writing the Design Doc Feels Too Slow

"Doesn't spending hours on a design doc defeat the purpose?" Fair question. The first design doc does take time — sometimes several hours.

The fix: have Claude Code write the first draft.

I want to build an app that does [brief description].

Using the DESIGN.md template, draft a design document for this.
Mark anything you're unsure about as TBD — I'll fill those in.

The AI produces a draft. You review it and fill the TBDs. This approach is typically 3–4x faster than writing from scratch, and the quality is usually good enough to build on.

The Core Insight

Most of the slowness in Claude Code-assisted development traces back to the same cause: a spec that asks the AI to make decisions it shouldn't have to make.

AI agents are implementation machines, not judgment machines. When you take on the judgment work upfront — in the form of a thorough design doc — the AI can do what it actually does well, at full speed.

Start your next project with a DESIGN.md. The first one might cost you a couple of hours. Everything after that will be faster than you've seen before.