Guides  /  Rollout and delivery

What does a specification actually contain?

Answer

A specification states what the system is for, what it must do, what could go wrong, what it must know, where and how fast it must run, and what it should improve toward. Each of those is written in plain language.

Akka Specify compiles those inputs into one governed system. Agents, safeguards, evidence, the semantic layer, tests and deployment come out, and every part traces back to the specification that required it.

The mechanism

A functional requirement alone does not describe a governed system.

Spec-driven development turns a functional requirement into a working application. The requirement says what the system does, and a generator produces code from it. Spec-driven delivery takes a broader set of specifications and produces the entire governed system.

A production system in a regulated business needs more than behaviour. Where it runs decides which rules apply. What it knows decides whether its answers are grounded. What it may tune decides how far it changes without a person. A specification that omits those leaves them to whoever notices them later.

What goes in

Each input compiles into a different part of the system.

Goals and intentPurpose, success metrics, and who holds decision rights.
Functional requirementsWhat the system must do, across agents, tools, orchestration, memory, APIs and interface.
Risk envelopeWhat could go wrong and where the system operates. The risk envelope compiles to the safeguards enforced at runtime, along with the industry and jurisdiction posture.
Knowledge sourcesWhat the system must know, delivered as a semantic layer with a knowledge graph, hybrid retrieval, multi-hop reasoning and durable shared memory.
Operational envelopeService level, regions, latency and token budget, which set the deployment topology and the token economics.
Improvement policyWhat the system optimises toward and how far it may tune itself, which drives the reinforcement-learning loop.
What comes out

Every part of the delivered system traces to its requirement.

Agents, safeguards, evidence, the semantic layer, tests and deployment are generated together. A safeguard exists because a row in the risk envelope required it, and the runtime binding that enforces it carries that row.

The trace runs in both directions. An auditor asking why a control exists reads the requirement behind it, and a team editing a requirement sees which artifacts the edit reaches.

Questions

Related questions.

Who writes each part?

Product owners write goals and functional requirements. Risk and compliance own the risk envelope. Platform and operations own the operational envelope. One artifact holds them, so the parts are reviewed together.

What happens when a part is left blank?

An unanswered part becomes a decision made later by whoever writes the code. Writing it down moves the decision to the person who owns it.

Is a specification tied to Akka?

The specification describes the system in its own terms, so the investment stays portable across deployments and Akka versions.

Does this replace the design documents we already write?

The specification is the artifact each change is verified against. A design document that no check reads describes the system as it stood on the day it was written.

How does one specification cover several jurisdictions?

The risk envelope carries the jurisdictions, and each one contributes its own controls. One specification compiles into different runtime safeguards per region.

On Akka. The specification inputs and the system they generate are described under Akka Specify. The safeguards the risk envelope compiles to are enforced by Akka Verify.