For leaders · ways of working

Spec-driven development

A small centre of excellence (COE) writes the specs once and builds the shared parts once. After that, every agent and every data platform is built, tested, released and run from the same specs, and each one we build makes the specs stronger for the next.

Solution Architectthe whole picture:flows, decisions, risksPlatform Architectwhat must exist:runtime, data, securityApplication Architecthow one agent works:tools, prompts, memoryOps and SREhow it runs:SLOs, alerts, runbooksTest Strategyhow we prove it:evals, worlds, gatesThe spec library: one place, versioned like code
The COE: five roles, five kinds of spec, one library. Each role writes the part only they know well.
5 roleswrite the specs: solution, platform and application architects, Ops and SRE, test strategy
4 kindsof spec, from "any company, any cloud" down to "this agent on Azure"
8 usesfor one spec: build, test, review, deploy, operate, gate, audit, fail fast
28 → 8gaps when we rebuilt an agent from the specs alone, run 3 to run 5

The one-minute version. Today most teams build each agent from scratch, and the knowledge lives in people's heads. Testers guess what to test, Ops learns how it behaves after go-live, and reviews come down to opinion.

With spec-driven development, that knowledge is written down once, in plain words, by the people who know it best. Developers build to it, testers test against it, Ops releases against it as a checklist, and auditors read it. When something goes wrong, we fix the spec first, so the next agent never makes the same mistake.

Why change

Building without specs, and building with them

Today, without specsWith spec-driven development
Each team reinvents logging, guardrails, retries and cost controlThe COE builds them once; every agent reuses them
Testers read the code to guess what "working" meansEvery promise in the spec becomes a test case
Ops meets the agent for the first time at go-liveOps wrote its targets, alerts and runbooks into the spec before the build began
Reviews are opinion against opinionReviews check the work against the spec, line by line
Problems show up in production, from customersGaps show up on day one, when the spec cannot answer a question
Changing cloud means rebuildingChanging cloud means writing a new binding; the specs stay the same
The tenth agent costs about as much as the firstThe tenth agent is faster and safer, because nine agents improved the specs

Who writes the specs

The COE team

Five roles. Each writes the part of the spec that only they know well. No role has to read the whole library; each opens the part that is theirs.

Solution Architect

The whole picture: which business flow, which decisions the agent may take on its own and which need a person, and the main risks.

WritesWrites the agent's purpose, its boundaries and who it hands over to.

Platform Architect

What every agent must have underneath it: runtime, identity, secrets, data access, logging, cost metering.

WritesWrites the catalogs and the binding for each cloud.

Application Architect

How one agent is put together: its tools, its prompts, its memory, how it recovers when a tool fails.

WritesWrites the agent spec template and the reference implementation.

Ops and SRE

How it runs in production: response-time and error targets (SLOs), alerts, runbooks, rollback, cost limits.

WritesWrites the operations spec and the ops gate checklist.

Test Strategy

How we prove it works: which promises need tests, which pretend worlds and faults to try, what counts as a pass.

WritesWrites the test spec and the world descriptions for AgentTwin.

Four kinds of spec

Some specs fit every company, some fit one agent

Two simple questions sort every spec. Does it name a product or cloud (tech binding), or not (tech agnostic)? Does it fit any industry (domain agnostic), or one business and one requirement (domain specific)?

CatalogsWhat every agent must haveWhat must always be trueHow to describe a test worldwritten once, used by allAgent specOne agent's behaviour contractIts promises, limits, hand-offsIts world: customers and faultsone per agentBindingsEach concern mapped to a cloudAzure, AWS, GCP, DatabricksThe only place products appearone per platformThe deployed agentClaims agent on Azure: its config,its SLOs, alerts and runbooks,and the gate evidenceone per releaseTechagnosticno product namesTechbindingnames the productDomain agnosticany industryDomain and requirement specificone business, one agent
Top left is written once and used by every agent. Bottom right exists once per release. Product names live only in the bottom row, so changing cloud never touches the top row.

