Skip to main content

Design Before Code

In one line: No code until a design exists — brainstorm → spec → plan → execute.

Do this: For any change you cannot fully hold in your head, write the design first. The 30-60 minutes it costs is cheaper than the rework it prevents.

What: Every non-trivial change follows a mandatory pipeline: brainstorm (explore the problem space) → design specification (commit to an approach with rationale) → implementation plan (decompose into ordered tasks) → execution. No code is written until a design exists.

Why: AI code generation is fast — that is both its strength and its primary risk. Without a design phase, development degenerates into producing plausible code quickly, reviewing it superficially, and committing it, only to rework it when integration reveals the wrong approach, misunderstood scope, or unconsidered edge cases.

The failure mode is rarely "the code doesn't work." It usually does. The failure is that it solves the wrong problem, or solves the right one in a way that breaks downstream. Forcing the architect to articulate the problem, weigh alternatives, and commit to an approach before any code exists eliminates that class of error.

The design also serves the AI: fed a spec before writing code, it aligns on the first attempt rather than the third. A design document is a prompt-engineering artifact, not just human communication.

Evidence: The Brainstorm Gate (Section 3.1) refuses to clear without a design artifact addressing the Decision-Cost Rubric; the missing artifact is detectable in real time. Reproducible: try to advance to implementation with no committed design and the gate blocks you.

How: The Superpowers plugin provides two skills that govern this pipeline:

  1. brainstorming — Structured problem exploration. Produces a problem statement, constraint analysis, and 3+ candidate approaches with tradeoffs. Output is a conversation, not a document. Its purpose is to prevent premature commitment to the first approach that seems reasonable.

  2. writing-plans — Converts brainstorm output into a single design artifact: a formal specification plus an ordered implementation task list. Uses the project's design doc template (audience, problem statement, design decisions table, data flow, API contracts, error handling, testing strategy). Each task specifies inputs, outputs, acceptance criteria, and estimated complexity, sized to be completable in a single agent session (typically 15-60 minutes of implementation). The artifact is committed to docs/ before any implementation begins.

The pipeline is not mandatory for trivial changes (typo fixes, configuration updates, single-line bug fixes). The threshold is judgment-based: if you can fully hold the change and all its implications in your head, skip the pipeline. If you cannot, the pipeline is cheaper than the rework.

For deeper treatment of ADR practices, see appendix-g-adr.md.