Most specs are born dead. You write one at the start of a feature, it is accurate for about a day, and from the second commit onward it slowly stops describing the thing you are building. By the time the feature ships, the spec is a historical document about a plan you abandoned.
A living spec is the opposite bet. It is a specification designed to change when the code changes, so that at any moment it still describes the product that actually exists. That single property is what separates a contract you can trust from a file you learn to ignore.
Static specs are not wrong, they are frozen
The current generation of spec-driven tooling is good at getting a spec written. Spec Kit, for example, gives you a clean flow from a proposal to a spec to a plan to tasks. Those files make a change legible before anyone builds it, which is genuinely valuable and exactly where spec-driven development earns its reputation.
The limitation is not in the format. It is in the lifecycle. A spec produced that way is written once, at the front of the work, and then the work moves on without it. Nothing carries the spec forward as the code changes. It is a static artifact: correct at t=0, decaying from t=1.
This is not a knock on writing specs up front. Writing the contract before you build is the whole point. The problem is treating “written” as “done.” A contract that never updates becomes the source of spec drift: the code and the spec telling two different stories, both looking authoritative, one of them lying.
Static spec
- Written once
- In a folder
- Decays from t=1
- Read as stale truth
Living spec
- Updates with code
- Attached to code
- Flags when stale
- Stays a contract
What “living” means, concretely
“Living” is an easy word to wave around, so here is the concrete test. A spec is living if a change to the code can update it without a human remembering to do so as a separate task, and a change to the spec has a defined path into the code. Information flows both ways. The document is not upstream of the work; it is part of the loop.
That breaks down into three properties.
It is attached, not adjacent
A static spec lives in a folder next to the code. A living spec is connected to the code: to the files, components, and tests that implement it. When you can trace a spec statement to the code that satisfies it, you can detect the moment they diverge. A spec floating in a docs/ directory has no such anchor, which is why it drifts unnoticed. This is the same reason a portable specification has to carry its links to code and evidence, not just its prose.
It updates as a byproduct of work
The reason specs rot is that updating them is a separate chore, and separate chores lose to deadlines every time. A living spec updates as a side effect of the work that is already happening: closing a task, landing a change, recording a decision. If keeping the contract current requires a second, disciplined pass that nobody has time for, it will not stay current. This is the operating principle behind living documentation in general.
It knows when it is stale
A living spec does not have to be magically always-correct. It has to be able to tell you when it might be wrong. A spec connected to the code and to acceptance criteria that can be re-run can flag the moment reality diverges from the contract, instead of silently presenting an old green as current truth.
Why this matters more with agents
When one person wrote all the code, the spec and the mental model drifted together at the same speed, and the person could reconcile them from memory. That safety net is gone.
An agent does not hold your memory of the contract between runs. Context is lost between sessions unless something outside the chat holds it. Run several agents in parallel and each one edits against whatever context it was given, not against a shared, current contract. A static spec cannot serve as that shared contract, because by the third run it no longer matches the code. A living spec can, because it moved along with the first two runs.
Put differently: the faster code gets written, the shorter the shelf life of a frozen spec. Agents did not make living specs a nice-to-have. They made static specs expire faster.
There is a second-order effect worth naming. When agents read a stale spec as ground truth, they do not just fail to update it, they actively build against it. The wrong contract becomes an instruction. An agent that reads “three-step checkout” in a spec the code has already moved past will happily reintroduce the third step you removed last week, and report success against the criteria it found. A static spec is not a passive document that quietly goes out of date. In an agent workflow it is an active source of regressions, because every run treats it as current.
A living spec is not more documentation
The instinct, hearing all this, is to write more. Bigger specs, more detail, more sections to keep current. That is the wrong direction, and it is how spec-driven development gets a reputation for crushing overhead.
A living spec is usually smaller than a static one, not larger. It holds the parts that must survive contact with the code — intent, boundaries, acceptance criteria, the decisions behind the design — and it delegates the rest to the code and the tests, which are already the most current description of behavior you have. The goal is not a document that describes everything. It is a contract small enough to keep alive and connected enough to stay true.
If you find yourself maintaining a spec that duplicates what the code already says, you are not keeping a living spec. You are keeping a second copy of the truth that will drift from the first.
Where PaellaDoc fits
A living spec needs somewhere to live that is connected to the product and the code, not a folder that goes stale. That connection is what PaellaDoc is built to hold: a local model where the spec is attached to the repository, the tasks, and the evidence from each run, so a change to the code has a place to update the contract and a change to the contract has a path into the work. The spec stops being a document you file and starts being a part of the system that stays current because the work keeps it current.
FAQ
How is a living spec different from good documentation? Documentation describes how something works for a reader. A living spec is a contract that defines what must be true and stays connected to the code that proves it. Good living documentation and living specs share the same enemy, staleness, but a spec carries acceptance criteria and boundaries, not just explanation.
Do living specs replace tests? No. Tests verify behavior; a living spec carries the intent, boundaries, and decisions that tests cannot express. The two reinforce each other. Acceptance criteria in the spec are what the tests check against, which is how the spec knows when it has gone stale.
Can I make my existing static specs living? Partly. You can connect them to the code, trim them to what must stay current, and route updates through the work instead of a separate chore. What you cannot do is make a spec living by writing more of it. Living is about the lifecycle, not the length.