Keeping the four apart is what makes the specs reusable. The catalogs on the top left are the same for an insurance agent and a hotel agent, so the second agent gets them for free.

What the COE builds

Specs first, then shared assets, then many agents

The COE does not only write documents. It also builds the horizontal assets: the parts every agent needs, whatever its industry. Domain teams then build vertical agents on top, one per business problem.

Vertical agents, built by domain teamsInsurance claimsBanking serviceHotel conciergeRetail returnsClinical reviewHorizontal assets, built once by the COEReferencearchitectureReferenceimplementationAgent CoreFrameworkEvalHarnessAgentTwinsimulatorGuardrailcatalogSpecs, written by the COECatalogsAgent spec templateBindings per cloudOps gate checklistAzureAWSGCPDatabricksruns on any cloud: the binding decides whichevery agent feeds back down
Like a building: the specs are the foundation, the shared assets are the middle floor, and each domain team adds its own agent on top.
Horizontal assetWhat it gives every agent team
Reference architectureThe agreed picture of how an agent is put together, with no product names
Reference implementationA working agent that passes every gate, to copy from (reference agent)
Agent Core FrameworkThe shared code: the agent loop, tools, memory, retries, logging and cost metering
Eval HarnessOne way to score answers and behaviour, across test tools (Eval Harness Framework)
AgentTwinA pretend world of customers, tools and faults to test the agent in before it meets real people (AgentTwin, explained)
Guardrail catalog57 common guardrails, each with the test that proves it holds (the catalog)

Not only for developers

One spec, eight uses

Most people think a spec is something developers read before coding. Here the same spec also drives testing, release, operations and audit. That is where most of the saving comes from.

Builddevelopers code to itTesttest cases come from itDeployrelease only if gates passOperate (SRE)SLOs and alerts come from itOps gate checklisttick every line, or stopAuditevidence for every ruleReviewcheck against it, not opinionFail fastgaps show on day oneThe spec
Testers, reviewers, Ops, SRE and auditors all work from the same spec the developers built to, so nobody works from a different idea of what 'done' means.

Example: the ops gate checklist

Before an agent goes live, Ops ticks a checklist. Nobody writes this list by hand. It is generated from the specs, and every line says which spec it came from. If a line cannot be ticked, the release stops.

The same lines help testers (they know exactly what to prove), reviewers (they check the evidence, not the code style) and SRE (the targets and alerts were agreed before the build, not after an incident).

Then, the vertical agents

How one domain agent gets built

Once the COE layer is in place, a domain team can build an agent for insurance, banking, hospitality, retail or healthcare by following the same six steps every time.

7What each agent teaches us goes back into the specs and assets1Business ownersays what it must do2Agent specCOE specs + requirement3Developerbuilds on the framework4AgentTwintests in a pretend world5Ops gateall ticks, or no release6Cloudserves real customers
Step 7 is the important one. What each agent teaches us flows back into the COE's specs and shared assets.
  1. The business owner says, in plain words, what the agent must do, and what it must never do.
  2. The agent spec is built by filling in the COE template: the requirement plus the catalogs it inherits.
  3. Developers build on the Agent Core Framework, so they only write what is special to this business.
  4. AgentTwin tests the agent in a pretend world with realistic customers and faults, before any real customer sees it.
  5. Ops ticks the gate checklist. Every line traces back to a spec.
  6. The cloud binding deploys it to Azure, AWS, GCP or Databricks.
  7. Lessons go back to the COE: a missing rule, a new fault, a better default.

Why it gets better with time

Every agent makes the bundle stronger

The specs, the framework, the eval harness and AgentTwin together form the harness bundle. It is not finished when the COE starts. It grows a little with every agent built on it.

Build an agentFind the gapsFix the specs and assetsNext one starts strongerThe harnessbundle growsGaps found when the agent was rebuiltfrom the specs alone28Run 324Run 46 repeats8Run 50 repeats
Measured: we rebuilt the same agent from the specs alone, fixed every gap it found, and rebuilt again. Gaps fell from 28 (run 3) to 8 (run 5), and none of run 4's gaps came back.

