The Locked Spec

Specifications have a shelf life of zero

Most specifications are dead on arrival. A product manager writes requirements before development starts. An engineer reads them, interprets them, builds something close enough, and ships it. The spec sits in a wiki or a ticket, never updated, slowly diverging from reality with every bug fix, edge case, and scope change that follows.

By the time the feature has been in production for six months, the original spec describes a system that no longer exists. Everyone knows this. Nobody fixes it. The spec rots, and the code becomes the only reliable record of what the software actually does.

This isn’t a discipline problem. It’s a design problem. Specifications are treated as a one-time artifact, something you produce before building and never revisit. There’s no lifecycle. No mechanism to keep them current. No way to know whether a spec still accurately describes the implementation it was written for.

What if specs had a lifecycle, one that kept them honest?

Draft, implemented, validated, locked

The lifecycle we’re proposing has four stages, and each one means something specific.

Draft. A specification starts as a draft. It describes intended behavior: what the software should do, under what conditions, with what inputs and outputs. At this stage, the spec is a hypothesis. It’s structured enough to be implementable, but it hasn’t been tested against reality yet.

Implemented. An engineer (or an AI) writes code that targets the draft spec. The implementation claims to fulfill the specification. At this point, you have two artifacts: a spec that says what should happen, and code that says what does happen. The question is whether they agree.

Validated. The implementation is tested against the specification. Not just unit tests. Validation that the behavior described in the spec is faithfully reproduced by the code. This might involve automated test generation from the spec, manual verification, or both. The point is that someone (or something) has confirmed: this code does what this spec says.

Locked. Once validated, the spec is locked. It becomes an immutable, verified contract. The spec and its implementation are bound together. The behavior described in the spec has been confirmed in production code. It’s no longer a hypothesis. It’s a fact.

Locking is the critical step. Everything before it is process. Locking is the moment where a specification becomes trustworthy.

What locking actually means

A locked spec is a statement of verified truth: this behavior has been implemented and confirmed.

That matters for several reasons.

AI can reason about it with confidence. When a spec is locked, an AI system knows that the described behavior is real. It’s not aspirational, not outdated, not a rough sketch. A locked spec for an HTTP retry policy in C# means an AI can generate a Go implementation of the same policy and have high confidence in the target behavior. The spec is the contract. The AI just needs to fulfill it in a new language.

Teams can build on it. A locked spec is a dependency you can trust. If your feature relies on a payment processing module, and that module’s spec is locked, you know exactly what it does. You don’t need to read the code. You don’t need to track down the engineer who built it. The spec is the interface.

It survives people leaving. The biggest risk in any software organization isn’t technical debt. It’s knowledge loss. When an engineer leaves, the reasoning behind their code leaves with them. Locked specs capture that reasoning in a form that persists independently of any individual. The context doesn’t walk out the door because it was never stored in someone’s head to begin with.

Specs as building blocks

Locked specs are composable. That’s what makes them powerful at scale.

Consider how medicine works. A pharmacopeia is a library of verified treatments, each one tested, documented, and locked down. A doctor doesn’t re-derive the efficacy of ibuprofen every time they prescribe it. They reference a body of verified knowledge and build on it.

Locked specifications work the same way. Once a behavior is specified, implemented, validated, and locked, it becomes a building block. Future implementations can reference it. Future systems can compose it with other locked specs. The library of verified behavior grows over time, and every new project starts from a higher baseline.

This is the compound interest that software has never had. Every other engineering discipline accumulates verified knowledge over time. Software starts from scratch with every project, every framework migration, every new hire who has to reverse-engineer the codebase to understand what it does. Locked specs break that cycle.

What happens when things change

Business rules change. Locked specs aren’t permanent. They’re versioned.

When a requirement changes, the locked spec is revised. The new version enters the lifecycle as a draft. It gets implemented, validated, and locked again. The previous version remains in the version history; you can see what the behavior was and what it became.

This is version control for intent, not just for code. Git tracks how code changed. Spec versioning tracks why it changed: what business rule shifted, what requirement was added, what behavior was deprecated. The full history of decisions is preserved, not just the history of keystrokes.

Unlocking a spec is a deliberate act. It signals that the current behavior is no longer authoritative and needs to be re-specified. It makes change visible and intentional, rather than something that happens silently through code commits that nobody reviews against the original requirements.

The library grows

Imagine an organization where every validated behavior is locked and catalogued. After a year, they don’t just have a codebase. They have a library of specifications that describes everything the software does and why.

New engineers don’t need to spelunk through code to understand the system. They read the specs. Technology migrations don’t require reverse-engineering; the specs describe the behavior, and the new implementation just needs to pass the same validation. AI assistants don’t hallucinate about what the code should do; they reference locked specs and generate accordingly.

The knowledge compounds. Every locked spec makes the next project faster, the next migration cheaper, the next onboarding smoother. The organization’s understanding of its own software becomes an asset that appreciates over time, rather than a liability that depreciates with every departure and every framework change.

That’s the end state: software organizations that know what their software does, not because someone remembers, but because it’s specified, validated, and locked.