Part 2. Why Specification-Driven Development

Vibe coding is useful when you're exploring an idea, building a throwaway prototype, or want to quickly see the shape of a solution. But it doesn't hold up well over the long life of a project. There's no persistent memory in chat, requirements get mixed with fixes, and architectural decisions often emerge by accident.

SDD solves this problem not through magic, but by moving context from ephemeral conversation into versioned files. The agent receives not just a command to "do it," but a map of the project: why it exists, what decisions have already been made, what's currently being built, how to verify readiness.

Typical Vibe Coding Failures

1. Intent drift. You asked for a "simple form," the agent added complex state management, a new library, and a different UI style.
2. Context decay. After several sessions, the agent forgets why the project doesn't use an ORM, or why the API must render HTML on the server.
3. Unverifiable results. The agent changed 30 files, and you don't know what criteria to use for acceptance.
4. Hidden decisions. Important decisions stayed inside chat history and never made it into the repository.
5. Reviewer fatigue. The agent writes quickly, but the human gets tired checking a large stream of changes.

SDD doesn't make the agent infallible. It makes errors earlier, smaller, and checkable.

What Changes When Working with Qwen Code

Instead of one long session like this:

qwen
> Build the whole app.
> Fix this.
> Looks wrong.
> Add tests.
> Actually, use SQLite.

You create a sustainable loop:

qwen
> /clear
> Read @specs/mission.md @specs/tech-stack.md @specs/roadmap.md.
> Create a feature specification for the next roadmap phase. Ask me questions first.

Then in a new session:

qwen
> /clear
> Read @specs/mission.md @specs/tech-stack.md and @specs/2026-05-08-reviews-display/plan.md.
> Implement only task groups 1 and 2. Don't change unrelated files.

And separately for verification:

qwen
> /clear
> Compare implementation against @specs/2026-05-08-reviews-display/validation.md.
> List discrepancies before making fixes.

Each session receives exactly the context needed for its role.

SDD Is Not Waterfall

The classic waterfall model tries to describe the entire system upfront. In agent-based SDD, specifications are small, living, and focused on a single feature. You don't write 80 pages before starting. You capture sufficient context for the next meaningful step.

A good feature specification should be:

• small: one phase, one branch, one merge;
• verifiable: there are commands and a manual verification scenario;
• linked to the roadmap;
• understandable to a new agent without prior chat history;
• strict enough that the agent doesn't guess important decisions.

Seven Questions a Good Specification Answers

To avoid reducing a specification to a set of headings, keep these seven questions in mind. If any answer is missing, the specification isn't ready for implementation.

1. What business intent or product task stands behind the feature? That is, why are we doing this, not "what" and "how."
2. Who is the user and what is their scenario? If only an admin uses the feature, that's a different set of decisions than if a visitor sees it.
3. What's in scope and what's out? Explicitly listed boundaries and explicit "beyond the boundaries" protect against scope creep.
4. Which decisions are already made, which are open? Recording made decisions prevents the agent from re-choosing them. Recording open ones helps the human notice and close them before implementation.
5. What constraints cannot be relaxed? Stack, invariants, data schema, API format, security constraints.
6. What must not break? Existing behavior that the feature must not affect (see the separate section on negative requirements in Part 7).
7. How will correctness be proven? Commands, manual scenarios, control values, signs of deviation. Without this, a specification is a wish, not a contract.

These seven questions don't dictate file structure. The structure remains the same: requirements.md, plan.md, validation.md. The seven questions are a content check.

When SDD Is Overkill

You don't need to write a full constitution for a one-off shell script or a small text fix. A lightweight request is sometimes better. Practical rule:

• If the change can be fully understood and verified in 5 minutes, a normal request is enough;
• If the change touches architecture, data, security, public behavior, or multiple files, write a specification;
• If the agent will work autonomously for more than a few minutes, a specification almost always pays off.

Example: Bad Time Economy

You ask:

Add login.

The agent might choose JWT, cookie sessions, OAuth, local users, passwordless login links, PostgreSQL, SQLite, Prisma, Drizzle, password reset, middleware, and UI. If half the choices are wrong, you'll spend time rolling back.

Better to describe first:

# Requirements — Admin Login

## Boundaries
- One login page for admin only.
- Authentication via cookie session.
- No self-registration.
- No password reset in this phase.

## Decisions
- Store one admin in SQLite.
- Use httpOnly cookie.
- Protect only `/dashboard`.

## Verification
- Unauthenticated GET /dashboard redirects to /login.
- Wrong password shows generic error message.
- Correct password sets cookie and redirects to /dashboard.
- `npm test` and `npm run typecheck` pass.

Now the agent doesn't need to guess.

Practice

Take any feature you'd normally ask for in a single phrase. Rewrite it as a mini-specification:

# Requirements — <feature name>

## Boundaries

## Out of scope

## Decisions

## Verification

Then ask Qwen Code:

Review @requirements.md as a feature specification. What's ambiguous enough that implementation could go off track?

Don't ask for code until you've eliminated ambiguity.

Review Questions

1. How does feature-level SDD differ from big upfront design?
2. Why is "the code works" insufficient for accepting agent-made changes?
3. What decisions in your project should be recorded before code generation?