The context your agent needs has a name. It is the architecture model.
Tomasz Zajac
7 min read
For twenty years I have watched the architecture model be a nice-to-have. It got drawn when an audit was coming or when compliance asked for it. It lived in draw.io or Confluence, was out of date by the second release, and nobody paid a price for that. The code shipped. The model never became a must-have because nothing forced it to be one.
Something is forcing it now, and it arrived from an unexpected direction.
“Context” is the architecture model
People who never worked on architecture are rediscovering it. They do not call it that. They call it context: a folder of Markdown files the agent reads before it writes code, with the conventions, the components and the rules of the house. It is a good instinct and I do not want to mock it. But it is a reinvention, and a partial one. The discipline of describing a system so that someone who was not in the room can act on it is forty years old. Zachman published his framework in 1987. Kruchten’s 4+1 views are from 1995, ISO 42010 made viewpoints a standard, TOGAF has been teaching the business-to-technology chain since the nineties. Before you write your own in a folder of notes, it is worth checking what has already been established, because the gaps in the notes are exactly the gaps the agent will fill by guessing.
So yes: the context is the architecture model. Say it that way and the next steps become obvious.
Why the harness is not optional
I am not a sceptic about AI in delivery. An agent integrates a third-party API faster than I can read its documentation, and I want that. But the speed comes with two properties an architect has to take seriously. The agent guesses: wherever the input leaves a gap, it fills it with the most probable thing, not with the thing you meant. And it is not deterministic: the same brief gives a different design on Tuesday than it did on Monday. Neither is a bug. That is what a language model is.
Without a harness, those two properties become risk that materialises later, as a system with three ways of doing the same thing and nobody who can say which one is intended. With a harness, the same properties are a source of drafts you review, which is a better job than writing from a blank page.
The “AI-based SDLC” is the SDLC
There is a lot of writing now about an AI-native software lifecycle. Read the details and it is the ordinary lifecycle, done properly: requirements that can be tested, a model of the system, a design before the code, verification that is automated, a short loop between a change and knowing whether it was right. We knew all of this. We skipped it because people were slow enough that skipping it was survivable. Agents removed the slack. Modelling, development, iteration and a fast feedback loop are essential in a way they were not before, because the volume of change is no longer limited by typing speed.
What the model is, and what it is not
It is not a draw.io diagram. It is not C4 either, although C4 is in it. C4 shows the structure of the software, and structure is one viewpoint. Why the structure looks like that, what it has to guarantee, which business process it serves: none of that is in a container diagram.
To get the full picture you go back to the basics, and the basics are Zachman’s rows: conceptual, logical, physical. TOGAF cuts the same cake differently, into business, data, application and technology architecture, and both agree on the thing that matters here: the business layer is part of the architecture, not an input to it. Conceptual is that business side: what the system is for, the requirements, the processes it supports. Logical is how the parts connect, independent of technology. Physical is where it runs. Requirements and processes are architecture. They always were; we just filed them somewhere else.
Your model, not a standard one
Every company should define its own model and adjust it as it learns. The standards are there to be borrowed from, not adopted whole. ArchiMate is a serious piece of work, but for most organisations it is over-engineered: some sixty element types, most of which nobody will use, and a learning curve that kills adoption before it starts. TOGAF’s ADM is a method for an enterprise architecture function with a budget, not for a product team of forty people. UML and SysML have the notation for almost anything and, for that reason, for nothing in particular. A small metamodel your team actually fills in beats a complete one that stays empty.
My minimal set follows the three layers above. None of its building blocks is new; each has a source older than the current wave of tooling.
Needs
It starts with the needs: the brief, the notes from the workshop, the ticket as the customer wrote it. They are kept as they came, because the raw words are evidence. ISO 29148 has separated stakeholder needs from requirements for this reason. When a requirement is disputed months later, the need is where you find out whether anyone asked for it or it was invented on the way.
Requirements
Requirements are derived from the needs and written in EARS, so that each one has an unambiguous, testable form. EARS came out of Rolls-Royce engine control software in 2009 and fits on a page: a requirement says when, while or if something happens, and what the system shall do then. It sounds bureaucratic until you give an agent a requirement that says “fast” and see what it does with it.
Scenarios
Scenarios are written in Gherkin, each one verifying a requirement. Given, when, then: the form comes from behaviour-driven development, and what matters here is the link it keeps. A scenario names the tests that check it, so whether a requirement is verified becomes a question a build can answer.
Mockups
Mockups belong where a scenario involves a screen. A rough one is enough. Without it the agent designs the screen itself, and you see what it chose when the pull request arrives.
Processes
Processes are the kind BPMN has drawn since 2004: the work across people and systems, in order, with the point where the system takes over. Requirements state the system’s obligations one at a time. The process is where you see whether together they get a customer from the first step to the last.
The domain model
The domain model holds the entities, their attributes and the relations between them, as domain-driven design describes them. It is the vocabulary everything else uses. When a requirement says order and a component stores an order, both mean the same entity, with the same attributes. An agent without that vocabulary invents a new one in every file it touches.
State machines
State machines come one per entity whose lifecycle matters, in Harel’s statecharts from 1987. A status column tells you which states exist. It does not say which transitions are allowed or which event triggers each of them, and that is what an agent gets wrong when a new feature touches the status.
The C4 elements
The C4 elements describe the structure. Yes, C4: Simon Brown’s answer to how much of UML a team needs for structure. People, systems, containers and components cover the logical and physical layers, and most teams already draw them.
Decision records
Decision records follow the form Michael Nygard described in 2011: a status, the context, the decision and its consequences. The code records what was chosen and never why. An agent that cannot see the decision will propose the rejected option again, with good arguments.
Fitness functions
Fitness functions, from Building Evolutionary Architectures, are automated checks that an architectural property still holds: a dependency that must not exist, a response time the system has to keep. They are what keeps a decision from turning into a wish once the team, or the agent, is under pressure.
That set is enough to describe most systems I have worked on, and enough for an agent to do real work with.
What makes it a model rather than a pile of documents is the relations between the blocks. A requirement derives from a need. A scenario verifies the requirement. A component satisfies it. A decision constrains the component, and a fitness function checks that the decision still holds. A state machine is the lifecycle of one entity, and a process moves entities through those states. The model is that graph. Diagrams, tables and documents are views of it: edit the graph and the views stay true, edit the diagram and you are back in draw.io.
How people and agents use it
The same three ways. Read it, to learn the constraints and the current state before changing anything. Write it, to model: a new system from a brief, or an old one from the code nobody documented. Read it again, to check that what was built is aligned with what was decided.
Humans have always done the first and the third badly, because reading the model is slower than asking a colleague. Agents do not have colleagues. They read what is there, and they read all of it. That makes the model worth more than it was, and its gaps more expensive.
What you get
A process in which AI can be used at scale, which is a different thing from vibe coding. Vibe coding produces a pull request that engineering then reviews for two days, or approves by default because nobody has two days. Neither scales. A model the agent reads before it writes, and a check that compares the result with the model after, is what turns a fast generator of plausible code into a part of the delivery process you can defend in front of your CTO and your auditor.