Chapter 1: The Three Layers of Truth
The Three Tiers of Architectural Knowledge
To prevent specifications from becoming an unmaintainable monolith, Spec-Driven Development organizes system knowledge into three distinct layers:
1. Intent (The Top Tier)
Intent defines the fundamental purpose, business constraints, and non-negotiable boundaries of the system.
- Why does this product exist?
- Who does it serve?
- What are the hard constraints? (For example: zero external dependencies, strict privacy boundaries, or sub-second latency ceilings.)
Intent rarely changes once established. It serves as the constitutional baseline against which all other decisions are evaluated.
2. Behavioral Specifications (The Middle Tier)
Behavioral specifications describe concrete, testable system behaviors. Each specification cites the high-level intent that justifies its existence.
- How is data ingested, validated, and transformed?
- What errors are returned under failure conditions?
- What are the exact state transitions of the workflow?
Behavioral specifications are explicit contracts. If a feature or edge case is not described in a specification, it does not exist in the system.
3. Implementing Markers (The Code Tier)
In your source code files, specific marker tags wrap the functions, structs, or routines that implement each specification:
// [Marker: userauth range-start]
func AuthenticateUser(token string) (*Session, error) {
// ...
}
// [Marker: userauth range-end]
By linking the marker tag userauth to the specification auth.user_validation, the toolchain creates an unbroken, verifiable link from high-level intent directly down to the specific lines of code.
The Closed-Loop Verification Workflow
When an engineer modifies code wrapped in a marker:
- The toolchain detects the change and flags the associated specification as drifted.
- The developer or code reviewer inspects the delta to determine whether the code introduced a defect or whether the specification itself needs updating.
- The specification and code are reconciled, and the build gate passes.
This guarantees that documentation cannot drift away from reality.
In Chapter 2 (coming soon), we will examine how to set up automated build gates and drift detection in your continuous integration pipeline.