Meaning leaks. Left to itself, an agent will scatter the definition of a concept far and wide across prompts, services and a dozen inline string literals — each one a slightly different paraphrase of the same idea, sometimes even contradicting each other. This is a big ‘drift’ problem, because your system quietly believes multiple conflicting truths.
Take a status as obvious as ‘operational’. For a drilling engineer it means the well is flowing; for the operator’s press team it means first oil was announced; for a reservoir engineer it can mean producing at constrained rates during ramp-up, months before plateau. If you have not nailed this definition down then you will default to the definition presented to the agent. Where you have multiple, or zero, definitions then inevitably quality is hit, the maintenance burden goes up and the ratchet effect becomes the spaghetti effect.
It’s up to you to unambiguously control ambiguity by defining a single source of truth and arming your agents with that knowledge.
This truth lies in the semantic layer.
What lives in the layer
Everything with a fixed meaning. Enum values and their definitions. Entity type definitions and how the types relate. If you want to standardise anything across varying meaning then it goes here — for example, equivalent legislation across boundaries. Any knowledge that is used to interpret information and ‘add value’ goes in this layer. If you have a training course for new recruits that explains your industry to them, codify it here: your SOPs, your working assumptions, your disambiguation rules, your unit conventions and so on. The domain knowledge that you want to scale goes in here — essentially the logical thought processes of engineers and analysts. Anything that could be misinterpreted or disagreed on.
The semantic layer is an agent-scalable brain-dump of your in-house experts.
One definition, many consumers
The compounding trick is that a single definition now serves every consumer. Each enum carries a written definition in the semantic layer — what ‘installed’ actually means, how it differs from ‘commissioned’, which jurisdictions use which term.
The same definitions can be used across your whole pipeline: extraction, API, front end, quality control and user interface. Multiple consumers, one definition, zero drift. And because it is one definition, improving it once improves all five.
And you can gate the discipline needed — refuse to commit inline descriptions, refuse enums without definitions, refuse database fields without full semantic meaning attributed to them.
A useful side effect is the codification of organisational knowledge and the improved clarity that comes with tight definitions. These provide a virtuous feedback loop of improvement (the ratchet effect) and remove dependencies on specific experts who could leave the organisation.
Forcing the read: proof-of-read
A single source of truth is worthless if nobody consults it. Agents are confident readers of their own training data, and an agent will happily skip your definition and use its own. For high-stakes reasoning that is fatal — for regulatory and financial definitions, for example, the meaning must be retrieved from the semantic layer, not the model’s weights.
So the read is gated like everything else: proof-of-read. Before the agent can write any critical data or decision, it must present evidence it loaded the relevant semantic entries (i.e. repeat them verbatim, and the gate checks). No proof, no write. This suppresses an entire class of plausible-but-wrong analysis where the LLM would have given you the average expected answer, but your expertise requires a specific answer in a specific domain.
The annotated data model
Most teams treat a data model as fields and types. That throws away its best use. Each field in my models is decorated, and every decoration is operational — consumed by running code, not documentation that rots:
- Definition — what the field means in the real world, not just its type.
oil_rate_bopdis stabilised oil production in barrels per day, not gross fluid including water, not the licence’s equity share of it. - Aliases — every name the concept travels under, feeding the matcher’s alias index.
- Negative space —
dont_confuse_with. What this thing is not. The project is not its holding company; Project Big 1 is not Project Big 2; an operator is not a licensee. Most expensive errors are not missing knowledge, they are confusions — and a confusion is just a missing negative. Recording what things are not is as valuable as recording what they are. - Extraction guidance — a per-field pattern describing how the value tends to appear in documents and how to interpret any ambiguities. Where the prose says “up to £500”, the guidance says what to do with “up to”.
- QC priority — how important is the field to the application, and where should we weight its priority when performing quality control. You can’t quality check everything all the time. This puts the effort where the eyeballs are.
The model therefore stops being a description of storage and becomes a teaching object: the same annotations drive extraction, validation, matching and review. When the data model is the prompt, extending the system means annotating a field — not writing five new prompts.
Where it paid
Accuracy. An entity matcher’s hardest cases are disambiguation cases, and disambiguation context comes straight from the layer — what makes this company / project / whatever different from another one with the same or similar name. How do you actually identify a person, for example? False positives in entity matching are landmines.
Cost. The layer is a big, stable block of text shared by thousands of calls — which makes it perfect prompt-cache material. Definitions at the front of the prompt, volatile content at the back, fan out pyramidically, and the entire semantic spine rides the cache at a tenth of the price. Centralised meaning is not just correct, it is cheap.
Scalability. Adding new entities to your systems becomes a configurable data exercise, not an engineering one: define the type, annotate the fields, add the enums and definitions — and the extraction prompts, schemas, QC checks and UI essentially assemble themselves from the annotations. The generic machinery never changes; only the meaning does. That is the property you want when you scale from five entity types to fifty.
Honourable mention: config files
Left alone, an agent buries thresholds, weights, model choices and tuning constants inline, in whatever function needed them, duplicated and undiscoverable. I pull them into config files. The theoretical benefit is that a human can tune the knobs; in 200 days I never did. The real benefit is that the agent can find and change a value safely and consistently, in one place — and you can easily diff a config change.
Conclusion
In a world where AI models get more capable every day, one of the few ‘moats’ left is the applied knowledge domain and domain experience. You need to efficiently exploit and scale that while you still can.