Glossary

A consolidated list of terms from the textbook. Used as a reference in any part — definitions are duplicated here to avoid inconsistencies in the text.

SDD Artifacts

Project Constitution — three files in specs/ that capture long-term decisions: mission.md (why and for whom), tech-stack.md (how), roadmap.md (what and in what order). Changed only during the replanning phase.

**mission.md** — purpose, audience, tone, definition of success.

**tech-stack.md** — language, environment, framework, database, testing, constraints. If a decision is not recorded here, it may be assumed by the agent.

**roadmap.md** — ordered phases with statuses. Each phase is a candidate for a separate feature branch.

Feature Specification — a folder specs/YYYY-MM-DD-feature-name/ with three files:

• **requirements.md** — boundaries, what is out of scope, decisions specific to this feature, context.
• **plan.md** — numbered groups of tasks for implementation.
• **validation.md** — a set of facts and readiness criteria (see below).

**QWEN.md** — permanent context for Qwen Code: rules of agent behavior in this repository.

**AGENTS.md** — a general contract for any AI agent. Qwen Code reads both files if they are present.

**CHANGELOG.md (project)** — a changelog of the learning project. Updated by the changelog skill before merging.

Bugfix Specification — a folder specs/YYYY-MM-DD-bugfix-name/ with files bugfix.md, plan.md, validation.md. Used instead of a regular feature specification when the task is to fix existing behavior rather than add new functionality. In bugfix.md, the sections "Current Behavior", "Expected Behavior", "Proof of Root Cause", "What Must Not Change", and "Regression Scenarios" are mandatory. In validation.md, a repro fact is mandatory: a command or scenario that fails before the fix and passes after. More details in Part 11.

Negative Requirements — a section of the specification describing what must not change when implementing a feature or fix: which routes, contracts, behaviors, and data remain unchanged. In a regular feature, this is the "Out of Scope" section; in a bugfix specification, it is "What Must Not Change". Protects against "improvements along the way" that the agent can easily introduce if the boundary is not written down.

Fact Lifecycle

Fact — an executable or unambiguously verifiable statement that can yield a clear "pass / fail" verdict. By command, test, HTTP status, or database invariant.

Fact Levels in validation.md:

• Example — a specific input-output pair.
• Invariant — something that is always true (after an action, in any database state, etc.).
• Property — checks a class of cases.
• Contract — a formal binding "given condition X, action Y leads to Z".

Fact Statuses:

• draft — proposed but not yet accepted.
• spec — accepted as mandatory for the feature.
• implemented — there is a test, command, or manual confirmation.
• deferred — consciously postponed to a future phase.

Proof Package — a set of artifacts attached to a merge request and confirming that the branch is ready: a link to the feature specification, marks of completed automated checks from validation.md, a log of manual checks, and if necessary — screenshots, request dumps, log excerpts. Not a separate file, but a structure of the merge request comment. Removes from the reviewer the burden of reproducing the entire scenario from scratch. More details in Part 9.

Processes

Replanning — a separate branch between features, in which mission.md, tech-stack.md, roadmap.md, testing policy, and changelog are updated. Does not implement product features.

MVP Phase — assemble a minimally viable version from several phases at once. A stress test of specification maturity; riskier than a regular feature.

AI Fatigue (previously encountered as a calque from AI fatigue) — human exhaustion from the volume of changes that the agent produces faster than the human can verify. SDD reduces it through small phases, explicit boundaries, and fact-checking.

Drift — divergence of implementation from specification. Occurs in code, in facts, and in the specification itself (when project rules have changed but the feature has not).

Escalation Rules — a list recorded in QWEN.md or in a skill of situations in which the agent must stop and return control to the human: ambiguous requirements, missing required fact in validation.md, conflict with specs/tech-stack.md, need for a destructive command, new dependency. Without these rules, the agent tends to silently make decisions that later have to be rolled back. More details in Part 14.

SDD Maturity Scale — a short descriptive scale of a team's process state, from 0 ("vibe coding") to 4 ("learnable process"). Does not claim to be canonical; used as a mirror to notice which step will give the most benefit now. The goal of the textbook is to bring the team to level 2 on a didactic project. More details in Part 21.

Qwen Code Tools

Skill — a directory with SKILL.md describing when and how the agent should apply a specific process. Personal (~/.qwen/skills/) or project-level (.qwen/skills/).

Hook — a shell command that Qwen Code executes when an event occurs (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, etc.). Useful for logging, adding context, guarding boundaries.

MCP — Model Context Protocol; an external layer of tools and data sources connected to the agent via mcpServers in settings.json or qwen mcp add.

ACP — Agent Client Protocol; a communication protocol between the agent and the IDE/client. Used, for example, when working with Qwen Code from JetBrains.

Headless Mode — qwen -p "..."; launches the agent without an interactive session, for automation and CI.

Context Rot — an observed degradation in model response quality as input grows: on long irrelevant context, relevant pieces are found worse than on short focused context. Practical consequences in the textbook: /clear between roles, injecting only relevant memory entries into QWEN.md, limiting the length of injected context. More details in Part 14 and Part 19.

External SDD Frameworks

GitHub Spec Kit — an open framework with a standard cycle /constitution → /specify → /clarify → /plan → /tasks → /analyze → /implement.

AWS Kiro — an IDE with its own SDD model: specs (requirements.md + design.md + tasks.md), steering files, agent hooks.

The correspondence of the textbook with Spec Kit and Kiro is in Appendix A.

Antipatterns (see Part 20)

• Specification after code — the artifact is written for reporting, not for control.
• **Giant requirements.md** — a 50-item specification that no one runs.
• **validation.md that no one ran** — facts are theoretical.
• Weakening facts after an error — rewriting a fact instead of fixing the code.
• **Ritual /clear** — clearing context without understanding what it actually does.
• Skill as a magic button — the team invokes a skill without reading SKILL.md.
• **QWEN.md as a dump** — turns into an unreadable canvas, the agent stops following the main thing.
• Hook that silently changes the project — without logging, without human feedback.
• Memory as a hidden source of truth — mandatory rules live only in SQLite, not in specifications.

• MCP without a task — connected just because it's possible.
• Too big an MVP — without specification maturity.