Apart from the agent skill in Part 3, the first five parts of this series assumed people write and maintain the diagram source. That assumption is already out of date. AI coding agents read repositories, answer questions about them and, given the right tool, produce architecture diagrams that look finished. For a team of three architects responsible for a whole medical scheme, the attraction is obvious.
So is the risk. An agent asked to describe a system will describe the system it sees, and sometimes also the system it expects. A cache, a message queue or a fraud check is a common pattern, and a plausible diagram includes it whether or not it exists. Architecture diagrams should be evidence, not artwork told that story with a fraud service that was proposed and never built.
Our view: let agents write architecture sources, never pictures, and put every agent-written change through the same gates as a human one, plus one more: reconciliation against an inventory the agent did not produce. A typed, schema-first source is what makes those gates possible.
Mopane Medical Scheme is fictional, and its systems and figures are illustrative. Mopane's architects started using a coding agent to propose model changes from pull requests in the claims platform repository, and to produce first versions of views for new projects.
Why the source, not the picture
An agent can produce a diagram in several forms: an image, an SVG, a drawing-tool file, or a text source. Only the last fits the workflow this series has built.
A schema constrains the output. When the agent must produce JSON that matches a schema, or a model that a parser accepts, whole classes of error are rejected before anyone looks. An element without a type, a relationship to an identifier that does not exist, a message from a participant to itself where the renderer does not support it: each fails with a specific diagnostic.
Diagnostics are something the agent can act on. A machine-readable failure, naming the rule, the element and the supported fix, can be fed back to the agent for a bounded number of repair attempts. Archify is built around this loop: its validation returns stable rule codes and supported fixes, and its skill instructions limit how many correction rounds the agent should attempt. An image gives the agent nothing to repair.
The change is reviewable. An agent's proposal arrives as a diff to the model, in a pull request (Part 4), with a computed delta. The reviewer reads three added relationships, not a new picture that might differ from the last one in ways nobody spots.
The output is comparable with reality. Because the agent writes elements with identifiers, its output can be reconciled with the inventory and traces described in Part 5.
The gates
Mopane's agent-written changes pass five steps before they merge.
1. The agent writes the source change. It works from the repository and from instructions that describe the house conventions. It does not render or edit pictures.
2. Schema and lint gates. The same validation and lint rules as for any human change. These fail closed: a source that does not pass is not shown to a reviewer.
3. Inventory reconciliation. Every element the agent names is matched by identifier against the discovered model from Part 5. Every relationship it asserts is matched against infrastructure dependencies or traces where those exist.
4. Evidence levels set by rule. Anything the agent asserts that matched the inventory is marked observed, with the source and date. Anything that did not match is marked assumed or proposed, never observed, regardless of how confident the agent sounded.
5. A named human signs off. An architect, and the owner of any affected container, approve the pull request. The approval is recorded with their name.
The first two gates are no different from human changes. The third and fourth exist because an agent's errors are of a different kind. A person who adds a component to the model usually knows whether it exists. An agent may not, and its output does not say so.
Catching invented components
Reconciliation sorts each component into one of four cells.
Named by the agent and in the inventory. Keep it, mark it observed, and record the inventory entry as its evidence.
Named by the agent but not in the inventory. This is the cell that matters. It may be a hallucination, a component that exists outside the inventory's reach (such as a partner's system), or a proposal the agent picked up from a design note. It is marked assumed or proposed, and the owning team is asked. At Mopane, the first month of agent-written views produced two of these: a "notification queue" between the claims engine and the member app that did not exist (the engine called the push service directly), and a pharmacy switch that was real but outside the cloud inventory. The first was removed. The second was added to the mapping file.
In the inventory but not named by the agent. The agent missed it. Either add it, or record that it is out of scope for this view.
In neither. Nothing to show, with the uncomfortable caveat that both lists might be missing the same thing. Interviews with owners remain the only defence there.
One rule makes the whole scheme work: the inventory must come from outside the agent. If the same agent that wrote the diagram also produces the list it is checked against, the check proves consistency, not truth. At Mopane, the inventory comes from tagged cloud resources and the trace service graph, produced by the platform's own tools.
Instructions for diagram work
The agent's behaviour depends heavily on its instructions. Mopane keeps a short section in the repository's agent instructions file, reviewed like any other code. An illustrative version:
Architecture diagram work
- Edit only files under architecture/. Never edit rendered images.
- Reuse existing element identifiers. Search the model before adding one.
- Every new element needs an owner and a support level.
- Mark an element observed only if you can cite a file and line,
a resource, or a trace. Otherwise mark it assumed.
- Never add a component because the pattern is common. If you think
one is missing, add it as proposed and say why in the pull request.
- Run validation and lint. If they fail, apply only the supported
fixes, at most twice, then stop and report.
- List every element and relationship you added, removed or changed.
The instructions encode the same things the gates check, which is deliberate. The instructions reduce how often the gates fire. The gates catch what the instructions did not prevent. Neither is enough alone. The specification is the control surface makes the same argument for agent-written code.
What stays human
Agents are good at the parts of diagram work that are tedious for people: tracing calls through a repository, keeping names consistent, updating twenty views after a rename, writing first versions of a view for a new audience. They are not accountable for the result.
Three decisions stay with people at Mopane:
- Whether a change to the architecture is acceptable. A new dependency from the provider portal to the member registry is a design decision with security and POPIA consequences for health information, not a documentation update.
- Target state. What the architecture should become is a decision for the architects and the business, recorded in decision records. An agent can describe options. It does not choose.
- What may leave the organisation. Which views can be shared externally, and in what sanitised form.
The pattern is the one CloudNala applies to AI-generated documents generally: the agent produces, checks run, a named person decides, and the record shows all three. Evidence Before Autonomy covers that pattern across documents, reviews and audits, and A polished AI output can still be wrong explains why fluency is not evidence.
Bringing the series together
Across six parts, Mopane moved from a shared drive of exported pictures to a model with a source file (Part 1), one model rendering many views (Part 2), a typed toolchain with honest gates (Part 3), review in the pull request (Part 4), reconciliation with what is running (Part 5) and, finally, agents as authors under the same controls. Each step was useful on its own, and none required the next.
The thread through all of it is the distinction between well formed and true. Tools, pipelines and agents have made well-formed diagrams cheap. Evidence, identity and named human review are still what make them true.
This is the last part. Start again from Part 1, What changes when a diagram has a source file, or see all parts on the series page.
How CloudNala can help
We help architecture teams introduce AI agents into diagram work safely: agent instructions for architecture sources, validation and reconciliation gates, evidence rules, and review and sign-off that keep a named person accountable. We can also review agent-produced architecture documentation for components and relationships that cannot be traced to evidence.
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.
Request an Architecture Review or write to us at consult@cloudnala.co.za