Why coding agents need world models, not just context
In robotics, the original “world models” were models of physics — they explained the environment to an agent so the agent could move, grasp, and not break things. NVIDIA built one. A lot of people built one. The shape was always the same: capture the laws of the environment so the agent can reason about consequences before it acts.
When we move from physical agents to cooperating software agents, the environment changes but the requirement does not. An enterprise agent does not need Newtonian mechanics. It needs the business domain, the rules of the organisation, the tasks worth doing, the data it is allowed to touch, and the boundaries it must not cross. That is its physics.
Agentic coding is the same problem in a narrower domain — and right now, most teams are trying to solve it without a world model at all. The result is the experience every senior engineer has felt: ask the agent for a one-shot CLI and it lands beautifully; ask the agent to keep building the same system across months and the wheels come off. Decisions get forgotten. Patterns drift. The “fix” devolves into regenerating the entire codebase, which works once and then stops being an option.
The mistake is treating code as the memory of the project. Code is a side effect. It does not capture intent. It does not explain why the architecture has this seam and not that one. It does not record the non-functional decisions that constrained the design. This is the same impedance mismatch that has lived between architecture diagrams and source code for decades — and an agent inherits all of it the moment it opens a repository.
What we actually need is a fundamental world model for the engineering project itself: a structured, queryable, partially executable representation of what we are building, why, and how it should be built. Less new than it sounds. We have had pieces of this for twenty years, scattered across UML, C4, DDD, IDLs, and DSL-driven code generators. The job now is to assemble them into something an agent can read as memory and write against as a contract.
Below is a four-layer framework for that world model.
Layer 1 — Architecture and non-functional decisions
This is the outermost layer of the world model. It answers: what is the shape of this system, and what properties must it preserve?
The architecture layer captures the high-level structural decisions — the bounded contexts, the system boundaries, the integration topology, the deployment model. C4-style diagrams are useful here, not as decoration but as part of the specification the agent reads before it touches a file. The agent should be able to ask “which context owns this concept” and get a deterministic answer.
The non-functional decisions live alongside the structure. Latency budgets, consistency guarantees, availability targets, security posture, data residency, observability requirements, supported languages and runtimes. These are exactly the constraints a senior engineer holds in their head while making every micro-decision in a pull request, and they are exactly the constraints that get violated when an agent runs without them.
Two properties matter for this layer to actually work as agent memory. First, it must be machine-readable — Markdown prose alone is not enough; the constraints need structure the agent can index and reference. Second, where possible, the constraints must be executable: a latency budget paired with a load test, a security posture paired with a policy check, an architecture rule paired with a fitness function. An executable architectural rule is one the agent cannot quietly forget, because the build will tell on it.
This is also the layer where you encode the “rules of the game” — what kinds of changes are even allowed. Can a service in this context call that one synchronously? Is a new dependency permitted? Does this module own its own database or share one? These are the invariants. Without them, the agent will eventually do something locally sensible and globally catastrophic.
Layer 2 — Components
The component layer is where the architecture is decomposed into the things that get built and owned: services, modules, libraries, packages, aggregates, contexts. Each component has a role, an interface, a set of responsibilities, and a relationship to the others.
The trap here is reaching for UML class diagrams and calling it done. A component model that an agent can use is closer to a directory of contracts than a wall of boxes-and-arrows. For each component you want: its purpose stated in a single paragraph, its public interface (the operations it exposes and the data it accepts and returns), its dependencies on other components, its ownership of data, and the patterns it implements.
This is also the layer where domain language gets pinned down. If the project has a PaperItem and a PaperCollection, those names need to be canonical across the world model — the architecture references them, the specs reference them, the code uses them, and the agent never has to guess whether a Paper and a PaperItem are the same thing. This is the kind of naming drift that destroys long-running agentic projects, and it is exactly what a component model with explicit identifiers prevents.
The output of this layer is a navigable map: from a high-level capability down to the component that owns it, and from a component down to the operations it offers. An agent that can traverse this map knows where to go to make a change, and just as importantly, knows where not to go.
Layer 3 — Logic and behavior specs
The third layer captures what the system actually does — the business logic, the workflows, the state transitions, the rules. This is the layer most people skip, because it is the most expensive to write and the easiest to wave at with “the code is the spec.” It is also the one that pays back the most when an agent is doing the implementation.
Behavior specs come in two flavors, and a useful world model carries both.
The first is the prose-level behavioural description: the rules, the invariants, the workflows, the edge cases, the things that should never happen. Written for humans, but written precisely enough that an agent can translate them into tests. “When a paper is archived, the original metadata must remain immutable, and any correction is recorded as a new revision linked to the original” is the kind of sentence that an agent can read and turn into a property-based test, a state-machine check, or a runtime assertion.
The second flavour is the executable spec — the test that runs. Functional requirements paired with acceptance tests. Non-functional requirements paired with performance harnesses or fitness functions. State machines paired with model-based tests. The rule is simple: every claim the world model makes about behaviour should, eventually, be checkable. The agent does not need every spec to be executable from day one, but it needs to know which ones are and which ones are still aspirational.
This is also the layer that captures intent — the reason behind a design choice, not just the choice itself. Architecture Decision Records (ADRs) live here. So do the small “why this and not that” notes that, in a human team, only ever exist as Slack scrollback. Agents inherit none of that scrollback. If the rationale is not in the world model, it does not exist for the agent.
Layer 4 — Code patterns and code generation rules
The final layer is the one most agentic-coding tools start with and most stop at: how the code itself should be written. Style, structure, idioms, error handling, logging conventions, dependency injection patterns, naming, file layout, test organisation. The “house style” of the codebase.
This is the layer where you teach the agent to write code that looks like it belongs. Not just syntactically correct, but consistent with the rest of the system — the same retry pattern, the same way of structuring a handler, the same way of validating input. Without this layer, the agent will produce code that is locally fine and globally inconsistent, and a year of that turns a codebase into a museum of every coding style the agent went through that month.
The rules in this layer are best expressed as a combination of prose (”we use the repository pattern for persistence; we do not put queries in service classes”), examples (”here is a canonical handler; new handlers should look like this”), and enforced checks (linters, formatters, custom AST rules, architecture tests). The trio matters. Prose without examples is too abstract. Examples without rules become outdated. Rules without prose are unreadable.
There is a strong analogy here to compiler back-ends. The agent is, at this layer, just another code generator. The world model is the intermediate representation. The code generation rules are the target-specific lowering pass. We have decades of experience designing this kind of pipeline; we just have to remember we have it.
How Context Mapper and MDSL fit the four layers
Olaf Zimmermann’s Domain-Driven Service Design with Context Mapper and MDSL walks through a seven-step pipeline that takes a user story all the way down to OpenAPI specifications and runnable service stubs, using two DSLs — Context Mapper’s CML and the Microservice Domain-Specific Language (MDSL). Reading it through the lens of agentic world models is striking: the pipeline is, almost line-for-line, an instance of the four-layer framework above. It is what a properly engineered world model for a service-oriented system looks like when you commit to the idea.
The mapping is clean.
The user story written in CML — UserStory PaperArchiving { As a "Researcher" I want to create a "PaperItem" ... } — and the derived domain and subdomain (Domain PublicationManagement { Subdomain PaperArchive { ... } }) sit at the architecture and non-functional layer. They establish the high-level structure: which domain we are in, which subdomains exist, what each subdomain is for. The domainVisionStatement is essentially an intent annotation — exactly the kind of thing the agent needs to read before it starts modifying anything. When Step 5 splits the model into ReferenceManagementFrontend and ReferenceManagementService with a typed context map showing the relationship between them, that is the integration topology — non-functional architecture made explicit and machine-readable.
The bounded contexts and aggregates produced in Steps 3 and 4 — BoundedContext ReferenceManagementContext containing Aggregate PaperArchiveAggregate with its entities, value objects, and services — sit squarely in the component layer. Each aggregate is a component with a defined boundary, an owned set of entities, and a public service interface. The progression from type FEATURE to type APPLICATION to type SYSTEM across Steps 3 through 5 is exactly the navigable map I described earlier: the same component, viewed at three levels of resolution, with the names preserved across all of them. An agent reading this never has to guess what a PaperItem is. The entire toolchain depends on it being one thing.
The service operations and their signatures — createPaperItem, lookupPapersFromAuthor, convertToMarkdownForWebsite — together with the Microservice API Patterns decorations (STATE_CREATION_OPERATION, RETRIEVAL_OPERATION, INFORMATION_HOLDER_RESOURCE) live in the logic and behaviour spec layer. The MAP decorations are particularly interesting: they are not just labels, they are typed responsibilities that downstream tools use to decide HTTP verbs, idempotency, and caching behaviour. That is a behavioural spec encoded in a way that an agent — or a code generator, which is the same thing — can consume directly. The MDSL output, with its endpoint type ... serves as INFORMATION_HOLDER_RESOURCE exposes operation ... with responsibility STATE_CREATION_OPERATION expecting payload ... delivering payload ..., is the executable spec form: precise enough to validate against, abstract enough to retarget.
The code patterns and generation rules layer is where the MDSL-to-target generators live. The MDSL specification is a single source from which OpenAPI, gRPC Protocol Buffers, GraphQL schema, Jolie/WSDL, and Java POJO modulith stubs can all be produced. Each generator is, in our terms, a code generation rule set for its target — encoding how an MDSL endpoint becomes an HTTP path, how an operation responsibility becomes a verb, how a payload becomes a schema. The HTTP binding section in MDSL lets the team override defaults: this is the project-specific layer of the rules, the “house style” for how this particular system maps abstract operations onto concrete REST endpoints. An agent told to add a new operation has, at every step, a rule it can follow rather than a choice it has to make.
There is one more thing worth pulling out. Zimmermann is careful to note that Step 4 — refining the high-level design — remains a human activity. The transformations on either side are mechanical, but the design itself is not. This is the right answer for agentic coding too. The world model is not a magic spec that turns prompts into systems. It is a substrate that makes the boundary between human design and agent execution sharp enough to enforce. The human owns the design decisions; the agent owns the lowering. The world model is what sits between them and keeps either side from corrupting the other.
Where to start
You do not need to build this whole stack on day one to get value. The minimum viable world model is roughly: a one-page architecture overview with explicit non-functional constraints, a component list with canonical names and responsibilities, a behaviour spec for the slice you are currently building, and a code style guide with at least one canonical example per pattern. Put it in the repository. Make the agent read it before every non-trivial task. Add executable checks as you go.
GitHub’s Spec-Kit is moving in this direction. Context Mapper and MDSL are already there for the service-oriented case. Twenty years of model-driven engineering, DSL design, and contract-first development have left us with most of the parts. The work now is reassembly — taking those decade-old best practices and rewiring them so that the consumer is no longer a human reading the spec, but an agent treating it as memory.
The agent is not the new actor in this picture. It is just another code generator. What is new is the requirement that the world model be good enough to feed one continuously, across months, without the design decaying. That requirement is what makes the difference between agentic coding as gambling and agentic engineering as a discipline.
Originally published on Sovereign Agentic AI on Substack.