Living Documentation, Spec-Driven Development and DDD
In development teams, documentation is often perceived as a necessary evil: something produced at the end of a project, under time pressure, and therefore destined to become obsolete quickly. Diagrams that describe systems that no longer exist, documents no one reads, decisions lost in individual memory.
In recent years, however, the growing adoption of AI agents as development assistants has brought documentation back to the center of the process. Approaches such as Spec-Driven Development require explicit, consistent, and continuously maintained specifications. For agents to work effectively, context must be made explicit: it is no longer enough to “know” how a system works — it must be readable, verifiable, and updatable.
This scenario makes it clear that documentation can no longer be a secondary artifact. It must become an active part of the project, on par with the code itself. This is where the comparison between Living Documentation and Spec-Driven Development takes shape.
What does Living Documentation mean?
The documentation problem exists since the origin of computing, but one of the most mature treatments of the topic can be found in the book “Living Documentation – Continuous Knowledge Sharing by Design” by Cyrille Martraire.
The book is not a prescriptive manual, but rather a conceptual journey. It starts from a simple and radical observation: documentation fails because it is separated from the system it is supposed to describe. It is written once, rarely updated, and quickly loses credibility. When this happens, teams stop reading it — and consequently stop maintaining it.
Living Documentation emerges as a response to this failure. According to Martraire, it is documentation that derives directly from the system and shares its lifecycle. Its key characteristics are:
- extracted from code, tests, and models;
- automatically verifiable;
- human-readable;
- fully integrated into the development flow, not a separate activity.
It is therefore not a tool, but a design and working approach. Anyone familiar with practices such as BDD or Domain-Driven Design will recognize many similarities.
The sources of Living Documentation
Martraire identifies several “sources of truth” from which documentation can emerge.
The first is code. Well-written code, with expressive names, clear types, and a coherent structure, already tells a story. In this sense, writing good code is already a form of documentation.
Next come tests as executable examples. In particular, domain tests or BDD-style tests become verifiable narratives of system behavior: they explain what the system does and why it does it.
Finally, the domain as central knowledge. The domain model, expressed through the Ubiquitous Language, is perhaps the most valuable form of documentation: it captures business rules, key concepts, and shared decisions between business and technology.
In summary, Living Documentation does not describe the system from the outside — it is a natural consequence of it. Its purpose is to:
- explain why the system is built in a certain way;
- make design decisions visible;
- preserve knowledge over time.
What is meant by Spec-Driven Development?
For many years in software development, code has been the only real source of truth. Specifications existed, but they were subordinate: requirement documents, diagrams, and design docs that all shared the same fate — becoming obsolete as soon as the code began to evolve.
In this paradigm, to understand what a system did, you had to read the code. To validate it, you had to run it. To discuss it, you had to interpret it. Code was simultaneously implementation, documentation, and truth.
This approach has a structural limitation: it makes alternative or parallel implementations difficult and concentrates all knowledge in an artifact that is not designed to be discussed at a conceptual level.
Spec-Driven Development overturns this structure. In a Spec-Driven context, specifications do not serve the code — the code serves the specifications.
The Product Requirements Document (PRD) is no longer an informal guide, but a formal source from which the implementation is generated or verified. Technical documents do not inform coding; they define it. Specifications do not describe what the system should do — they establish what it must do.
This is not an incremental improvement, but a paradigm shift: truth no longer resides in the code, but in the contract that the code is required to satisfy.
The Spec-Driven flow
The process often starts from a vague idea. Through an iterative dialogue — possibly supported by AI agents — this idea is refined into a coherent PRD, complete with acceptance criteria and edge cases.
Requirements and design stop being isolated phases and become continuous activities. Specifications are versioned, discussed, branched, and merged like any other project artifact.
From these specifications emerge implementation plans that connect requirements to technical decisions. Every architectural choice is traceable; every decision has an explicit rationale. Code generation can begin even from partial specifications, in an exploratory way, producing models, APIs, and tests directly from formal definitions.
Feedback does not stop at development: production metrics, incidents, and performance issues become inputs that update the specifications, feeding a continuous evolution loop.
Living Documentation vs Spec-Driven Development
To truly understand the difference between Living Documentation and Spec-Driven Development, it is necessary to look beyond tools and operational practices, focusing instead on a few fundamental axes: intent, timing, the role of specifications, and the relationship with the domain.
Intent: knowledge vs control
Living Documentation is designed to share and preserve the system’s real knowledge. It reduces the gap between what the system is and what people understand, making decisions, rules, and models visible.
Spec-Driven Development, on the other hand, has a normative intent: guiding development through formal specifications that act as a contract.
Timing: emergence vs prescription
Living Documentation emerges during and after development and is evolutionary by nature. Its alignment is guaranteed by automation.
Spec-Driven Development operates before implementation. Specifications precede the system and constrain its evolution, requiring discipline to remain consistent.
The role of specifications
In Living Documentation, specifications are implicit, expressed through code, tests, and models. They describe what truly exists.
In the Spec-Driven paradigm, specifications are explicit, formal, and versioned separately. They define what the system must become.
The role of tests
In Living Documentation, tests are narratives and executable examples, where readability takes precedence over completeness.
In Spec-Driven Development, tests are compliance verification tools — guardians of the contract.
Relationship with Domain-Driven Design
Living Documentation integrates naturally with DDD: the domain model is central, the Ubiquitous Language is essential, and Bounded Contexts become units of documentation.
Spec-Driven Development is more situational. It works very well at system boundaries — APIs, integrations, regulated contexts — but can be rigid in complex, exploratory domains.
A mature perspective
Living Documentation and Spec-Driven Development are not in conflict.
In modern architectures, an effective combination often includes:
- Spec-Driven Development at system boundaries (APIs, integrations, events);
- Living Documentation within Bounded Contexts, in the domain model and design decisions.
In other words:
Specifications protect the system.
Living Documentation protects knowledge.