Study guide: Part 1. Introduction

Topic: Part 1. Introduction to Specification-Driven Development (SDD)

Difficulty level: Medium

Estimated study time: 8-10 hours

Prerequisites: Basic programming skills in JavaScript or TypeScript

Understanding of terminal and command line principles

Initial experience with version control systems (git)

Understanding of web development principles (HTML, CSS, databases)

Readiness to learn a new methodology for working with AI agents

Learning objectives: Formulate a definition of SDD and explain the fundamental differences from the traditional "vibe coding" approach with AI agents

Identify the role of the specification as the main development artifact and describe the process of creating a project constitution

Apply the SDD methodology to initialize the AgentClinic study project while complying with all structural requirements

Analyze the differences between a "bad" free-form prompt and an SDD-style prompt, creating your own examples

Assess project readiness for working with a tool-agent using a checklist of success criteria

Overview: Part 1 "Introduction" presents the fundamental concepts of the Specification-Driven Development (SDD) methodology. The study material introduces the fundamental shift in the control point of development: from chaotic interaction with AI agents in "vibe coding" mode to a structured process where the specification becomes the single source of truth. The concept of a tool-agent (using Qwen Code CLI as an example) is introduced, the distribution of responsibility between human and machine is explained, and an overview of the AgentClinic study project is provided — a satirical web application that will evolve throughout the textbook. Special attention is paid to terminological agreements, classification of statements by strength (Standard, Recommendation, Frontier), and the minimum vocabulary of key SDD concepts. The material prepares you for the practical creation of a project constitution, feature specifications, and organization of work with the agent.

Key concepts: Sdd (specification-driven development): A development methodology in which the specification is the main controlling artifact. Code is generated by the agent based on the specification, not on a free-form prompt. The human is responsible for intent, constraints, and acceptance criteria; the agent is responsible for speed, code search, and routine implementation. This approach preserves project memory across sessions and agents.

Vibe coding: An informal approach to interacting with an AI agent, in which the developer writes a short free-form prompt (for example, "make me a feedback form") and accepts the result "by feel." Characterized by rapid code generation followed by a series of fixes. Works for prototypes but scales poorly to large systems: decisions remain in the chat, architecture drifts.

Feature specification: A document containing requirements, implementation plan, and verification criteria for a single functionality. Includes requirements.md, plan.md, and validation.md files. Serves as the input file for the agent and determines the quality of the result. Created before writing code and updated after the phase is completed.

Project constitution: A set of documents defining the project's identity: mission (mission.md), technology stack (tech-stack.md), roadmap (roadmap.md), and key agreements. Loaded at the start of each session and ensures continuity of project understanding.

Qwen.md: A persistent context file for Qwen Code CLI containing project working rules. Automatically loaded at the start of an agent session. Can be located at the user or project level.

Tool-agent: A software tool (Qwen Code CLI, Claude Code, Codex CLI, Cursor, etc.) that reads specifications and generates code. In the context of the textbook, the term "agent" refers specifically to such a tool, not to the characters of the AgentClinic clinic.

Separation of responsibilities: A fundamental SDD principle: the human is responsible for formulating intent, defining constraints, validating results, and updating specifications. The agent is responsible for execution speed, code search, routine implementation, and mechanical changes. Both parties perform the work for which they are best suited.

Skill (skill.md): A repeatable instruction for the agent in a standardized format. Stored in the .qwen/skills/ directory. Example: a skill for feature specification that the agent can apply repeatedly without additional instructions.

Acceptance criteria: Specific, verifiable conditions that the implementation must meet. Defined before writing code and included in validation.md. Allow objective assessment of whether a task has been completed correctly.

Replanning: The process of updating the constitution and roadmap between features. Performed when understanding of the project changes during work. Ensures documentation remains up to date.

Validation: Confirmation that the implementation corresponds to the specification. Conducted by the human based on criteria from validation.md. Independent of the development process and is a formal confirmation of quality.

Important dates: Standard: Fixed behavior of a tool or generally accepted SDD practice. Not subject to discussion.

Recommendation: An experienced practice that works in most cases but allows reasonable exceptions.

Frontier: An approach that is being used but has not yet stabilized; results depend heavily on the specific team.

