Part 3. Process Overview

The SDD process can be thought of as several layers of memory. The top layer is the project constitution. The middle layer is feature specifications. The bottom layer is implementation and verification. Between features there is replanning: you update the upper layers if new work shows that old decisions are inaccurate.

Basic cycle:

flowchart TD
  A["Constitution<br/>mission.md<br/>tech-stack.md<br/>roadmap.md"] --> B["Feature specification<br/>requirements.md<br/>plan.md<br/>validation.md"]
  B --> C["Implementation<br/>code, tests, migrations"]
  C --> D["Verification<br/>automatic and manual facts"]
  D --> E{"Did facts pass?"}
  E -- "yes" --> F["Merge"]
  F --> G["Replanning<br/>update rules and roadmap"]
  G --> A
  E -- "no" --> B

Role of the Constitution

The constitution answers questions that should not be re-decided for every feature:

• why the project exists;
• who it is built for;
• what stack is used;
• what architectural constraints are already accepted;
• what phases are planned, active, or completed.

In Qwen Code this layer is supplemented by a QWEN.md file. The difference is: QWEN.md tells the agent how to behave in the repository, while specs/*.md tell what the product builds.

Example structure:

agentclinic/
  QWEN.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md

Role of Feature Specification

For each roadmap phase a separate folder is created:

specs/
  2026-05-10-feedback-form/
    requirements.md
    plan.md
    validation.md

requirements.md fixes boundaries, what is out of scope, decisions, and context.

plan.md breaks work into task groups.

validation.md describes how to know that a branch can be merged.

These files are more important than chat history. A new Qwen Code session continues work by reading only the repository.

Role of Branches

Each feature phase should live in a separate Git branch:

git checkout -b phase-1-hello-hono

This reduces cognitive load when working with the agent. If the agent changed too much, you have a clear boundary: all changes in this branch must correspond to a specific specification folder.

Role of /clear

In Qwen Code a fresh context helps verify that the specification is sufficient. If the agent can implement the feature after /clear, it means the necessary knowledge is written in files, not hidden in chat memory.

Example:

/clear

Read @QWEN.md, @specs/mission.md, @specs/tech-stack.md
and @specs/2026-05-10-feedback-form/plan.md.
Implement only task group 1. Stop after the list of changed files.

If after clearing the agent asks reasonable clarifying questions, that is normal. If it starts guessing, the specification is incomplete.

Four Modes of Working with the Agent

1. Interview mode. The agent asks questions and helps write the specification.
2. Implementation mode. The agent implements specific task groups.
3. Verification mode. The agent looks for mismatches between code and specification.
4. Replanning mode. The agent updates the constitution, roadmap, changelog, and process.

Do not mix these modes unnecessarily. When in one session you first discuss the product, then ask for code, then verification, the agent starts pulling old context into places where it should work from the file.

The "Plan — Implement — Verify" Loop

Within a single feature, modes 2 and 3 are conveniently represented as the "Plan — Implement — Verify" loop (in English-language sources this is called Plan-Act-Verify). The loop defines three phases and explicit constraints for each:

• Plan. The agent lists what it intends to do, which files it will touch, which checks it will run. At this step the agent does not write code or change files. If the plan contains changes not in requirements.md, that is a signal to clarify the specification, not to "let's try it".
• Implement. The agent changes code within the approved plan. Extending the plan during implementation is forbidden: a new idea becomes either a separate task group or a specification correction.
• Verify. The agent compares the result with validation.md, lists what passed, what failed, and what was not checked. At this step the agent does not fix code — it only writes a report.

It is useful to keep these three phases in mind both when formulating requests and when reading agent responses: if the response mixes "I am planning" and "I already did it," you lost the control point. In part 8 these constraints turn into specific requests for each phase.

Three Specification Modes

Not every piece of work is described the same way. It is convenient to distinguish three modes:

• Requirements-First. The default mode of this textbook. Used for features where the main thing is what should appear: a reviews page, a feedback form, a new route.

• Design-First. Applied when requirements have been clear for a while, and the main risk is how exactly to implement: schema migration, public API change, module reorganization. Here plan.md or a separate design.md is written first, and only then detailed requirements.
• Bugfix specification. A separate mode for fixes: instead of "what should appear" — "what reproduces the bug," "what result was expected," "what should not change when fixing." More details in part 11.

In the tutorial project AgentClinic you will almost always work in Requirements-First mode. The names of the other modes are needed so as not to stretch the first template into places where it gets in the way.

Example Qwen Code Request for Project Overview

You are helping me work in SDD.
Do not write code yet.
Read @README.md and look at the repository structure.
Suggest an initial specs/ catalog:
- mission.md
- tech-stack.md
- roadmap.md

Before writing files, ask exactly three grouped questions:
1. Mission and audience
2. Technical stack and constraints
3. Roadmap and first phase

Practice

Create an empty structure in the tutorial project:

mkdir -p specs

touch specs/mission.md specs/tech-stack.md specs/roadmap.md

Leave the files empty for now. In the next part we will configure Qwen Code so that it understands the project rules, and then fill the constitution deliberately.

Review Questions

1. Why is it better to store feature specifications next to the code rather than in a separate document?
2. When should replanning be done?
3. What does successful implementation after /clear demonstrate?