Last week I typed this into Claude Code:
add a Redis cache between Orders and the orders DB in "Order Management — current", then render it
and my architecture diagram updated itself. Correctly. With an audit trail. Without touching my ServiceNow instance.
That sentence would have sounded like a party trick a year ago. I want to walk through why it isn't one — and why "can an agent maintain this safely" is about to become a standard question we ask of every artifact we keep.
Why agents and diagrams were a bad match until now
Agents are good at text and terrible at pictures. An architecture diagram in a classic tool is a picture: geometry in a proprietary format, no semantics, no way to make a small verifiable change. Asking an LLM to "update the Visio" is asking it to regenerate the whole thing and hope. Nobody sane wires that into a pipeline.
So the fix isn't a smarter agent. It's a different artifact. Three requirements:
1. The diagram must be text with a grammar. In ArchTruth the source of truth is a small DSL — one concept per line: service app.orders "Orders Service", app.checkout -> app.orders : "REST". An agent can read it the way it reads code, and a change is a diff a human can review. Just as important: edits are typed operations — addNode, addEdge, setNode, layer ops — not "rewrite the file." The agent proposes a change, not a new document. Untouched lines stay byte-identical, comments and ordering included.
2. Concurrency has to be boring. This is the requirement almost everyone skips. Plenty of tools now expose diagrams over MCP — LeanIX, Ardoq, Lucid, Structurizr all ship servers, and there are startups built entirely on the idea. Speaking the protocol is the easy half. The failure mode everyone imagines is the other half: the agent overwrites the architect's morning of work. The fix is thirty years old — optimistic concurrency. Every write carries If-Match with the revision the agent read. Someone edited in between? The write gets a 412, the agent re-reads and re-applies. Two writers, zero clobbers, no locks, no drama. This is the single feature I'd insist on before letting any agent near any shared artifact.
3. Attribution has to be automatic. Every agent write lands as an immutable version attributed to its API key, in an append-only audit log next to the humans' edits. When a diagram changed at 2 a.m., you know which key, which operations, and what the diff was. "An AI did it" is not an acceptable answer in a change advisory board; "key ci-pipeline, revision 41→42, added the cache node per CHG0031337" is.
The wiring
One line:
claude mcp add --transport http archtruth https://archtruth.app/api/mcp \ --header "Authorization: Bearer <org-scoped key>"
That exposes eight tools over MCP — list, get, search, patch with typed ops, render, validate — the same handlers the human editor uses. The same API is plain REST with an OpenAPI spec, so the CI job that just deployed a new service can add it to the diagram in the same pipeline run. Read-only keys for reporting agents, write keys for maintaining ones, rate limits per key.
What changes when this works
The interesting effect isn't the demo — it's that the diagram's maintenance story changes. Today a diagram is accurate exactly as long as a human remembers to update it. Once the systems that change your architecture also update the picture of it — deploy pipeline adds the service, the agent that scaffolded the integration draws the edge — the diagram is maintained by the same forces that cause drift. That's the only stable equilibrium I know of.
And because current state is generated from the CMDB (read-only — every node carries its sys_id) and future state lives as a layer on top, the human work moves up a level: you design the target, the diff becomes the change request package, and the decision record cites the exact change it justifies. The agents do the bookkeeping. The architects do architecture.
The loop is live at [archtruth.app](https://archtruth.app) — free tier, no card, thirty minutes with a PDI. If you run a ServiceNow estate and want to pressure-test this on your own CMDB, I'm looking for a handful of design partners: mike@mikereams.com.