Specs Rot Too: Failure Modes and Continuous Maintenance
You have built a complete specification system: machine-readable specs, a doc testing process, mechanisms for externalizing tacit knowledge, and trust ring adjudication rules. Everything ran smoothly last month. This month, Agent output quality is starting to slip.
The reason is very likely spec rot. Code is evolving, requirements are changing, but the specs have not been updated in sync. The drift between specs and implementation keeps widening, and the Agent is working from an outdated operations manual.
Spec rot has four typical failure modes.
Staleness. The code has changed, but the spec is still on the previous version. A module's interface gained an additional parameter, but the inputs definition in the spec was not updated. Code generated by the Agent based on the old spec is missing this field, and the integration test fails. Detection signal: a PR modifies a module's code but has no associated spec update. Countermeasure: require PRs to link to the spec entries they touch. When code changes involve interfaces, data structures, or business logic, the corresponding spec must be updated in sync.
Ambiguity. Natural language is inherently polysemous. "The system should respond quickly" might mean 100ms, 1s, or 5s to different people. Ambiguity in specs may seem harmless when written, but as system complexity grows, different modules interpret the same vague description differently, leading to inconsistencies at integration time. Detection signal: the same acceptance criterion is implemented differently by two Agents. Countermeasure: use concrete values, examples, and counterexamples to eliminate ambiguity. Use structured definitions rather than natural language descriptions for critical fields.
Conflict. As the number of specs grows, contradictory descriptions may appear across different specs. Module A's spec says a certain API returns dates in ISO 8601 format; Module B's spec says the same API returns Unix timestamps. Two Agents each implement according to their own spec, and integration inevitably fails. Detection signal: data format mismatches or interface contract inconsistencies in integration tests. Countermeasure: introduce cross-module API contracts as Ring 0 level single sources of truth. Module-level specs must remain consistent with the API contract.
Surface area bloat. The scope of specs keeps expanding, with unrelated requirements and "just in case" features getting stuffed in. The Agent faithfully executes everything in the spec, including parts irrelevant to the current task. Bloated specs waste the Agent's context window space and increase the probability of information interference. Detection signal: spec entries that have not been referenced by any task for an extended period. Countermeasure: maintain a clear non_goals list and regularly clean up spec entries that are no longer relevant.
Spec maintenance is an ongoing cost. This cost is naturally absorbed by human adaptability in traditional development: the programmer knows the documentation is outdated and automatically works based on the actual situation. Agents lack this adaptability. Whatever the spec says, they execute. An outdated spec is more dangerous than no spec at all, because the instructions it gives appear authoritative while the content has already diverged from reality.
This ties back to the evolution principle of this book. After the specification system is built, the cost of maintaining it is long-term and continuous. This cost is a foundational infrastructure investment for Agent-driven development, similar to CI/CD maintenance costs: you can choose to invest and reap continuous returns, or you can choose to ignore it and then discover at some point that the reliability of the entire system has quietly collapsed.