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.
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 specs | With spec-driven development |
|---|---|
| Each team reinvents logging, guardrails, retries and cost control | The COE builds them once; every agent reuses them |
| Testers read the code to guess what "working" means | Every promise in the spec becomes a test case |
| Ops meets the agent for the first time at go-live | Ops wrote its targets, alerts and runbooks into the spec before the build began |
| Reviews are opinion against opinion | Reviews check the work against the spec, line by line |
| Problems show up in production, from customers | Gaps show up on day one, when the spec cannot answer a question |
| Changing cloud means rebuilding | Changing cloud means writing a new binding; the specs stay the same |
| The tenth agent costs about as much as the first | The 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)?
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.
| Horizontal asset | What it gives every agent team |
|---|---|
| Reference architecture | The agreed picture of how an agent is put together, with no product names |
| Reference implementation | A working agent that passes every gate, to copy from (reference agent) |
| Agent Core Framework | The shared code: the agent loop, tools, memory, retries, logging and cost metering |
| Eval Harness | One way to score answers and behaviour, across test tools (Eval Harness Framework) |
| AgentTwin | A pretend world of customers, tools and faults to test the agent in before it meets real people (AgentTwin, explained) |
| Guardrail catalog | 57 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.
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.
- ✓Every promise in the agent spec has a passing test.From: Agent spec + test strategy
- ✓The agent passed its AgentTwin worlds, including faults: a tool goes down, a customer is angry, a request is out of scope.From: World description
- ✓Response-time, error-rate and cost-per-conversation targets are set, and an alert fires when each is missed.From: Operations spec
- ✓Every alert has a runbook and a named person on call.From: Operations spec
- ✓Personal data is masked in logs; out-of-scope requests are refused and handed to a person.From: Assurance catalog
- ✓Model and prompt versions are pinned, and rollback has been tried once.From: Platform catalog + binding
- ✓A daily cost budget with a hard stop is switched on.From: Operations spec
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.
- The business owner says, in plain words, what the agent must do, and what it must never do.
- The agent spec is built by filling in the COE template: the requirement plus the catalogs it inherits.
- Developers build on the Agent Core Framework, so they only write what is special to this business.
- AgentTwin tests the agent in a pretend world with realistic customers and faults, before any real customer sees it.
- Ops ticks the gate checklist. Every line traces back to a spec.
- The cloud binding deploys it to Azure, AWS, GCP or Databricks.
- 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.
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 answers | AI engineering (agent harness) | Data engineering |
|---|---|---|
| What every system must have | AI Harness Catalog (AHC) | Data Platform Catalog (DPC) |
| What must always be true | AI Assurance Catalog (AAC) | Data Assurance Catalog (DAC) |
| The world it must face | Agent world description | Data World Description (DWD) |
| What this one system does | Agent spec, one per agent | Data Platform Manifest (DPM), one per company |
| Which product does each job | Binding per cloud | Data Binding Spec (DBS) |
| Practice before it is real | AgentTwin | DataTwin |
| Working example to copy | Reference agent and Agent Core Framework | Reference 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 · 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 · 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 · 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.