Spec-Driven Development: Why Quality is Designed Before Building

The Problem with Building First

Many teams start where they think they should: writing code. Or asking AI to generate components, flows, integrations. The result is predictable: it works, but no one knows for certain what it does, why it does it that way, or how to change one piece without breaking others.

This happens because quality becomes an inspection problem: you wait to have something finished, you test it, you discover defects, you go back. It's like building a house, inspecting the foundations after the roof is done, and only then discovering they're broken. The cost of correction is exponential.

In Galaxy, the opposite happens.

What is Spec-Driven Development

Spec-Driven Development (SDD) inverts the order: before writing a single line of code, you write the specification. It's not decorative documentation that no one reads afterward. It is a verifiable artifact that defines what to build, how it should behave, and how you'll know it works.

The specification is your single source of truth. Every team member, every tool (including AI), every verification phase consults it. There are no floating interpretations. There is no "I thought you wanted this but I built that".

Why Specification First

Writing the spec before building forces you to think. To ask uncomfortable questions:

• What is the exact desired outcome?
• Under what conditions is it considered complete?
• What can go wrong and how do we detect it?
• What happens if the user does X when we expected them to do Y?

This clarity is where quality lives. Not in elegant code. In conscious decisions, recorded, communicated.

AI provides the volume: it can generate functions, write tests, suggest flows. But it generates based on what you ask it. If you pass it a precise spec, the volume is useful. If you pass it vague intentions, the volume is noise.

The Spec → Plan → Build → Operate Cycle

Phase 1: Spec (Specification)

Here you write what gets built, not how. It includes:

• Functional description of expected behavior
• Acceptance criteria (concrete scenarios)
• Edge cases and error situations
• Input and output interfaces
• Technical or business constraints

Verifiable artifact: The specification document itself. It can be structured markdown, an annotated data model, or a set of user stories written with precision.

Verification: Could someone who never saw this build it using only the spec? If the answer is "no", the spec is not ready.

Phase 2: Plan (Planning)

Based on the spec, you design how to build it. Here:

• You break down the spec into actionable tasks
• You assign responsibilities (humans or AI)
• You estimate effort and dependencies
• You define what tools you'll use and why
• You plan incremental verification

Verifiable artifact: A traceable execution plan. Each task connected to its spec section, each deliverable to its acceptance criterion.

Verification: Is it clear how each task closes a spec requirement? Is any requirement missing? Are there blockers that need to be resolved before moving forward?

Phase 3: Build (Construction)

Now you build. With the spec and plan as your compass, AI can accelerate without losing direction:

• You generate components, services, queries based on the spec
• Each build is verifiable against specific criteria
• Tests are written in parallel, guided by the spec
• Each design decision is documented (why you chose architecture A over B)

Verifiable artifact: Code that passes tests. But more importantly: a decision log. Each commit explains which spec requirement it closes.

Verification: Does the code reflect the spec? Did I pass the tests? Can I trace each line of code back to its requirement?

Phase 4: Operate (Operation)

In production, the spec remains your ally:

• When something fails, you go back to the spec: was that expected behavior?
• When you need to scale, the spec tells you what cannot change
• When new requirements arrive, the old spec shows you what the baseline was
• When new people join, the spec is their entry point

Verifiable artifact: Operational metrics connected to spec criteria. SLOs, alerts, dashboards that measure exactly what the spec promised.

Verification: Does the system behave in production as the spec defined? Are there divergences? Did you learn something that requires updating the spec for the next version?

Why This Multiplies Traceability

Every decision remains anchored in the spec. That means:

Backward traceability: You see a bug in production → you check the spec → you understand if it was misinterpretation, requirement change, or genuine failure.

Forward traceability: You need to add functionality → you consult the existing spec → you understand what you cannot break.

Cross-functional traceability: Different teams work in parallel but all against the same spec. There are no integration surprises because everyone built the same thing.

AI amplifies this. It generates code faster, but from a clear spec. It proposes variations, but always within what's specified. It detects inconsistencies more quickly because it's not navigating by intuition.

Practice in Galaxy

In Galaxy, specifying is the work. It's not a formality. It's where real thinking happens, team alignment, quality design.

When we write the spec:

• We ask uncomfortable questions together
• We discuss trade-offs explicitly
• We document why we chose one approach over another
• We create a recorded agreement before the machine starts working

Then, when AI accelerates construction, it does so within clear boundaries. It's not a moving target. It's not "let's see what you come up with". It's "build exactly this, and let's see together if what you built complies". 💡

How to Know Your Spec is Ready

Before moving to Plan:

• Does someone without technical context understand what will be built?
• Are the acceptance criteria verifiable without ambiguity?
• Are edge cases documented?
• Is the scope and out-of-scope clear?
• Are there design decisions that need technical ratification?

If you can't answer "yes" to all of them, the spec is not ready. And that's good: better to find out now than after building.