claude-code-ultimate-guide/guide/diagrams/06-development-workflows.md

title	description	tags
Claude Code — Development Workflows Diagrams	TDD cycle, spec-first pipeline, plan-driven workflow, iterative refinement loop	workflows tdd spec-first plan-driven iterative

Development Workflows

Proven patterns for structuring AI-assisted development sessions.

---

TDD Red-Green-Refactor with Claude

Test-Driven Development adapted for Claude Code: write the failing test first, then ask Claude to implement only what's needed to pass it. This prevents over-engineering and ensures tests actually verify behavior.

flowchart TD
    A([Start: New feature needed]) --> B(Write failing test\nwith human)
    B --> C(Run tests)
    C --> D{Tests fail\nas expected?}
    D -->|No: tests pass\nbefore impl!| E(Fix test — it's too weak)
    E --> B
    D -->|Yes: RED ✓| F(Ask Claude to implement\nminimal code to pass)
    F --> G(Run tests again)
    G --> H{Tests pass?}
    H -->|No| I(Diagnose with Claude\nfix implementation)
    I --> G
    H -->|Yes: GREEN ✓| J{Code needs\nrefactoring?}
    J -->|Yes| K(Refactor with Claude)
    K --> L(Run tests: still green?)
    L -->|No| I
    L -->|Yes: REFACTOR ✓| M{More features\nneeded?}
    J -->|No| M
    M -->|Yes| B
    M -->|No| N([Feature complete ✓])

    style B fill:#E85D5D,color:#fff
    style F fill:#E85D5D,color:#fff
    style D fill:#E87E2F,color:#fff
    style H fill:#E87E2F,color:#fff
    style J fill:#E87E2F,color:#fff
    style G fill:#7BC47F
    style K fill:#6DB3F2,color:#fff
    style N fill:#7BC47F

ASCII version

Write failing test (RED)
        │
    Run tests
        │
  Fail as expected?
  ├─ No  → Fix test (too weak)
  └─ Yes → Ask Claude: implement minimal code
                │
           Run tests
                │
           Pass? (GREEN)
           ├─ No  → Diagnose + fix
           └─ Yes → Refactor?
                    ├─ Yes → Refactor (REFACTOR) → re-run tests
                    └─ No  → Next feature

Source: TDD with Claude

---

Spec-First Development Pipeline

Write the specification before the code. Claude uses the spec as the single source of truth — preventing drift between what was planned and what was built.

flowchart LR
    A([Idea / Requirement]) --> B(Write spec.md\nin natural language)
    B --> C(Claude reviews spec\nfor clarity + completeness)
    C --> D{Spec approved\n by human?}
    D -->|No: gaps found| E(Refine spec\naddress gaps)
    E --> C
    D -->|Yes| F(Generate tests\nfrom spec)
    F --> G(Generate implementation\nfrom spec + tests)
    G --> H(Run test suite)
    H --> I{All tests\npass?}
    I -->|No| J(Claude fixes\nimplementation)
    J --> H
    I -->|Yes| K(Human review\nspec vs output)
    K --> L{Matches\nspec?}
    L -->|No| M(Update spec\nor implementation)
    M --> K
    L -->|Yes| N([Merge ✓])

    style A fill:#F5E6D3
    style B fill:#6DB3F2,color:#fff
    style D fill:#E87E2F,color:#fff
    style I fill:#E87E2F,color:#fff
    style L fill:#E87E2F,color:#fff
    style N fill:#7BC47F

ASCII version

Idea → Write spec.md → Claude reviews
                             │
                       Approved? ─No→ Refine spec
                             │ Yes
                       Generate tests from spec
                             │
                       Generate implementation
                             │
                       Run tests → Pass? ─No→ Claude fixes
                             │ Yes
                       Human review → Matches spec? ─No→ Fix
                             │ Yes
                           Merge ✓

Source: Spec-First Development

---

Plan-Driven Workflow with Annotation

Complex tasks benefit from plan mode: Claude explores the codebase, proposes a plan, you annotate it, then Claude executes only what was approved. Prevents surprises on large refactors.

flowchart TD
    A([Complex task given]) --> B(Enter Plan Mode\nShift+Tab × 2)
    B --> C(Claude explores\ncodebase structure)
    C --> D(Claude proposes plan\nwith file list)
    D --> E(Human reviews plan)
    E --> F{Plan\nacceptable?}
    F -->|No: issues found| G(Human annotates plan\nmarks corrections)
    G --> H(Claude revises plan)
    H --> E
    F -->|Yes| I(Approve plan\nExit Plan Mode)
    I --> J(Claude executes\nstep by step)
    J --> K(Claude reports\nprogress)
    K --> L{Unexpected\nissue?}
    L -->|Yes| M(Claude flags issue\nasks for guidance)
    M --> F
    L -->|No| N{All steps\ncomplete?}
    N -->|No| J
    N -->|Yes| O([Task done ✓])

    style A fill:#F5E6D3
    style B fill:#6DB3F2,color:#fff
    style F fill:#E87E2F,color:#fff
    style L fill:#E87E2F,color:#fff
    style N fill:#E87E2F,color:#fff
    style G fill:#F5E6D3
    style O fill:#7BC47F

ASCII version

Complex task
     │
Plan Mode (Shift+Tab×2)
     │
Claude explores codebase
     │
Claude proposes plan
     │
Human reviews ──No──► Annotate + Claude revises ──► re-review
     │ Yes
Approve + exit plan mode
     │
Claude executes step by step
     │
Unexpected? ──Yes──► Flag + ask guidance
     │ No
Done? ──No──► continue
     │ Yes
Complete ✓

Source: Plan-Driven Workflow

---

Iterative Refinement Loop

Output rarely hits the mark on the first try. This loop gives you a systematic way to improve results through targeted feedback rather than "make it better" vague instructions.

flowchart TD
    A([Initial prompt]) --> B(Claude generates output)
    B --> C(Evaluate output quality)
    C --> D{Good\nenough?}
    D -->|Yes| E([Done ✓])
    D -->|No| F(Identify specific issue\nWhat exactly is wrong?)
    F --> G{Issue type?}
    G -->|Style/tone| H(Add: style constraints)
    G -->|Missing info| I(Add: provide missing context)
    G -->|Wrong approach| J(Add: redirect approach)
    G -->|Too verbose/brief| K(Add: length constraint)
    H --> L(Refine instruction)
    I --> L
    J --> L
    K --> L
    L --> M(Claude refines output)
    M --> N(Compare before/after)
    N --> O{Improvement\ndetected?}
    O -->|Yes| C
    O -->|No| P(Different\napproach needed)
    P --> F

    style A fill:#F5E6D3
    style D fill:#E87E2F,color:#fff
    style G fill:#E87E2F,color:#fff
    style O fill:#E87E2F,color:#fff
    style E fill:#7BC47F
    style L fill:#6DB3F2,color:#fff
    style P fill:#E85D5D,color:#fff

ASCII version

Prompt → Output → Evaluate → Good? ──Yes──► Done
                                 │ No
                          Identify specific issue
                                 │
                          ┌──────┴──────────────┐
                         Style  Missing  Wrong  Length
                          └──────┬──────────────┘
                          Refine instruction
                                 │
                          Claude refines
                                 │
                          Better? ──Yes──► Evaluate again
                                 │ No
                          Different approach

Source: Iterative Refinement — Line ~347