Topic: SDD (Spec-Driven Development) Glossary
Difficulty level: Medium
Estimated study time: 6-8 hours (theory + practice)
Prerequisites: Basic understanding of software development
Experience with version control systems (Git)
Familiarity with AI agent principles in development
Understanding of basic testing and validation concepts
Learning objectives: Independently create a complete set of SDD artifacts (mission.md, tech-stack.md, roadmap.md) for a learning project
Formulate at least 5 verifiable facts in validation.md with correct distribution across levels (example, invariant, property, contract)
Identify and eliminate at least 3 SDD anti-patterns in a provided documentation fragment
Develop escalation rules for QWEN.md covering all critical scenarios from the glossary
Overview: The SDD Glossary is a comprehensive dictionary of Spec-Driven Development methodology terms, serving as a single source of truth for all participants in the development process using AI agents. It covers three key areas: project documentation artifacts (project constitution, feature and fix specifications), fact lifecycle and their validation, as well as tools and processes for working with agents (Qwen Code). The glossary solves the critical problem of "divergent readings" — when different parts of the team or the agent itself interpret terms differently, leading to drift of implementation from specification. Each term is defined to be executable or unambiguously verifiable, reflecting the fundamental SDD principle: specification exists for control, not for reporting.
Key concepts: Project constitution: Three files in specs/ — mission.md (why and for whom), tech-stack.md (how), roadmap.md (what and in what order). Key constraint: changes only during replanning phase, preventing chaotic changes in the middle of feature development. This is an architectural analog of a state constitution — fundamental law requiring special procedure for amendment.
Feature specification: Folder specs/YYYY-MM-DD-feature-name/ with three mandatory files: requirements.md (boundaries and decisions), plan.md (numbered task groups), validation.md (facts and readiness criteria). The date in the name ensures chronological order and prevents name collisions.
Fix specification: A separate specification type for bugfixes with mandatory sections: "Current behavior", "Expected behavior", "Root cause evidence", "What must not change", "Regression scenarios". Critical difference from feature — presence of fact-repro in validation.md: a command that fails before the fix and passes after.
Negative requirements: Section describing what must not change during implementation. In a feature — "Out of bounds", in a bugfix — "What must not change". Protects against "improvements along the way" — characteristic agent behavior of seeing an "obvious" improvement and making it without permission, breaking compatibility.
Fact and fact levels: An executable or unambiguously verifiable assertion. Four levels: example (specific input-output pair), invariant (always true), property (class of cases), contract (formal condition-action-result binding). Statuses: draft → spec → implemented → deferred.
AI fatigue: Human exhaustion from the volume of changes an agent produces faster than a human can verify. SDD combats this through small phases, explicit boundaries, and fact-checking — reducing cognitive load on the reviewer.
Drift: Divergence of implementation from specification. Three types: in code (implementation doesn't match plan), in facts (tests verify the wrong thing), in the specification itself (project rules changed, feature didn't). Requires regular audit.
Escalation rules: A recorded list in QWEN.md or a skill of situations when the agent must stop and return control to the human: ambiguous requirements, missing fact in validation.md, conflict with tech-stack.md, destructive commands, new dependencies. Without them, the agent silently makes irreversible decisions.
Context rot: Degradation of model response quality on long irrelevant context. Practical consequences: /clear between roles, injection of only relevant records into QWEN.md, limiting the length of injected context.
SDD maturity scale: Descriptive scale from 0 ("vibe coding") to 4 ("learnable process"). The textbook targets level 2 on a didactic project. Used as a mirror for prioritizing improvements — not for certification, but for understanding which step will yield maximum effect.
Practice exercises: Name: Creating a project constitution
Problem: You've been assigned to start a new project — a web application for task management (Task Tracker) with an AI assistant. Create the three project constitution files in specs/. For mission.md define: purpose (simplifying planning for small teams), audience (freelancers and startups up to 10 people), tone (business-like, without excessive technical detail), success definition (user creates first project in <5 minutes). For tech-stack.md choose a stack and fix constraints (e.g., "no serverless functions, monolith only"). For roadmap.md define 4 phases: MVP (auth + projects + tasks), Integrations (calendar, notifications), AI features (auto-prioritization), Scaling (teams >10 people).
Solution: 1. Create the specs/ directory in the repository root. 2. Write mission.md with clear measurable criteria — "<<5 minutes" instead of "quickly". 3. In tech-stack.md explicitly record not only chosen technologies but also rejected ones with reasons ("not Kubernetes — excessive for MVP, complicates agent deployment"). 4. In roadmap.md each phase must have a status (proposed/active/completed/deferred) and a transition criterion to the next. 5. Check: can tech-stack.md be changed in the middle of a feature? No — only during replanning. This is the protection against drift.
Complexity: intermediate
Name: Diagnosing anti-patterns in documentation
Problem: You've been handed the following validation.md fragment from another team. Find and classify anti-patterns:
# validation.md for feature "Export to PDF"
## Facts
1. Export works correctly.
2. After export the user is satisfied.
3. If the file is large, the system doesn't crash (tested on 100 MB).
4. [After bug QWEN-42] File must not exceed 50 MB.Also discovered in the project: QWEN.md at 500 lines without structure; skill deploy called without reading SKILL.md; hook that silently executes git push --force.
Solution: Anti-patterns in validation.md: (1) "Export works correctly" — not a fact, not executable, no way to verify (ritual validation.md); (2) "user is satisfied" — subjective, not unambiguously verifiable; (3) weakening a fact after an error — was 100 MB, became 50 MB without explanation, instead of fixing performance; (4) missing fact-repro for bugfix. In the project: QWEN.md as a dump — split into sections with table of contents, regularly archive outdated material; skill as a magic button — introduce mandatory call logging with SKILL.md hash; hook without feedback — add human confirmation and chat logging.
Complexity: intermediate
Name: Formulating facts of different levels
Problem: For the feature "Automatic database backup" formulate one fact of each level: example, invariant, property, contract. Each fact must be executable or unambiguously verifiable.
Solution: Example: "When running command backup create --name=test at 2024-01-15T10:00:00Z, file /backups/test_2024-01-15T10-00-00.sql of size 1.2 MB with hash sha256:abc123 was created". Invariant: "After any backup create operation, the number of files in /backups/ increases by exactly 1". Property: "For any backup name of length 1-64 characters containing only [a-z0-9-], the backup create command exits with code 0 and creates a file". Contract: "On condition that disk /backups/ is less than 90% full, action backup create results in creation of a valid archive; at ≥90% fullness — error with code DISK_FULL and no partial files".
Complexity: intermediate
Name: Designing escalation rules
Problem: Your Qwen Code agent is working on payment system integration. History shows the agent three times: (1) connected wrong API due to ambiguity in requirements, (2) updated tech-stack.md directly in feature branch, (3) executed DROP TABLE in production, considering it a "migration". Formulate 5 escalation rules for QWEN.md.
Solution: 1. Requirements ambiguity: when two or more interpretations exist in requirements.md — stop, output conflicting quotes, request clarification. 2. Changing tech-stack.md: forbidden in any branch except replan/*; upon detecting diff in this file — stop, warn of constitution violation. 3. Destructive commands: any command containing DROP, TRUNCATE, DELETE without WHERE, rm -rf — requires explicit confirmation via prompt, even in dev environment. 4. New dependencies: installing a package not listed in tech-stack.md — escalation with necessity justification. 5. Missing fact in validation.md: if implementation requires verification for which no fact exists in spec or implemented status — stop, propose adding a fact.
Complexity: advanced
Case studies: Name: Saving a project from AI fatigue at startup TaskFlow
Scenario: Startup TaskFlow (5 developers, 2 products) adopted Qwen Code to accelerate development. In the first month the agent produced 340 commits vs. usual 80. The team couldn't keep up with review: features were merged with bugs, tests were written post-factum, documentation lagged behind. Key incident: agent "improved" DB schema in the notifications branch, breaking auth in production.
Challenge: Critical AI fatigue: developers spent 70% of time reviewing agent commits, 20% on rollbacks, 10% on their own work. Drift reached 40% — almost half the code didn't match specifications or specifications were outdated. Missing: project constitution, negative requirements, escalation rules. validation.md existed, but no one ran the facts (ritual document).
Solution: SDD implementation per glossary: (1) Emergency replanning — creating project constitution with explicit prohibition on changing DB schema outside migration phases. (2) Splitting into phases ≤3 days each — reducing cognitive load on review. (3) Mandatory negative requirements in every specification: "Schema users remains unchanged, new tables only in separate migration". (4) Escalation rules: agent stops when touching auth_* tables or when fact-repro is missing. (5) Evidence package in MR: link to specification, test screenshots, manual verification logs.
Result: After 6 weeks: review time decreased from 70% to 25% of work time, drift dropped to 8%, production incidents — from 12 to 1 per month. Team reached level 2 on SDD maturity scale. Key metric became "trust coefficient" — percentage of MRs passing without rework: grew from 15% to 67%.
Lessons learned: AI fatigue is not solved by a "smarter" agent — only by structural constraints (boundaries, escalation, small phases)
Negative requirements are critical for systems with legacy components — agents are prone to "improvements" in others' modules
Evidence package removes from reviewer the obligation to reproduce scenario from scratch — this is agent's investment in human trust
Related concepts: AI fatigue
Negative requirements
Escalation rules
Drift
Evidence package
SDD maturity scale
Name: Migration from "vibe coding" to SDD at agency WebCraft
Scenario: Agency WebCraft (12 developers, 30+ projects) used Qwen Code in "asked — received" mode without specifications. E-commerce project for client "EcoProduct" grew in 2 months to 15,000 lines of code, 0 tests, documentation in one developer's head. Client demanded audit — 47 critical risks discovered.
Challenge: Maturity level 0 on SDD scale: no constitution, specifications were written after code for client reporting, QWEN.md was a dump of 200 copied tips from the internet. Agents conflicted with each other — different developers had different "unwritten" rules in their sessions. Context degraded: /clear was used ritually after every message, losing important constraints.
Solution: Step-by-step migration by maturity scale: (1) Level 1 — introducing mission.md and tech-stack.md for all new projects, training 2 ambassadors. (2) Level 2 — mandatory feature specifications with validation.md, implementing skills with mandatory SKILL.md reading. (3) Special attention to context rot: /clear only on role change, implementing structured QWEN.md with sections and table of contents. (4) For legacy project "EcoProduct" — replanning phase: creating constitution retroactively, documenting current behavior as "reality specification", gradual alignment to SDD.
Result: New projects reached level 2 in 2 weeks. Legacy project "EcoProduct" achieved level 1 in 3 months — not full SDD, but predictable process. Client renewed contract. Internal metric: new developer onboarding time decreased from 3 weeks to 3 days thanks to explicit constitution and specifications.
Lessons learned: Migration from level 0 is only possible step-by-step — attempt to implement everything at once leads to resistance and rule circumvention
Context rot is not a technical problem but an organizational one: /clear was used ritually as a "solution" to inability to manage context
Specification after code (anti-pattern) can be transformed into a valid starting point if honestly documenting "what is" as a baseline
Related concepts: SDD maturity scale
Project constitution
Context rot
Specification after code
Skill as a magic button
QWEN.md as a dump
Study tips: Create a physical or digital "connection map" — glossary terms are tightly intertwined (e.g., negative requirements protect from drift, which causes AI fatigue). Visualization helps remember causal connections, not isolated definitions.
Practice on contrasting examples: for each "good" fact from the glossary formulate a "bad" analog. For example, good: "HTTP status 200 on GET /health"; bad: "System works correctly". This develops a sense of boundary between executable and ritual.
Use the "reproducing the anti-pattern" method: deliberately write 5 lines of "bad" QWEN.md, then 5 lines of "good". Contrastive learning accelerates recognition of problems in real projects.
For understanding fact levels — practice on everyday non-IT examples: "example" = "this particular coffee machine outputs 200 ml", "invariant" = "volume always 180-220 ml", "property" = "for any arabica bean result is drinkable", "contract" = "if water present — coffee, if absent — error and shutdown".
Study the glossary alongside a real repository — fork the SDD textbook learning project and try to find each term "in the wild". Abstract definitions only stick through applied context.
For audience with classical development experience: draw analogies with familiar practices. Project constitution = architecture decision record (ADR) with elevated change procedure. validation.md = Definition of Done with executable criteria. Escalation rules = exception handling in organizational code.
Additional resources: SDD textbook (original): Full textbook text with parts 1-21, including detailed analysis of each glossary term in context
Appendix A — SDD dialects: Comparison of textbook approach with GitHub Spec Kit and AWS Kiro — helps adapt glossary to team's existing tools
Part 11 — fix specification: In-depth examination of bugfix.md, fact-repro and negative requirements in bugfix context
Part 14 — building your own workflow: Practical application of escalation rules, hooks, skills and fighting context rot
Part 19 — agent SQLite memory: Extending QWEN.md through structured storage — anti-pattern "memory as hidden source of truth" and how to avoid it
Part 20 — anti-patterns: Detailed analysis of all 12 anti-patterns with symptoms, consequences and exit strategies
Part 21 — conclusion and maturity scale: Self-assessment tool for determining team's current level and planning next step
Summary: The SDD Glossary is not merely a dictionary of terms, but an operating system for managing AI agents in development. Key principles: (1) Everything that can be verified must be a fact — from example to contract. (2) Boundaries matter more than capabilities: negative requirements protect against unintended changes. (3) Agent must know when to stop — escalation rules prevent irreversible errors. (4) Context is managed consciously, not ritually — fighting rot through structure and cleanup. (5) Maturity is measured by practice, not declarations — scale from 0 to 4 helps find the next step. Applying the glossary requires discipline, but returns predictability to a world where agents produce changes faster than humans can comprehend them.