Why AI Needs a Structured Phase Workflow: From One‑Shot Prompts to the 5‑Stage Spec‑Kit Model

Hello, I'm James. In the previous post I explained how externalizing decisions into a CLAUDE.md file lets AI load a stable set of decisions instead of relying on ad‑hoc consensus. This article introduces the second core principle: structuring the workflow into distinct phases.

01 | What Happens When You Give AI a One‑Sentence Requirement

Example request: “Help me write a user‑management system.” The AI immediately produces a monolithic code bundle containing a User model, CRUD API, front‑end pages, and login logic. Although the output looks complete, several mismatches appear:

Requirement misalignment: the user‑management you need is a multi‑tenant SaaS team‑member manager, but the AI generated a simple single‑tenant user table.

Technology‑stack mismatch: the AI used JWT while your project already uses session‑based authentication.

Boundary overreach: the AI also implemented “send registration invitation email,” a feature that was not in scope.

Layered false assumptions: each layer (field format, API call style, UI interaction) assumed correctly in isolation, but together they form a cascade of errors.

The result is usually a complete rewrite or a time‑consuming fix, not a productivity gain. The root cause is mixing requirement analysis, solution design, and code implementation into a single step, allowing early‑stage assumptions to amplify later.

02 | How Phase‑Based Work Improves Quality

Human engineers hold requirement‑review, design‑review, and code‑review meetings not because the meetings are valuable per se, but because the “pause points” force alignment before moving forward. AI needs the same mechanism.

Reduce accumulated assumption errors: each phase generates its own set of hypotheses (problem definition, user stories, technical design). If all phases run in one burst, erroneous hypotheses propagate downstream, making later corrections expensive.

Validate assumptions at the end of each phase: by checking the deliverable before proceeding, errors are caught early and do not flow into the next stage.

Independent verification: Discover produces a problem statement and scope document; Define yields user stories and acceptance criteria; Design creates a technical design doc, API contract, and architecture diagram; Develop outputs code, tests, and review records; Deliver provides test reports, deployment scripts, and user documentation. Each artifact can be reviewed without relying on later context.

AI stays on track: when the AI knows it is in the Define phase, it writes user stories instead of code; in the Design phase it produces design artifacts instead of implementation.

03 | The Five‑Stage 5D Framework (Spec‑Kit)

Spec‑Kit proposes the most mature phase division used in current engineering practice:

Discover: Ask what problem are we solving? Output: PROBLEM.md, SCOPE.md.

Define: Clarify what we will build. Output: SPEC.md, USER_STORIES.md, feature list, data‑model draft.

Design: Decide how we will build it. Output: technical design doc, API contract, architecture diagram, ADRs.

Develop: Write the code. Output: source files, unit/integration tests, code‑review records.

Deliver: Final hand‑off. Output: test report, deployment scripts, changelog, user documentation, release confirmation.

Each stage produces concrete, version‑controlled artifacts rather than informal discussion.

04 | Core Deliverables per Phase

Discover – PROBLEM.md, SCOPE.md – organize problem statement and boundaries.

Define – SPEC.md, USER_STORIES.md – write user stories and acceptance criteria.

Design – DESIGN.md, API.md – produce technical solution and interface design.

Develop – source code, test files – implement according to the design.

Deliver – CHANGELOG.md, deployment scripts – prepare release notes and deployment.

These artifacts can be reviewed independently and serve as inputs for the next phase.

05 | Gates Between Phases

Transition between phases is not automatic; a "gate" (checkpoint) requires human confirmation that the current deliverable is correct before the AI proceeds.

Discover completed → output PROBLEM.md + SCOPE.md
    ↓
[Gate] Human confirms: “Is this the problem we need to solve? Are the boundaries correct?”
    ↓
Define starts

Define completed → output SPEC.md + USER_STORIES.md
    ↓
[Gate] Human confirms: “Do these user stories cover all requirements? Are acceptance criteria clear?”
    ↓
Design starts

The gate ensures the AI cannot decide on its own that the previous phase is finished; a human must intervene, protecting the project from costly downstream fixes.

06 | Three Phase‑Strategy Frameworks

Spec‑Kit (Hard Gate): Every phase ends with a mandatory human confirmation. Provides strict control, prevents assumption leakage, but adds overhead—suitable for complex, high‑risk projects.

GSD (Wave Scheduling): Uses "waves" instead of strict phases; tasks within a wave can run concurrently. Faster execution but weaker phase discipline—best for projects with clear technical plans that need high throughput.

OpenSpec (Incremental Intervention): Targets brownfield projects; inserts a "Delta Spec" only where changes are needed, leaving the rest of the codebase untouched. Ideal for incremental feature work on existing systems.

Choosing a strategy:

New, complex projects → Spec‑Kit.

Clear roadmap, need parallel work → GSD.

Existing codebase, localized changes → OpenSpec.

07 | Practical Template: WORKFLOW.md

Save the following markdown in WORKFLOW.md and have the AI load it at the start of each session:

# Project Workflow

## Phase Definitions

### Phase 1: Discover
**Goal**: Clarify problem and scope
**Output**: `docs/PROBLEM.md`
**Entry Condition**: Clear requirement description
**Exit Condition**: Human confirms PROBLEM.md is accurate

### Phase 2: Define
**Goal**: Define functional specs
**Output**: `docs/SPEC.md`
**Entry Condition**: PROBLEM.md confirmed
**Exit Condition**: Human confirms SPEC.md is complete

### Phase 3: Design
**Goal**: Choose technical solution
**Output**: `docs/DESIGN.md`
**Entry Condition**: SPEC.md confirmed
**Exit Condition**: Human confirms DESIGN.md is reasonable

### Phase 4: Develop
**Goal**: Implement features
**Output**: code + tests
**Entry Condition**: DESIGN.md confirmed
**Exit Condition**: Tests pass, code review done

### Phase 5: Deliver
**Goal**: Release
**Output**: `CHANGELOG.md` + deployment confirmation
**Entry Condition**: Develop completed
**Exit Condition**: Human confirms release

## AI Working Rules
1. At start, confirm current phase.
2. Perform only tasks for that phase.
3. After finishing, output deliverable and wait for human confirmation.
4. Upon confirmation, move to next phase.

The template is lightweight; you can merge or drop phases for small tasks.

08 | Common Pitfalls

Pitfall 1: Over‑granular phases create many gates and stall progress. Keep phases to 3‑5 and place gates only at high‑value checkpoints (requirement correctness, design feasibility).

Pitfall 2: Skipping the Design phase leads to sub‑optimal technical choices (e.g., processing 100k items with a naïve loop). Design acts as a low‑cost alignment step before code.

Pitfall 3: Treating gates as formality—AI announces completion but proceeds without real human review. The gate must be a genuine pause awaiting explicit confirmation.

Summary

One‑sentence demands cause AI to mix analysis, design, and implementation, amplifying early mistakes into costly rework.

Phase‑based workflows reduce accumulated assumption errors and allow independent verification of each stage.

The 5D Spec‑Kit framework (Discover → Define → Design → Develop → Deliver) is the most mature division.

Each phase produces concrete artifacts and is protected by a human‑confirmed gate.

Three strategies exist: Spec‑Kit (hard gates), GSD (wave scheduling), OpenSpec (incremental intervention); choose based on project type.

Implement a reusable WORKFLOW.md so the AI always knows the current phase and rules.

Avoid too many phases, skipping Design, and treating gates as paperwork.

Next, we will discuss the third principle: task atomization—why breaking large tasks into small ones improves AI output quality given context‑window limits.