14KB
Spec Driven Development — Chapter-26: Canonical Glossary
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 489–504
- Pages without text: none
Canonical Glossary The single source for the technical terms in this material. Each term appears here once, with the translation and the plain explanation used in the text. The chapters explain each term on its first appearance and reuse this spelling without renaming it. When you introduce a new term, record it here. Convention: the “Ch.” column shows which chapter the term entered the material in. Terms Term Ch. Definition SDD (Spec Driven Development) 0 Development guided by a specification: describing what you want before asking for the code. Vibe-coding 0 Programming on improvisation, on vibes, asking the AI with no method and no clear specification, hoping the result will do. Token 0 The unit of text (a chunk of a word) that the AI reads, generates, and bills for.
Context 0 The window of text resent to the AI on every interaction, where everything it knows about the task has to fit, since it keeps no memory of its own between requests. Waterfall 0 A model that specifies everything up front and only then builds, in sequential phases that flow down like a waterfall. Agile 0 An approach that delivers in short cycles, with frequent feedback, adjusting course at each step instead of betting everything on a fixed plan. FOCUS Architecture 0b The second volume in the trilogy, on where each rule lives and why dependencies point inward. The acronym opens up into Feature- Oriented, Clean, Unidirectional and Scalable. Context Engineering 0b The third volume in the trilogy, on what the agent sees right now, in this call's window, and at what cost. Cross-reference 0b The way this book cites a sibling volume: the name, the link, and what you need to
know summed up in the sentence itself, with no outside reading required. Scrum 1 An agile approach based on short cycles (sprints) with defined roles and events and frequent feedback. Iterative/incremental 1 Building in short cycles, delivering and adjusting little by little, instead of all at once at the end. Agile Manifesto 1 A 2001 document that set four values for developing software, with a focus on people, working software, collaboration, and responding to change. Sprint 1 A short, fixed-length cycle (usually 1 to 4 weeks) at the end of which something is ready to show and evaluate. Work in progress / WIP 1 What has been started and not yet finished; limiting it keeps you from starting a lot and finishing little. Continuous integration 1 Merging and testing everyone's work frequently, instead of waiting for the end, so that errors surface early.
TDD (Test-Driven Development) 1 Writing the test before the code, so the code is born already proving it does what it should. Extreme programming (XP) 1 Kent Beck's agile approach that takes good practices to the extreme: testing first, integrating constantly, and reviewing code continuously. Kanban 1 A method that visualizes work on a board and limits work in progress to improve the delivery flow. The specify → plan → tasks → implement cycle 1 This material's vocabulary for the stages of SDD: specify, plan, break into tasks, and build. Requirement 2 A testable statement of what the solution needs to do or respect. Scope 2 The boundary of what is in and what is out of a solution. MVP (minimum viable product) 2 The smallest version of the solution that already solves the core problem end to end and can be put in someone's hands. Non-goal 2 What you explicitly declare to be off target, to contain expectations and keep the AI
from inventing beyond what was asked. Acceptance criterion 2 What counts as done and correct; the verifiable condition that decides whether a requirement was met. (Synonym cited once: acceptance criteria.) Scenario / user story 2 A short description of a usage situation, from the point of view of the person using it, of what happens and the expected result. Edge case 2 A rare or extreme situation (empty, limit, error) that the solution still has to handle well. Assumption / premise 2 Something taken as true without being guaranteed, which, if it changes, changes the solution. Ambiguity 2 A passage that allows more than one reasonable interpretation; what a good spec reduces. Living artifact 2 A document made to be revised and rerun cheaply, not frozen like a contract.
Functional specification 2b The one that describes observable behavior, in the vocabulary of the problem; it stays true when the technology changes. Technical specification 2b The one that describes construction, in the vocabulary of the solution: layers, interfaces, data structures. It dies along with the stack choice, and its place is the plan . EARS (Easy Approach to Requirements Syntax) 2b A grammar born in aeronautical engineering that forces every requirement into one of five shapes (ubiquitous, event-driven, state-driven, unwanted behavior, and optional), so the triggering condition is never left implicit. MUST / MUST NOT / SHOULD 2b The vocabulary of obligation inherited from the RFCs: MUST is what the system has to do, MUST NOT what it may never do, SHOULD is a recommendation. Given/When/Then 2b A scenario format in three parts: the state of the world before, the single gesture that triggers the behavior, and what became true afterwards.
BDD (Behaviour- Driven Development) 2b A practice formulated by Dan North out of teaching TDD, which writes behavior in sentences a non-programmer can disagree with and a test tool can run. Design by Contract 2b Bertrand Meyer's idea of treating every operation as a contract between caller and executor, with a precondition, a postcondition, and an invariant. Precondition 2b What has to be true for the operation to be callable; the caller's responsibility. Postcondition 2b What the operation guarantees will be true when it finishes well; the executor's responsibility. Invariant 2b What is true before and after the operation, always, and which it has no license to break. ATDD (Acceptance Test-Driven Development) 2b Writing the acceptance test before building, together with whoever asked for the feature, and using it as the definition of done. Capability (the unit of a spec) 2c What the user can exercise from start to finish and you
can review whole before approving; the measure of how much fits in one specification. Cut by layer 2c Splitting a big feature into one spec for the database, another for the logic, another for the screen. Each part passes the size test and none of them delivers any capability. Cut by complete path 2c Splitting by pulling out of the whole capability the leanest version that still crosses every layer, and fattening it up in the specs that follow. CLI (command-line interface) 3 A way of driving a program by typing instructions in the terminal, instead of clicking buttons. constitution 3 In spec-kit, the set of principles that govern the project; the first step of the flow, before specifying. change / change proposal (OpenSpec) 3 OpenSpec's unit of work: a package that describes a change (the why, specs, tasks) before applying it. Spec delta 3 The part that changes in a proposal, merged into the living specification when the
change is archived. Scaffolding 3 The initial structure of files and folders that a tool creates when it initializes a project. Agent persona (BMAD) 3 A specialized role (analyst, architect, developer) that the AI agent takes on in each phase. PRD (product requirements document) 3 A document that states what you want to build and why, before discussing architecture. Story / epic 3 Epic: a large block of work; story: a small, implementable slice of it. Stack 3 The project's set of technologies: language, database, framework. A choice for plan , not for the spec. Governance 4 The level of the general, lasting rules that sit above the day-to- day decisions and define what is acceptable across all of them. Layered architecture 4 Organizing the code into bands with distinct responsibilities (view, state/presentation, use cases, repositories) instead of everything mixed together.
Dependency direction 4 The rule for who is allowed to know whom across the layers: dependencies point inward, and the inner layers ignore the outer ones. State/presentation layer 4 The band that holds the screen's state and reflects what it should show, between the view and the use cases. Use case 4 The unit that runs one business rule of the app (for example, “complete a task”). Repository 4 The object that isolates data access: only it talks to the database or the network, and no one else. Dependency inversion / injection 4 Instead of one layer creating another, it receives what it needs ready-made, which makes it testable and swappable. Clean Architecture 4 A design that puts the business rule at the center and frameworks and details at the edge, with dependencies pointing inward. SOLID 4 Five object-oriented design principles that keep classes and modules cohesive,
decoupled, and easy to change. Error handling as a value (Result) 4 Operations that can fail return an explicit success-or-failure result, instead of throwing an exception; the caller is forced to handle it. Amendment / semantic versioning 4 The controlled change of the constitution, numbered by MAJOR.MINOR.PATCH according to its impact, always with a rationale. constitution check 4 The check, during plan , that the feature's plan respects the principles set in the constitution. branch (feature branch) 5 An isolated line of work in git where a whole feature is developed, starting from main . merge 5 Joining the work of a branch back into main , integrating the feature into the project. main 5 The repository's main, stable line, where each feature starts from and returns to. unit of work 5 The feature as the thing that is born, runs through the entire cycle, and is integrated; the granularity of the loop.
core loop 5 The minimal path of the cycle, specify → plan → tasks → implement , without the three optional checks. clarify 5 The stage that asks what stayed ambiguous in the spec and records the answers in it before planning. checklist (quality gate) 5 The stage that validates whether the spec and the plan are complete and clear before they become tasks. analyze (consistency check) 5 The stage that verifies consistency among spec, plan, and tasks before building. manual validation 5 The check made with the app open in front of you, item by item, after the automatic steps have passed; the only one that catches what was consistent and wrong. artifact (of the flow) 5 The document that each stage writes and the next one reads (spec, plan, tasks, code); what makes the context disposable. agent-context- update ( /speckit-agent- context-update ) 5 A maintenance command that runs as an automatic hook after plan (and specify ), updating the agent's context
file to point at the most recent plan. backlog 6 The queue of features the system is still going to get, named and in priority order, waiting their turn while you work on one at a time (in practice, a file like rascunho.md ). Anti-pattern (of specification) 6b A way of going wrong that repeats, with a recognizable symptom, a predictable cost, and a known fix. Rule inherited by reference 6b The anti-pattern where the requirement says to apply “the same criterion” from somewhere else instead of saying what the rule is. Undeclared initial state 6b The anti-pattern where the spec fixes every possible option and forgets to say which one holds when the person arrives. A verb with two owners 6b The anti-pattern where two specs use the same expression for different behaviors, each one right within itself. A repeated edge with no answer 6b The anti-pattern where the spec never says what happens when the operation is repeated
or lands on something that is no longer there. Scope that grows out of convenience 6b The anti-pattern where the spec absorbs the near relative of what was asked for because the addition is cheap right now. Fixing at the end of the chain 6b An anti-pattern of reflex, not of wording: the defect gets patched where it showed up and the spec goes on saying the wrong thing. assumption (by the agent) 7 The decision the agent makes on its own, during implement , when an ambiguity in the spec was left open; what clarify exists to prevent, by bringing the decision to you and early. idempotency 7 The property of an action that, applied once or many times to the same state, always gives the same result (completing what is already completed changes nothing and is not an error). tasks (executable tasks) 9 The ordered list of small, verifiable steps that tasks writes from the plan; the artifact between plan and the
code (distinct from the verb/stage of the same name). decomposition (into tasks) 9 The act of breaking the plan into small, ordered, checkable tasks, each one a step that an agent runs and confirms as done. consistency report 9 The output of analyze : a table that lists each finding (with identifier, category, severity, location, and recommendation) from cross- checking spec, plan, and tasks. artifact conflict 9 An analyze finding where two artifacts, correct on their own, assert things that do not fit together (alongside gap and excess). fix at the source 9 Fixing a conflict in the artifact where the truth originates (the spec or the plan), not in the task or the code, so the fix flows down the whole chain. implement (execution) 10 The core-loop stage that runs the tasks in tasks.md and produces the code that passes the tests, reading the versioned artifacts (spec, plan, tasks) instead of the chat history.
red-green cycle 10 The beat of TDD inside implement : write a test that fails (red), write the minimum code that makes it pass (green), and refactor with the green suite as a safety net. Precision / decision / boundary correction 10b The three sizes of change in a spec already written: the rule was right and the sentence was loose; the rule was the wrong one; or what turned up does not belong to this spec. Rules A concept MUST appear under a single name throughout the material (Principle IX). Terms already recorded here MUST be reused without renaming in later chapters. When you introduce a new term in a chapter, explain it on its first appearance and add the corresponding row to this table.