from prompt to production: a structured pipeline for Claude Code

Claude Code in a single terminal, working a small well-scoped task, is capable enough to be genuinely useful. Give it a clear task, let it run, review the diff. That loop handles hundreds of small tasks without much friction.

The problem emerges when the task isn't small. "Build a search feature" or "add multi-tenant billing" is a unit of real work — multiple files, interface decisions, edge cases, tests. Hand that to Claude Code as a single prompt and you get one of two outcomes: a partial implementation that stalls at the first ambiguity, or a complete implementation that misread the requirement somewhere and has to be rebuilt. Both cost more than upfront structural work would have.

The teams shipping production code with Claude Code are doing something more structured. Not because they're disciplined in the abstract, but because the unstructured approach broke on them enough times that they built process to protect against it.

what a structured Claude Code workflow looks like

The stages used by serious Claude Code operators map onto a recognizable shape: scope, design, architecture, implementation, review, release. Each stage has a clear input, a clear output, and a gate before the next one starts.

1. scope the story

Before an agent touches a file, there needs to be a clear statement of what's being built and why — the user problem, the acceptance criteria, the hard edges. What's out of scope matters as much as what's in scope.

This doesn't need to be long. A well-structured story card of 300 words is sufficient for a nontrivial feature. The discipline is writing it before design starts, not after. Agents making design decisions without a scope statement are making assumptions about what matters — and correcting those assumptions late is expensive.

2. design before building

The design stage is where the shape of the solution is decided at the right level of abstraction: what are the UI surfaces, what are the API contracts, how does this feature interact with the existing system?

For UI work, this means wireframes — not a text description of a layout, but a visual representation that makes decisions explicit and checkable. A text spec that says "add a search bar with dropdown results" will be interpreted differently by every agent. A visual spec removes most of that variance. A design agent can produce wireframes from the scope document; a human approves before any code starts.

For backend or API work, the design stage produces interface contracts: function signatures, endpoint shapes, data model changes. Agents implementing to an approved interface don't have to guess at contracts, and reviewers can check implementation against a known target.

This is also the stage that catches the most expensive mistakes. A design decision that turns out to be wrong is a conversation and a revision. An implementation decision that turns out to be wrong is a revert and a rewrite.

3. architecture

Between design and implementation, a brief architecture stage translates the approved design into an execution plan: which files change, what new modules need to exist, the correct order of implementation for parallel agents.

The architecture output is the decomposition document that implementation agents work from. Getting this right before agents start reduces the overhead cost of running parallel Claude Code agents substantially — instead of resolving dependencies when agents collide, you resolve the parallelization plan upfront. This is also where you set the context that keeps decisions consistent across parallel agents without re-briefing each one by hand.

4. implementation

Implementation with an approved design and architecture is significantly more constrained than implementation from a raw prompt. Agents know what they're building, how it should look, what the interfaces are, and which files they own. They're executing a plan, not making one.

This is where parallel agents in isolated worktrees produce the most value. With a clear decomposition from the architecture stage, independent tasks run in parallel without colliding. An agent working on the API layer and an agent working on the UI layer have well-defined interfaces between them — they don't need to coordinate because the architecture stage did that.

5. review

Code review is high-attention work, and a human reviewing several parallel agents' diffs simultaneously is a bottleneck. But much of the mechanical review — type checking, lint, test coverage, security patterns, architecture conformance — can be done by specialist review agents operating with clear briefs.

The pattern that works well uses multiple specialists: a security-focused agent running OWASP checks, a refactor-focused agent scanning for dead code and naming problems, each producing structured output. The human reviewer works from that output rather than raw diffs, keeping attention on intent review — "is this actually the right solution to the problem we scoped?" — rather than things a tool can catch automatically.

6. release

The release stage is the gated exit. Tests pass, review agents signed off, the human approved. The branch is clean. Staging, if you have it, gets a build first. Then main.

The gate matters. Skipping the review stage because something looks fine is how quality debt accumulates. The gate doesn't prevent all mistakes, but it raises the floor: changes that pass it are consistently better than changes that bypass it.

---

why gates matter more than stages

A workflow without gates is a naming convention. The stages are only useful if nothing advances without meeting the exit criteria for the current stage.

This is where most informal Claude Code workflows break down. The stages exist in someone's head — "I'm going to design before building" — but the discipline slips when an agent has already produced code that looks plausible, or when a deadline is close, or when a feature seems small enough to skip the design step.

Explicit gates — an actual approval step before the workflow advances — are what make the stages real rather than ceremonial.

how to implement this without tooling

The spec-driven development approach formalizes this pattern at the document level: write the spec (requirements, design, tasks) and correct it before agents write code. That's the right starting point for teams running Claude Code in an editor or terminal who want to impose structure without adopting new tooling.

The practical discipline is simple: don't run an agent on a feature until you'd be comfortable handing a new engineer the same brief. If the brief isn't clear enough for that, the design stage isn't done.

For teams using CLAUDE.md files to encode conventions, a useful pattern is to include the current story scope and architecture decisions there — so every agent starting on the codebase begins with the current state of decisions, not just the project-level conventions.

what defract does with this pipeline

defract implements the same pipeline as a native macOS app — story → design → architecture → implementation → review → release — where each stage gate is enforced rather than advisory. The visual design stage uses a design agent to produce wireframes before implementation starts; you approve the wireframes before any code is written. The review stage deploys specialist agents (generic, security, and refactor) with structured output. Stage transitions require explicit approval before agents advance.

If you're already running Claude Code and want to see what a gated pipeline looks like in practice, it's a free download.