That is the business case in one picture. The first agent pays for the COE layer. Every agent after that costs less, takes less time, and fails less in production, because it starts from everything the earlier agents taught us.

Same way for data

The same method works for data engineering

We use the same pattern for data platforms. The roles and the four kinds of spec are the same; only the subject changes.

Question the spec answersAI engineering (agent harness)Data engineering
What every system must haveAI Harness Catalog (AHC)Data Platform Catalog (DPC)
What must always be trueAI Assurance Catalog (AAC)Data Assurance Catalog (DAC)
The world it must faceAgent world descriptionData World Description (DWD)
What this one system doesAgent spec, one per agentData Platform Manifest (DPM), one per company
Which product does each jobBinding per cloudData Binding Spec (DBS)
Practice before it is realAgentTwinDataTwin
Working example to copyReference agent and Agent Core FrameworkReference data platform framework

The full data version: Spec-driven development for data platforms. On AWS: the agent harness on AWS and the data platform on AWS + Databricks.

Read more: data platform architecture, DataTwin, explained, AI Harness Catalog, AI Assurance Catalog.

The case for leaders

What you get, and what it takes

For business leaders

Faster second, third and tenth agents, because most of the work is already done.

Fewer surprises in production, because agents meet faults in AgentTwin first.

Audit-ready from day one: every rule has a spec line and evidence.

No lock-in: changing cloud is a new binding, not a rebuild.

For technology leaders

One way of building across teams, so people can move between agents.

Testers, Ops and SRE join at the start, not at go-live.

Reviews become checks against the spec, so they are faster and fairer.

Gaps surface on day one, when they are cheap to fix.

What it takes

Time up front. The first agent is slower, because the COE layer is being built alongside it.

Discipline. "Fix the spec first" must be a rule, or the specs drift from the code and stop being trusted.

Five named people. The COE roles need owners with time set aside, not volunteers.

How to start

Onboarding in three steps

  1. 1 · Crawl: one pilot

    Pick one agent that matters but is not the riskiest. Use the open catalogs and the agent spec template as they are.

    Run the ops gate checklist on it, even by hand.

    You learn: where your teams' unwritten knowledge lives.

  2. 2 · Walk: form the COE

    Name the five roles. Write the binding for your cloud. Adopt the Agent Core Framework, Eval Harness and AgentTwin for the pilot.

    You get: a second agent built in much less time than the first.

  3. 3 · Run: vertical agents

    Domain teams build agents on the COE layer. AgentTwin runs on every change, and the ops gate is required for every release.

    You get: a harness bundle that improves with every agent.

Questions

Questions leaders ask

Isn't this just waterfall with a new name?

No. We work in thin slices: write a little spec, build it, test it, and fix the spec where the build showed it was wrong. Then the next slice. The spec is a living document that changes every week, not a big document signed off up front.

Won't writing specs slow us down?

The first agent, a little. After that it is faster, because most of the spec is inherited from the catalogs, and testers, Ops and reviewers stop asking questions the spec already answers.

Did you invent this method?

No. We follow the open OpenSpec way of working and borrow good ideas from GitHub Spec Kit and Kiro. What we add is what those leave out for agents: behaviour promises, operations and SLOs, testing in a pretend world, and mapping to rules such as the EU AI Act and ISO 42001.

Who owns the specs?

The COE owns the catalogs, templates and shared assets. Each domain team owns its own agent spec. A change to a shared spec goes through the COE, like a change to shared code.

Can AI write the specs for us?

AI helps a lot with drafting and with asking clarifying questions. But the decisions in a spec, such as what the agent may do alone and when it must stop, belong to people who can be held accountable for them.

What if we change cloud or vendor later?

Only the binding changes. The catalogs, the agent specs and the tests stay as they are, because they never named a product.

Talk to us

Want to try this with your team?

Everything on this page is open: the catalogs, the reference agent, the Eval Harness Framework and AgentTwin. If you would like to walk through it with your leadership team, or pilot it on one agent, write to basant@cleandataengineering.ai.

Back to For leaders