Practice exercises: Name: Analysis of differences between approaches

Problem: Read two variants of prompts to the agent: a "bad" prompt "Add a reviews page" and a "good" prompt in SDD style. Create a table comparing: (1) the number of uncertainties in each prompt, (2) risks to the project, (3) what the agent must decide independently in each case, (4) what remains in the chat after the prompt is executed.

Solution: 1. Bad prompt: creates many uncertainties — where to store data, whether ratings are needed, form, validation, navigation, tests. The agent makes all decisions independently, which may contradict the project architecture. Decisions remain in the chat and are lost when the session changes.

1. Good prompt in SDD style: contains explicit instruction to read the constitution, ask questions, create artifacts in the repository. The agent does not write code but prepares a specification. All decisions are documented and preserved.

1. Comparison table:

Complexity: intermediate

Name: Initializing the AgentClinic project

Problem: Create an empty directory for the AgentClinic study project. Initialize a git repository. Create a draft README.md with a project description including: (1) project name, (2) its purpose, (3) three groups of participants (engineering team, product team, marketing) with their wishes. Do not write code yet, do not ask Qwen Code for help.

Solution: 1. Creating directory and initializing git: mkdir agentclinic cd agentclinic git init

1. Creating draft README.md:

# AgentClinic

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

## Project participant wishes

### Engineering team

• Understandable study code in TypeScript
• Clean architecture with separation of responsibilities
• Tests and documentation present

### Product team

• Functionality: agent-patients, ailments, therapies, appointment scheduling
• Reviews and feedback
• Queue management system

### Marketing

• Memorable browser experience
• Attractive user interface
• Branded clinic aesthetic

Complexity: beginner

Name: Classification of statements

Problem: Below are statements from the textbook. Determine which are Standard, Recommendation, or Frontier: (a) QWEN.md is loaded at the start of a Qwen Code session; (b) a phase longer than two days should be split into two; (c) full automation of review through a multi-agent pipeline; (d) specification is the input file for the machine; (e) the agent can be replaced without losing project memory.

Solution: a) Standard — fixed tool behavior, confirmed by documentation.

b) Recommendation — practice based on experience. The two-day phase duration is optimal, but exceptions are possible (for example, a very small feature).

c) Frontier — the approach is in an experimental stage, results depend heavily on the specific team and context.

d) Standard — foundational definition accepted in SDD.

e) Recommendation — a goal achievable with proper organization of specifications, but not automatically guaranteed.

Complexity: intermediate

Name: Creating a success criteria checklist

Problem: Based on the "What will be considered success" section, create a 10-point checklist for checking repository readiness for working with a tool-agent. Each point must contain an action verb (exists, created, written, etc.) and be verifiable.

Solution: Repository readiness checklist:

1. There is a QWEN.md file with working rules for Qwen Code
2. The specs/ directory is created
3. There is a specs/mission.md with a project mission description
4. There is a specs/tech-stack.md with a list of technologies
5. There is a specs/roadmap.md with a development plan
6. Every major feature starts with requirements.md
7. Every feature contains plan.md with an implementation plan
8. Every feature contains validation.md with verification criteria
9. Implementation is done in a separate branch (not main/master)
10. Verification criteria are written before code
11. After the phase, the roadmap and specifications are updated
12. There is a .qwen/skills/feature-spec/SKILL.md file
13. The change log is maintained and up to date

Complexity: advanced

Name: Reworking a free-form prompt

Problem: Transform the following free-form prompt into an SDD-style prompt: "Make me a patient registration form for the AgentClinic clinic." The prompt must: (1) include an instruction to read the relevant documents, (2) contain an instruction to ask questions before working, (3) define which artifacts to create, (4) contain a prohibition on writing code at the first stage.

Solution: Prompt in SDD style:

"Start a new feature specification for the next roadmap phase: patient registration at the clinic.

First read specs/mission.md, specs/tech-stack.md, and specs/roadmap.md. Make sure you understand the project mission and current technology stack.

Then ask me questions on the following topics:

• What patient data needs to be collected (name, contacts, ailment history)?
• Is field validation needed (email format, name length)?
• Should the form support auto-save?
• What data security constraints should be considered?

