Topic: Part 3. SDD (Structured Design Driven) Process Overview
Difficulty level: Medium
Estimated study time: 4-6 hours (theory + practice)
Prerequisites: Basic understanding of Git and branch workflow
Experience working with markdown documents
Understanding of software development fundamentals (requirements, planning, testing)
Familiarity with the concept of AI coding agents (preferably Qwen Code)
Completion of Part 1 and Part 2 of the course (or equivalent experience)
Learning objectives: Explain the three-layer architecture of the SDD process (constitution → specification → implementation) and describe the role of each layer
Independently create a specs/ structure with mission.md, tech-stack.md, roadmap.md files for a study project
Apply the Plan — Implement — Verify loop when working with an AI agent, formulating clear requests for each phase
Use the /clear command to validate specification completeness and explain its diagnostic value
Select the appropriate specification mode (Requirements-First, Design-First, Bugfix) depending on the task type
Overview: This part of the course reveals the architecture of the Structured Design Driven (SDD) process — a software development methodology optimized for working with AI agents. The process is modeled as three memory layers: top (project constitution), middle (feature specifications), and bottom (implementation and verification). The key innovation is the explicit separation of agent work modes and the strict Plan — Implement — Verify loop that prevents "leakage" of context between phases. The material is practice-oriented: you will learn to create a repository where knowledge "lives" in files rather than chat history, which is critically important for reproducibility when working with AI assistants.
Key concepts: Three-layer SDD architecture: A metaphor for process memory: the top layer (constitution: mission.md, tech-stack.md, roadmap.md) answers questions that should not be re-decided for every feature; the middle layer (feature specification: requirements.md, plan.md, validation.md) describes specific work; the bottom layer (implementation: code, tests, migrations + verification) is execution. Re-planning occurs between layers when inaccuracies are discovered.
Project constitution: Foundational documents that fix the mission, audience, technology stack, architectural constraints, and roadmap phases. In projects with Qwen Code, supplemented by a QWEN.md file that tells the agent HOW to behave in the repository, as opposed to specs/*.md files that tell WHAT the product should build.
Feature specification: An isolated folder for each roadmap phase (e.g., specs/2026-05-10-feedback-form/), containing three mandatory files: requirements.md (boundaries, exclusions, decisions, context), plan.md (task groups), validation.md (merge criteria for the branch). These files are more important than chat history — a new session continues work by reading only the repository.
Git branches as cognitive boundaries: Each feature phase lives in a separate branch (git checkout -b phase-1-hello-hono). This creates a clear boundary: all branch changes must relate to a specific specification folder. When the agent makes excessive changes, there is a rollback point.
/clear command as diagnostics: A check for specification completeness: if the agent can implement the feature after clearing context, then knowledge is recorded in files. Reasonable clarifying questions are normal; guessing signals an incomplete specification.
Four agent work modes: Interview (writing specifications), Implementation (specific task groups), Verification (code ↔ specification mismatches), Re-planning (updating constitution, roadmap, journal). Mixing modes in one session leads to "pollution" of context.
Plan — Implement — Verify loop (plan-act-verify): Within implementation and verification modes: Plan — the agent lists intentions without changing files; Implement — code within the approved plan (extensions prohibited); Verify — comparison with validation.md, report without code edits. Mixing phases = loss of control point.
Three specification modes: Requirements-First (default — what should appear), Design-First (how to implement — for migrations, APIs, reorganization), Bugfix (what reproduces the bug, expected result, what should not change). Mode selection prevents stretching an unsuitable template.
Practice exercises: Name: Creating the constitution skeleton
Problem: In the study project AgentClinic, create a specs/ structure with empty mission.md, tech-stack.md, roadmap.md files. Then write a prompt for Qwen Code that will make the agent fill in these files by asking exactly three grouped questions (mission and audience, technology stack, roadmap). Important: the agent must not write code or create files before receiving answers.
Solution: 1. In terminal: mkdir -p specs && touch specs/mission.md specs/tech-stack.md specs/roadmap.md
- Prompt for Qwen Code:
You are helping me work with SDD.
Do not write code yet.
Read @README.md and look at the repository structure.
Propose an initial specs/ catalog:
- mission.md
- tech-stack.md
- roadmap.md
Before writing files, ask exactly three grouped questions:
1. Mission and audience
2. Technology stack and constraints
3. Roadmap and first phase- Verify that the agent actually asks questions rather than creating files with template data.
Complexity: beginner
Name: Specification diagnostics via /clear
Problem: You have a partially filled specification for a feedback form feature. Write a sequence of actions to check whether the specification is sufficient for implementation after /clear. Formulate a prompt that the agent should execute after clearing context. Describe how to interpret three possible outcomes: (a) agent implements without questions, (b) agent asks reasonable clarifications, (c) agent starts guessing.
Solution: 1. Ensure specification files contain: requirements.md (feature boundaries), plan.md (task groups with priorities), validation.md (acceptance criteria).
- Execute /clear in the Qwen Code chat.
- Prompt:
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 listing changed files.- Interpretation of results:
- (a) Successful implementation without questions → specification is sufficient, knowledge is in files
- (b) Reasonable clarifications (e.g., "what email validation format?") → normal, clarify and add to requirements.md
- (c) Guessing (e.g., "I will assume the form submits to API /api/feedback") → specification is incomplete, requirements.md needs refinement with explicit decisions
Complexity: intermediate
Name: Separating modes in one session
Problem: You discover that in a previous long session with the agent, product discussion, code writing, and verification got mixed together. As a result, the agent proposed changes beyond the feature scope, and some checks were skipped. Design a strategy to separate into four distinct sessions with explicit requests for each mode. For implementation mode, additionally break down into three phases of the Plan — Implement — Verify loop.
Solution: Session 1 — Interview mode:
Mode: interview. Help me complete the feature specification @specs/2026-05-10-feedback-form/.
Read requirements.md and ask clarifying questions about undefined boundaries.
Do not propose code, do not write an implementation plan.Session 2 — Implementation mode, Plan phase:
Mode: implementation, Plan phase.
Read @specs/2026-05-10-feedback-form/plan.md.
List what you intend to do for task group 2, which files you will touch, which checks you will run.
Do not write code, do not change files.Session 3 — Implementation mode, Implement phase:
Mode: implementation, Implement phase.
Plan approved: [insert approved plan from previous session].
Execute only this plan. If a new idea arises — stop and propose a separate task group.Session 4 — Verification mode:
Mode: verification.
Read @specs/2026-05-10-feedback-form/validation.md.
Compare current code in the branch with validation criteria.
List: what passed, what failed, what was not checked.
Do not edit code, only report.Complexity: intermediate
Name: Selecting specification mode
Problem: For three scenarios, select and justify the appropriate specification mode (Requirements-First, Design-First, Bugfix), describe the structure of created documents and differences from the default template:
Scenario A: Need to add a patient reviews page — new functionality for AgentClinic. Scenario B: Need to migrate database from SQLite to PostgreSQL without data loss. Scenario C: User reports that the feedback form sends empty messages when JavaScript is disabled.
Solution: Scenario A — Requirements-First:
- Standard structure: requirements.md (what is displayed, filters, moderation), plan.md (layout, API, integration), validation.md (display tests, XSS protection)
- No differences from template — classic new feature
Scenario B — Design-First:
- First create design.md or extended plan.md: migration schema, switching strategy (parallel usage, blue-green), rollback plan
- Then requirements.md: compatibility of existing queries, downtime constraints, data integrity criteria
- validation.md: test data migration checks, performance tests
- Difference: requirements are secondary, main risk is "how", not "what"
Scenario C — Bugfix:
- Adapted structure: reproduction.md (reproduction steps: disable JS, submit form), expected.md (expected: server-side validation, error), invariant.md (what must not change: successful submission with JS enabled, styling)
- plan.md: minimal changes, server-side validation
- validation.md: tests with JS disabled, regression tests for normal scenario
- Difference: focus on preservation, not addition; explicit specification of what must remain unchanged
Complexity: advanced
Case studies: Name: AgentClinic: from chaotic prompts to a reproducible process
Scenario: A team of three developers was creating an MVP for a medical appointment platform (AgentClinic). The first two weeks with Qwen Code passed in "stream of consciousness" mode: long sessions where requirements were discussed, code was written immediately, sometimes verification was done. The result — branches contained changes unrelated to the declared feature; specifications were scattered notes in Notion; a new developer could not reproduce the agent's work when restarting a session.
Challenge: 1. Chat context "blurred" between phases — the agent pulled product discussion into code and vice versa
- Lack of explicit validation led to merging branches with unverified scenarios
- Knowledge lived in different developers' chat histories, not in the repository
- Re-planning happened implicitly — architectural decisions changed without updating the constitution
Solution: The team implemented the SDD process from Part 3:
- Created constitution: mission.md (platform for independent doctors, audience — patients 35-65 years old), tech-stack.md (Hono, Drizzle ORM, SQLite → PostgreSQL in Q3), roadmap.md (4 phases: prototype, MVP, Telegram integration, mobile version)
- For each feature — separate folder specs/YYYY-MM-DD-name/ with three files
- Introduced rule: each phase — separate Git branch, named according to plan
- Used /clear as a mandatory step before implementation
- Separated sessions into four modes with explicit markers at the start of the prompt
- Implemented Plan — Implement — Verify loop with prohibition on plan extension during implementation
Result: After three weeks: new developer onboarding time reduced from 2 days to 2 hours; percentage of branches requiring rework after code review dropped from 60% to 15%; agent after /clear successfully implemented 80% of features without guessing; architectural decisions became traceable — when switching stack from Hono to FastAPI, updating tech-stack.md was automatically picked up in all new sessions.
Lessons learned: Knowledge in files outweighs chat convenience — short-term documentation costs pay off in reproducibility
Rigid boundaries between agent work modes prevent context "pollution" better than "be careful" instructions
/clear command is not a technical detail but an organizational metric of specification maturity
Re-planning must be a visible act: updating constitution with changelog entry, not implicit adjustment in conversation
Related concepts: Three-layer SDD architecture
Four agent work modes
Plan — Implement — Verify loop
/clear command as diagnostics
Name: API migration: when Design-First saves from technical debt
Scenario: Within AgentClinic, the public API needed to be changed for integration with an external electronic appointment system. Requirements were formally clear (new endpoints for appointment slots), but there was a risk of breaking contracts used by a partner's mobile app in development.
Challenge: 1. Classic Requirements-First template would lead to detailed "what" description without working out "how to maintain backward compatibility"
- Incorrect migration threatened refusal of partner app at a stage when own mobile app was not yet ready
- Need for API versioning was not obvious until implementation options were analyzed
Solution: The team applied Design-First mode:
- First created design.md with three options: URL-versioning (/v1/, /v2/), header-based versioning, and deprecate strategy
- Comparative analysis: URL-versioning — simplicity for partner, but route pollution; header-based — cleanliness, but documentation complexity; deprecate — minimum code, but risk of sudden failure
- Selected hybrid: /v2/ for new endpoints, X-API-Version header for future changes, 6-month deprecate on /v1/
- Only after fixing design.md were requirements.md written with explicit compatibility constraints and validation.md with contract tests
Result: Partner app migrated in 2 weeks without incidents; own mobile app used /v2/ from day one; on subsequent response format change, the team reused Design-First, reducing architectural decision time from 3 days to 4 hours.
Lessons learned: Design-First applies when the main risk is implementation approach, not requirement uncertainty
Conscious choice between options in design.md creates an audit trail for future architectural decisions
Deferred requirements.md writing does not speed up the process but improves final quality
Validation for Design-First must include tests not only for new code but also for regression of existing contracts
Related concepts: Three specification modes
Project constitution (tech-stack.md)
Role of branches as cognitive boundaries
Plan — Implement — Verify loop
Study tips: Visualize the process: draw the three-layer architecture on paper for your current or imaginary project, marking which decisions at each level are already made and which still vary
Practice /clear mentally: before sending a prompt to the agent, imagine that chat context disappears — is there enough information in the specs/ files to continue work?
Create prompt templates for four modes as snippets in your editor or clipboard manager — this reduces the temptation to mix modes to save time
Keep a "re-planning journal": when updating the constitution, record which work revealed inaccuracies in old decisions — this trains intuition about typical "friction points"
To study the Plan — Implement — Verify loop, use role-play: you are the agent, a colleague or imaginary "controller" checks whether you mixed phases in the response
Test your specifications for "guessing": ask a colleague or another AI model to read only specs/ and describe what it ASSUMES about unwritten details — matches with your intentions = good specification
Start with Bugfix mode for simple tasks: it is shorter and teaches focus on "what must not change" — a skill useful in all modes
Additional resources: Original SDD course (parts 1-2): Preceding materials for context understanding — recommended to complete before in-depth study of Part 3
Qwen Code documentation: https://github.com/QwenLM/Qwen2.5-Coder — official guide for working with the agent, including /clear commands and @-references
Git branching strategy (git flow / github flow): Comparison of branching strategies to understand why SDD proposes phase-based rather than developer-based branches
"Writing Great Specifications" by Kamil Nicieja: Book about specifications in BDD — analogies with Gherkin approach help understand why validation.md is separated from requirements.md
RFC processes in open source (Python PEP, Rust RFC): Examples of Design-First in large projects — how tech-stack.md scales to community architectural decisions
Practice: AgentClinic template repository: Fork the study project and complete all practical exercises from the guide in a real environment
Summary: Part 3 presents SDD as a three-layer process where knowledge is deliberately "frozen" in constitution and specification files rather than blurred in chat history. Key practices: isolated Git branches by phase, diagnostics via /clear, clear separation of four agent work modes, Plan — Implement — Verify loop with prohibition on plan extension during implementation, and flexible choice between three specification modes. Mastering these practices transitions work with AI agents from "magic" mode to engineering discipline with reproducible results.