In a team of people, a specification is a reference. Engineers read it, form a view, ask questions where it is unclear and fill gaps with judgement and hallway conversations. If the specification is a little out of date, the hallway usually corrects it.
Agents do not have a hallway. They act on what they are given, they resolve ambiguity by guessing, and they do not notice when a rule has changed unless something tells them. Once a team lets agents read specifications directly, the specification stops being a reference. It becomes the control surface: the main place where the organisation steers what gets built.
That shift has a consequence most teams miss. A control surface needs to be governed like one. Who may change it, how changes are versioned, and how a change reaches work already in progress all start to matter in ways they did not when a human read the document once and remembered the gist.
We have already covered what a good specification contains in Anatomy of a useful specification, and the different styles of spec-driven development in the flavours of SDD. This part is about control: what the specification governs, and how to keep it governing correctly as it changes.
Seapoint Payments is fictional, and its systems and figures are illustrative. We continue with Seapoint's merchant onboarding squad and its specification ONB-012, which covers automated bank-account verification for new merchants.
Five control points in one document
It helps to read a specification the way an agent does: not as prose, but as a set of constraints on behaviour. ONB-012 constrains the agent's work in five distinct ways.
Scope says what the agent may change. ONB-012 limits work to the payouts module and the onboarding status service. An agent that "helpfully" refactors the shared ledger client is outside scope, and the review should say so even if the refactor is good.
Contracts say which shapes must not break. Seapoint's bank-verification API returns a match result and a reason code. The specification names the contract version, so an agent cannot quietly change a field name that the risk dashboard depends on.
Acceptance criteria say when the work is done. ONB-012 has six, each written so a test can check it. "Handle partial matches appropriately" is not an acceptance criterion. "When the verification result is a partial match, the merchant's payouts are held and a review task is created within one minute" is.
Non-functional limits say how well it must work: verification must complete in under three seconds for 95% of requests, and verification responses may be retained for no longer than the period set in Seapoint's retention policy.
Explicit boundaries say what must never happen: no production data in agent sessions, no direct calls from the onboarding service to the payments ledger, no changes to fraud-scoring thresholds.
A gap in any of those five is not a documentation gap. It is a gap in control. If the boundaries section is missing, nothing in the specification stops an agent from doing something the team would never accept, and the only remaining defence is a reviewer who happens to notice.
Content is no longer the hard part
Most writing about specifications for agents stops at content: write clearly, include examples, make criteria testable. That advice is right and it is necessary. It is not sufficient once several agents and several people work from the same specification over weeks.
The hard problems are about change.
- The risk lead changes a rule after three tasks have already been built against the old one.
- Two engineers' agents work from two different copies of the specification, one pasted into a chat a fortnight ago.
- An acceptance test still checks the old behaviour, passes, and gives everyone false confidence.
- A merged change was correct under version 1.3 and is wrong under version 1.4, and nobody knows which version it was built against.
None of these is a writing problem. They are configuration-management problems, and the specification needs the same discipline the code already has.
What happened when ONB-012 changed
Midway through the work, Seapoint's risk lead changed one rule. Under version 1.3, a partial bank-account match (the account exists, but the holder name only partly matches the registered business) was accepted with a warning. Under version 1.4, a partial match holds the merchant's payouts until a person confirms the account.
That is a one-line change in the specification. It has at least four dependants.
In Seapoint's first month, the change reached the dependants by Slack message. One engineer saw it. One task was reworked. The acceptance test for partial matches was not updated, and a change merged the following week passed every check while still implementing version 1.3.
In the second month, the team treated the specification like code.
- The specification lives in the repository, next to the code it governs, so its history is the repository's history.
- Every change carries a record: what changed, why, who approved it, which sections are affected.
- Tasks and tests reference specification sections by identifier (ONB-012 §4.2, AC-4), so a tool can find every dependant of a changed section.
- Agent context is generated from the current version at the start of every task, never pasted by hand.
- Merged changes record the specification version they were built against, so a later reviewer can tell whether "correct" meant correct under the current rule.
None of these needs special tooling. A specification file in the repository, section identifiers, a small script that lists tasks and tests referencing a changed section, and a line in the pull request template covers most of it.
Who may change the control surface
If the specification steers agents, the right to change it is the right to change what agents do. That right should be held deliberately.
| Section | Owner who approves changes | Why |
|---|---|---|
| Intent and success measures | Product owner | They own the outcome |
| Business rules and examples | Analyst, with risk for risk rules | Rules carry policy |
| Contracts and limits | Architect | Other systems depend on them |
| Acceptance criteria | Tester, agreed with product owner | They decide when work is done |
| Boundaries | Architect and security | They are the last line of control |
Agents may propose specification changes. That is often useful: an agent that meets an ambiguity can open a question rather than guess. But a proposal is not a change. The approver for that section decides. We return to that separation of execution and authority in Part 5.
The cost, honestly
Governing a specification like code is more work than writing it once. Section identifiers, change records and approval rules add friction, and a small team building a low-risk feature may reasonably decide the overhead is not worth it. The test is simple: how expensive is it if an agent builds against a stale rule? For Seapoint, a stale payout rule means money leaving the business for an unverified account. That is worth a change record. For a change to a help page, it is not.
The governance of spec-driven development at scale piece covers how to tier that effort by risk, so that critical specifications get the full discipline and trivial ones do not.
What to do next
Pick one specification that agents currently work from and check three things. Is there exactly one current version, and can agents only get that version? Does every task and acceptance test point at a section identifier? When a rule changed last, can you list everything that was built against the old rule? If the answer to the third question is no, the specification is not yet a control surface. It is still a reference document being used as one.
Part 3 looks at the other side of the same problem: why the separate documents each role maintains drift apart, and why one living specification does better than a chain of handoffs.
Next: Part 3, One living specification beats twelve stale handoffs. All parts are on the series page.
How CloudNala can help
We help teams turn the specifications agents read into governed artefacts: a structure with section identifiers, ownership and approval rules per section, a change record, and simple tooling that finds every task and test affected when a rule changes. We usually start with one high-risk specification, so the team can see the difference on a change that matters before deciding how widely to apply it.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan an AI Delivery Pilot or write to us at consult@cloudnala.co.za