What is a living specification?

Explained

A living specification is a description of what a system must do and how its parts fit together, kept in the same repository as the code and updated whenever the system changes. It usually combines readable documents with machine-readable artefacts: API contracts such as OpenAPI files, architecture decision records, policies and evaluation definitions. Because it is versioned and reviewed like code, it stays true to the running system instead of drifting like a PDF. AI tools can read it to generate code and tests, spot differences between spec and implementation and propose updates when contracts change.

What it contains

• Functional descriptions: goals, users, flows and acceptance criteria.
• Contracts: API definitions (for example OpenAPI), event schemas and data models.
• Architecture decision records that explain why things are built the way they are.
• Policies and constraints: security, privacy, performance and compliance rules.
• Tests and evaluation definitions that check the system against the spec.

Living spec vs static document

A static specification is written once, approved and then left behind as the code moves on. After a few releases, nobody trusts it.

A living specification changes in the same pull request as the code. Reviews cover both, history shows when and why each requirement changed, and automated checks can fail the build when the implementation no longer matches the contract. The spec becomes a working tool, not an archive.

Why it matters with AI

AI coding assistants and agents work best with clear, current context. A living spec gives them the intent, rules and contracts they need, which reduces guesswork and inconsistent code.

It also works in the other direction. AI can compare specs with code, suggest migrations when a contract changes, regenerate tests and summarise what changed between versions. Approaches such as spec-driven development put the specification at the centre of this loop.

Frequently asked questions

Decision guides that use this term

• Legacy rewrite vs AI-assisted modernisation: should you start again or decode what you have?

Further reading

• Composable Platforms: Building Blocks of Modern Business Agility
• DevOps & Platform Engineering: Scalability, Autonomy and Governance in the Cloud-Native Era
• Agentic software engineering: how autonomous AI builds enterprise code

Related terms

• API A defined interface that lets one software system request data or actions from another; it is how applications call AI models and connect them to business systems.
• Evaluation The process of measuring how well an AI model or application performs: accuracy, relevance, safety, bias, cost and other criteria.
• API Specification A formal, machine-readable description of an API's endpoints, data schemas, authentication and errors, such as an OpenAPI document.
• Automation Having software carry out tasks without a person doing each step, increasingly with AI to handle decisions and unstructured inputs.
• Autonomous Systems Systems that sense their environment, decide and act on their own in real time, without a person supervising every step.
• Cloud AI AI capabilities offered as managed cloud services, such as Azure OpenAI, Amazon Bedrock or Google Vertex AI, so companies use models without running the infrastructure.