Phase 2: Writing Effective Specifications

A spec is a contract between you and Claude. Vague contracts produce vague results.

In the previous lesson, you learned how to spawn parallel subagents to research a problem from multiple angles. Now that you have research findings, you need to capture them in a document that Claude can execute flawlessly. This is where most developers fail—not because they lack research, but because they write specs that leave too much to interpretation.

Consider this: when you hand a specification to a human developer, they ask clarifying questions. When you hand the same specification to Claude, it makes assumptions. Every assumption is a potential bug. Every ambiguity becomes a decision made without your input. The goal of specification writing is to answer questions before they're asked.

Addy Osmani (Chrome Engineering Lead) describes effective specifications as combining PRD thinking (why we're building this) with SRS precision (how it should behave). Your spec should give Claude both the motivation and the mechanics.

The Four-Part Specification Template

Every effective specification follows a consistent structure. Here's the template that separates sellable Digital FTEs from weekend experiments:

Why this structure works: Each part serves a distinct purpose. Reference Architecture tells Claude what good looks like. Current Architecture shows Claude where you are. Implementation Plan provides the path. Checklist enables task extraction for Phase 4. Constraints prevent wrong turns. Success Criteria define done.

What Makes Specs Effective

Three qualities separate specifications that work on first attempt from those requiring five iterations:

1. Explicit Constraints (What NOT to Do)

Constraints are often more important than requirements. They prevent Claude from making reasonable but wrong choices.

Why constraints matter: Without them, Claude optimizes for the general case. Your system is not the general case. Constraints encode your specific context.

2. Measurable Success Criteria (Not "Fast", Not "Good")

Every success criterion must be testable. If you can't write a test for it, it's not a criterion—it's a wish.

How to convert vague to measurable: Ask "How would I know if this failed?" The answer is your criterion.

3. Checklist Format for Task Extraction

Phase 4 of SDD uses the Task system to delegate work to subagents. Each checklist item becomes a potential task. Write them as atomic units of work.

Bad checklist items (too vague, can't be delegated):

• Set up the system
• Make it work
• Test everything

Good checklist items (atomic, delegatable):

• Create /lib/cache.ts with LRU implementation (max 1000 entries)
• Add cache middleware to /api/products endpoint
• Write tests for cache hit/miss/eviction scenarios
• Update /docs/caching.md with new configuration options

Rule of thumb: If you can't explain the task to a junior developer in one sentence, it's not atomic enough.

Anti-Patterns to Avoid

Anti-Pattern 1: HOW Instead of WHAT

Specifications describe behavior, not implementation. Let Claude choose the how.

Why this matters: Claude often knows better implementation patterns than you. By specifying behavior, you get the benefit of its knowledge. By specifying implementation, you lock in your assumptions.

Anti-Pattern 2: Missing Constraints

No constraints means Claude decides everything. This is Vibe Coding with extra steps.

Anti-Pattern 3: Vague Success Criteria

"Works correctly" is not a success criterion. Neither is "user-friendly" or "efficient."

A Complete Specification Example

Here's a real specification that follows all principles:

Notice: This spec answers every question Claude might ask. Reference Architecture shows what good looks like. Current Architecture shows where we're starting. Implementation Plan provides sequence. Checklist enables task delegation. Constraints prevent wrong turns. Success Criteria define done.

Try With AI

Running Example Continued: We have research.md from parallel investigation. Now we write report-spec.md.

Prompt 1: Draft Specification from Research

What you're learning: The spec transforms research findings into a writing plan. Research.md's "tool capabilities" becomes the comparison section. "ROI data" becomes the business case section. "Gaps CTOs would ask about" become sections we must address or explicitly scope out.

Prompt 2: Strengthen Constraints

What you're learning: Constraints prevent scope creep. Without "NOT a tutorial," you'd explain how to use each tool. Without "CTOs have engineers," you'd dive into technical setup. Constraints encode audience judgment.

Prompt 3: Make Criteria Testable

What you're learning: Vague criteria let anything pass. "Each tool section includes pricing and limitations" is testable. "CTO can justify tool selection to their board" defines actual success.