Part 3 of The Agentic AI Playbook
Series Navigation:
- Part 1: This Isn’t Autocomplete
- Part 2: What Your AI Doesn’t Know
- Part 3: Define Before You Design
- Part 4: Spec First, Always
- Part 5: How to Work With It Daily
- Part 6: When One Agent Isn’t Enough
- Part 7: What Goes Wrong
- Companion: Ontology in the Age of AI
- Full Series Guide
Ask three teams what a “Customer” is. You will get five answers. One team means the legal entity with a contract. Another means the billing account. A third means the user logging in. Somewhere in the codebase, “Customer” is a CRM record, an organisation in a multi-tenant system, and a party in a regulatory report — all at the same time, all meaning something slightly different.
Before AI, this created drift slowly. A service misunderstood a concept. An API leaked a local interpretation. Six months later, integration pain arrived.
Now add an agentic AI and ask it to generate specs, code, tests, and documentation across that landscape. It will. At speed. And it will industrialise every ambiguity it finds, embedding inconsistent meanings into every artefact it produces.
That is not an AI problem. It is a missing ontology, and AI makes it worse.
What an ontology actually is
In software architecture, an ontology is the formal definition of what exists in a domain: what the core concepts are, what they mean, and how they relate. It is the semantic foundation that everything else builds on.
It is not a database schema. It is not an API contract. It is not a class model. Those are downstream artefacts. The ontology sits above them and gives them meaning.
A simple way to hold this: the ontology defines the nouns and the truths. Specs define the behaviours. APIs, events, and interfaces expose those behaviours. Code implements them.
If your team is generating APIs and code before agreeing what the core business concepts actually are, you are not designing a system. You are improvising one. And if AI is helping you do that, you are improvising faster.
Why this matters more with AI
The problem with ambiguity has always been that it propagates. A vague concept in a requirements document becomes a vague boundary in a service, becomes a vague field name in an API, becomes a vague column in a table. Without AI, that propagation is slow enough that you often catch it partway through.
With agentic AI generating specs, code, and tests in parallel, the propagation is near-instant. The AI does not pause to ask what “Customer” really means. It infers, based on context, and moves on. Every artefact it produces is consistent with its inference, which makes the inconsistency harder to spot. The output looks clean. The semantics are a mess.
There is a second failure mode specific to brownfield work. Legacy codebases already contain mixed meanings, historical compromises, and naming that made sense at the time. When teams feed those artefacts into an agentic AI and ask it to modernise, refactor, or document them, the AI mirrors the mess back in cleaner syntax. That is not transformation. It is ambiguity preservation with better formatting.
Brownfield modernisation with AI requires an explicit decision about which meanings to carry forward, which to consolidate, and which to retire. Without that decision, the target state becomes a polished version of the old confusion.
Greenfield and brownfield: different risks
In greenfield, the danger is false confidence. Nothing exists yet, so teams assume they can define meaning later. They start generating services and workflows quickly, especially with AI in the loop, and early terminology hardens fast. Once “Customer”, “Account”, “Tenant”, and “User” are being used loosely across prompts and specs, you have created semantic debt before a single user has touched the system.
In brownfield, the danger is inherited ambiguity. The legacy estate is the source of truth for the AI’s inferences. Feed it the existing system, ask it to generate a target-state design, and it will preserve the existing system’s conceptual model unless you explicitly tell it otherwise. The concepts you needed to retire come back in the output.
The approach is the same in both cases: define what things mean before you ask the AI to build with them.
What this looks like in practice
Take a straightforward example: a customer onboarding capability for a SaaS platform.
Most teams jump straight to API and workflow design. Instead, start by defining the concepts.
A Customer is the commercial or contractual party consuming the platform. It may own one or more Accounts. It must be identifiable through at least one recognised Identifier.
An Account is the service or operational context through which capabilities are consumed. It belongs to exactly one Customer. It may have multiple Users with different roles.
A User is an individual actor interacting with the platform. They act on behalf of a Customer and have access to one or more Accounts depending on the model. They must have a unique identity within the appropriate scope.
An Identifier is a domain-recognised reference used to uniquely identify a Customer, Account, or User within a given business context. Not just a string. Identifiers carry semantic and sometimes regulatory meaning.
At this point: no API, no orchestration, no screen flow. Just a disciplined definition of reality.
Now add the invariants. A Customer must have at least one valid Identifier. An Account must belong to exactly one Customer. A User must not exist without an owning Customer context. An onboarding flow must not create an Account detached from a valid Customer.
These are not implementation details. They are truths. They must survive UI changes, API versions, event-driven flows, data migrations, and AI-generated refactors. If they are only enforced in one service, they are local validations pretending to be architecture.
With that foundation, writing the spec becomes straightforward. The spec uses the ontology. It does not redefine it. That is exactly how it should work.
Where AI actually fits
Once the ontology exists, AI becomes a genuine accelerator. Not before.
With agreed concepts and invariants in place, you can prompt the AI to generate first-pass specs that reference those concepts consistently. You can ask it to challenge edge cases against the invariants. You can use it to identify naming drift across services, generate test cases aligned to business truths, and document process flows that respect the agreed semantics.
Without that foundation, the AI is doing all of those things — just based on inferences you never validated. It will collapse distinct concepts into one when they look similar. It will split one concept into several when context varies. It will generate APIs that expose implementation structure rather than business meaning, because implementation structure is what it can see.
AI is a force multiplier. The question is what you are multiplying. Clarity scales. So does confusion.
Devil’s advocate
The honest objection is overhead. Defining an ontology before building anything sounds like exactly the kind of architecture ceremony that slows teams down without visible output.
For a small, isolated, low-risk system — one team, one service, no shared concepts — that objection has some merit. If the scope is genuinely contained, looser modelling is a reasonable trade-off.
It stops being reasonable the moment you have multiple teams, multiple services, shared domain concepts, or any meaningful integration surface. At that point the ontology is not ceremony — it is the thing that stops multiple AI-assisted workflows from drifting apart the moment they speed up. Without shared semantics, parallel delivery streams diverge by default, and they diverge faster with AI than without it.
There is also a scale argument worth pushing back on. Getting ontology right upfront is not a week-long workshop. For a focused capability, a disciplined team can define the core concepts, their relationships, and the critical invariants in a few hours. The output is a short document, not an enterprise data model. The cost of not doing it — semantic rework, integration pain, brownfield confusion preserved into the target state — tends to be measured in weeks.
What to do
Before your next greenfield feature or brownfield change, do this before opening a prompt.
Write down the three to five core concepts involved in what you are building. For each one, write a single sentence that defines what it is and what it is not. Then write the invariants: the things that must always be true, regardless of how the system is built or changed.
Share that with the team and check for disagreement. Disagreement at this stage is cheap. Disagreement after the AI has generated three services and a spec is not.
Put the result in a file in your repo. Reference it in your CLAUDE.md. From that point, every prompt you write will be working with agreed concepts rather than inferred ones.