Part 1. Introduction

Specification-Driven Development, or SDD, shifts the control point in development with agents. In the familiar "vibe-coding" mode — when a developer writes a short free-form prompt like "make me a feedback form" and accepts the result on gut feeling — the agent quickly generates code, and then a series of fixes begins. This works for a prototype, but scales poorly to a large system: decisions remain in the chat, architecture sprawls, and the next agent or next session no longer knows why the code looks the way it does.

In SDD, the specification becomes the main artifact. Code remains important, but appears as a result of executing the specification. The human is responsible for intent, constraints, acceptance criteria, and quality control. The agent is responsible for speed, code search, routine implementation, and mechanical changes.

In this tutorial, we will use Qwen Code CLI. The SDD methodology itself is not tied to a specific agent: it can be implemented in Qwen Code, Claude Code, Codex CLI, Cursor, JetBrains AI Assistant. Qwen Code is suitable for this work because it runs from the terminal, reads project files, supports QWEN.md, @file commands, shell commands via !, headless mode, project skills, and MCP.

Terminology agreement. In this text, the word "agent" means Qwen Code CLI (or its equivalent) — a tool that reads specifications and writes code. The tutorial project AgentClinic has its own in-domain "agents" — fictional AI characters who are patients at the clinic. If the context is unclear, there will be a clarification of "agent-tool" or "clinic character".

How to read the tutorial's claims

The tutorial relies on claims of varying strength. To avoid mixing "how Qwen Code exactly works" with "how teams commonly do things" and with "what people are only trying out", disputed points will be marked:

• Standard. Fixed behavior of the tool or a generally accepted SDD practice. Example: "QWEN.md is loaded at the start of a Qwen Code session" — standard.

• Recommendation. An experienced practice that works in most cases but allows reasonable exceptions. Example: "split a phase longer than two days into two" — recommendation.
• Frontier. An approach that is being used but has not yet stabilized; results depend heavily on the team. Example: "full automation of review through a multi-agent pipeline" — frontier.

If there is no mark, treat the claim as either a standard or a recommendation. Frontier will be marked explicitly.

What you will build

The tutorial project is called AgentClinic. It is a satirical web application: AI agents come to a clinic to recover from working with humans. The example is funny in content, but technically serious: TypeScript, Hono, server-side JSX, SQLite, Vitest, CSS, feature specifications, and a change log.

You are not required to copy this project literally. Its role is to provide a stable tutorial model. After completing the tutorial, you can replace AgentClinic with your own service, internal tool, analytics application, or legacy project.

What will count as success

By the end of the tutorial, you should have a repository where:

• there is a QWEN.md with working rules for Qwen Code;

• there are specs/mission.md, specs/tech-stack.md, specs/roadmap.md;
• every major feature starts with requirements.md, plan.md, validation.md;
• implementation goes in a separate branch;
• verification criteria are written before the code;
• after the phase, the roadmap, specifications, and change log are updated;
• the repeatable feature specification process is formalized as .qwen/skills/feature-spec/SKILL.md;
• the agent can be replaced without losing project memory.

The human's basic role

In SDD, the developer does not disappear. Their work becomes more like that of an architect and editor of the intent layer:

• formulate what needs to be built;
• decide which constraints are non-negotiable;
• indicate where the agent may choose independently;
• check not only the code, but also the code's compliance with the specification;
• update specifications when the understanding of the project changes.

The most common mistake is to treat the specification as bureaucracy. In development with agents, the specification is not paper for a manager. It is an input file for a machine that determines the quality of the result.

Minimal vocabulary

Constitution — project constitution: mission, stack, roadmap, key agreements.

Feature specification — requirements, plan, and verification criteria for one feature.

Verification — confirmation that the implementation matched the specification.

Replanning — updating the constitution and roadmap between features.

Skill — a repeatable instruction for the agent in SKILL.md format.

QEN.md — permanent Qwen Code context for a project or user.

First example: bad and good prompt

Bad prompt:

Add a reviews page.

Problem: the agent will decide on its own where to store reviews, whether ratings are needed, whether a form is needed, how to validate fields, how to update navigation, whether tests are needed.

SDD-style prompt:

Start a new feature specification for the next roadmap phase: reviews display.
First read specs/mission.md, specs/tech-stack.md, and specs/roadmap.md.
Then ask me questions about boundaries, decisions, and context.
After answers, create specs/YYYY-MM-DD-reviews-display/requirements.md,
plan.md, and validation.md. Do not write code yet.

The difference is not in the length of the prompt, but in control. In the second case, the agent does not jump into code; it helps create an artifact that will live in the repository.

Practice

Create an empty directory for the tutorial project:

mkdir agentclinic
cd agentclinic
git init

Create a draft README.md:

# AgentClinic

AgentClinic is a fictional clinic where AI agents recover from working with humans.

Project stakeholder wishes:
- the engineering team wants clear tutorial code in TypeScript;
- the product team wants agents, ailments, therapies, appointments, reviews, and feedback;
- marketing needs a memorable browser experience.

Do not ask Qwen Code to write code yet. At this stage, the task is to fix the project idea and prepare the ground for the constitution.

Review questions

1. In SDD, where is the main source of truth: in the code, the chat, or the specifications?
2. Why can the same change through a specification be cheaper than a series of "prompt — fix" iterations?
3. What should a human do if an agent proposes a technically working but product-wrong solution?