After receiving answers, create the following artifacts in a new directory specs/YYYY-MM-DD-patient-registration/:

• requirements.md — functionality requirements
• plan.md — implementation plan with stage estimates
• validation.md — verification criteria

Do not write code yet. Wait for my specification approval."

Complexity: intermediate

Case studies: Name: Startup migration from "vibe coding" to SDD: CloudFlow team experience

Scenario: The CloudFlow startup team of 4 developers worked on a cloud-based project management platform. In early stages, interaction with Claude Code was built on "vibe coding": short prompts, quick fixes, minimal documentation. By the time they reached 10,000 lines of code, the team faced serious problems: the codebase became unmanageable, the agent gave contradictory advice in different sessions, and integrating a new developer took weeks.

Challenge: Main problems: (1) architectural decisions were made by the agent without documentation, (2) when changing sessions the agent did not remember the context of previous decisions, (3) refactoring one function affected 15+ related places due to inconsistency, (4) two developers received contradictory implementations of the same feature from different agent sessions.

Solution: The team conducted a three-week migration: (1) created a project constitution with mission.md, tech-stack.md, roadmap.md; (2) wrote QWEN.md with explicit working rules; (3) reworked the backlog into feature specifications; (4) implemented a rule: every feature goes through requirements → plan → validation → code stages; (5) created a SPEC.md skill to standardize the process; (6) set up CI with mandatory criteria from validation.md.

Result: After 2 months post-migration: new developer onboarding time reduced from 3 weeks to 3 days; number of bugs per release decreased by 60%; speed of adding new features increased by 30% (paradoxically, despite additional stages); ability to replace the agent without losing context confirmed when switching from Claude Code to Qwen Code.

Lessons learned: Specification is not bureaucracy but an investment in project manageability; the cost of writing a specification pays off many times over when scaling

Related concepts: SDD (specification-driven development)

Project constitution

Feature specification

Human-agent separation of responsibilities

Acceptance criteria

Study tips: Start with understanding the "why" — before diving into SDD mechanics, realize the limitations of "vibe coding" on large projects

Work with the study project hands-on: creating directories and files is much more important than theoretical understanding

Pay attention to statement labeling (Standard, Recommendation, Frontier) — this helps understand where you can experiment and where you cannot

Practice transforming free-form prompts into SDD-style prompts — this is a key skill requiring practice

Remember the minimum vocabulary: constitution, feature specification, validation, replanning, skill — without these terms, effective communication within SDD is impossible

Study the Qwen Code CLI tool before practical exercises — understanding the agent's capabilities will help you formulate better prompts

Don't try to apply SDD to an existing project right away — start with the AgentClinic study project to get a clean experience

Discuss the material with colleagues: statement classification and prompt analysis are good topics for paired review

Take notes on your understanding — writing a summary in your own words helps identify gaps in comprehension

Don't be afraid to seem "slow" at the specification stage — acceleration happens at the implementation stage when the specification has eliminated uncertainty

Additional resources: Qwen code cli documentation: Official Qwen Code CLI documentation, including QWEN.md description, operating modes, and available commands

Agentclinic repository: Study project on GitHub demonstrating the full SDD cycle from specification to implementation

Sdd methodology overview: Overview of the Specification-Driven Development methodology with examples of team applications

Skill examples (.qwen/skills/): Collection of SKILL.md files for standardizing the agent's repeatable operations

Article "from chat to artifact": Reflection on the transformation of the AI agent's role from code generator to specification executor

Summary: Part 1 "Introduction" lays the foundation for working with the SDD methodology. Key takeaway: specification is not a bureaucratic document but an input file for the machine that determines the quality of the result. SDD fundamentally differs from "vibe coding" by shifting the control point: instead of a series of "prompt — fix" iterations, a structured process is created with a project constitution, feature specifications, and clear separation of responsibilities. The human is responsible for intent, constraints, and acceptance criteria; the agent is responsible for routine implementation. The AgentClinic study project serves as a stable model for practice; after mastering the methodology, it can be replaced with any own project. The ultimate goal is a repository where the agent can be replaced without losing project memory, and specifications ensure repeatable quality.