Control and Feedback on What You Build

You decide the shape of the system, and you get told what it actually did. Both of those happen through things you can see and change — diagrams, sketches, workflows, designs — not through a paragraph of description.

• See the system. The design is an object you can look at and change, not a paragraph you hope was read the way you meant it.
• Agree it as a team. The same document opens on everyone's screen, to point at, draw on and edit together.
• Find out what it really did. A real run drawn from the logs, with the measured timings on it.

Why this matters

You have probably already built something this way. The first days are remarkable: you describe what you want, and working functionality appears at a speed no team could match.

Then it turns. You are reporting the same issue for the third time. A fix lands and something that worked last week stops. You go round in circles — because neither of you can see the shape of the thing you are both changing.

That is fine for a prototype. It is not how a company puts a system into production. Anything the business depends on needs a design somebody decided, a record of what the system actually did, and a way to see both. Not a prompt and a hope.

Circuitry is that surface. You and the agent work on the same diagram: you brainstorm and iterate on the design there, the agent traces a real run onto it with the timings it measured, and you diagnose from evidence instead of guesses. The design stays put, so the code stays on track.

Architects and senior engineers get control back, and the AI does what it is genuinely good at — the work — as a tool and a collaborator.

If your business runs on software, you can't afford to build it any other way.

Tap to enlarge

This is a sequence diagram — who acted, in what order — drawn from one real run. Every duration under a message was measured, the note says what the network did, and the legend underneath is the diagnosis and what to change. You and the agent are looking at the same thing.

The two halves

Building software with an agent usually goes one way: you describe what you want, something is produced, and you read the result to find out what you got. Two things are missing from that, and they are the two halves of engineering.

Control is deciding the shape before it exists. Which parts there are, what they say to each other, in what order, and which one owns each decision. That is a design, and a design is something you look at and move around — not a sentence you hope was interpreted the way you meant it.

Feedback is finding out what the thing really does once it runs. Not whether it compiled; what actually happened, in what order, on whose side, and how long each step took.

Circuitry is built so both of those live in the same artefacts.

Why prose is the wrong medium for this

Most faults in a system with more than one moving part are not a wrong value inside one function. They are order and ownership: a step taken by the wrong participant, or taken before it was allowed, or decided twice by two things that both thought they were in charge.

Those are nearly invisible in a written description, and they are nearly invisible in a log, because no single log holds them — each participant only sees its own half. They are obvious in a picture of the exchange between participants.

So the description you and the agent share should be that picture.

Formal diagrams are worth keeping again

Class diagrams and data models used to be standard practice. They went out of fashion for a reason that was entirely fair: keeping them true was manual work nobody had time for. You drew the design, the code moved, and within a few weeks the diagram described a system that no longer existed. A stale diagram is worse than no diagram, because someone will believe it. So teams stopped drawing them and kept the architecture in a few people's heads.

What changed is the cost. An agent draws the class diagram of a folder from the code in seconds and names every box after the real identifier, so the first version costs you a sentence.

Keeping it costs less than that again, because every diagram is timestamped. It records when it was last drawn. The agent checks that date when it picks the diagram up, looks at what the code has done since, and updates the parts that moved. For a diagram that has to be trusted, it can also record which files it was drawn from and check those directly.

That turns a formal diagram back into something you can afford to keep: a current map of what has actually been built, which is exactly what is missing when you inherit a codebase, review a design, or try to explain a system to somebody new.

Tap to enlarge

This is a class diagram — what exists and how it is built. An interface with its two implementations hanging under it, an order composed of line items with the multiplicities on the line, and a note attached to the interface.

Tap to enlarge

And this is an entity relationship diagram — the data underneath that same system. Entities with typed attributes, primary and foreign keys marked, and a crow's foot at each end of a line saying how many of one go with how many of the other.

The same two ways round as everything else here: draw either yourself to decide a design, or have it drawn from the code to see what you have.

A diagram is text, in a format every model already knows

Both directions go through Mermaid — the plain-text diagram format. You draw on the canvas and it reads back as Mermaid; the agent writes Mermaid and it becomes boxes and lines you can drag. It is the same diagram either way, and neither of you has to learn the other's medium.

That matters more than it sounds. Mermaid is not a format we invented: every model already writes it, so there is no grammar to teach an agent and nothing proprietary holding your architecture. Here is part of the class diagram above, as text:

classDiagram
  class PaymentMethod {
    <<interface>>
    +authorise(Money amount)* Receipt
    +refund(Receipt r)* void
  }
  class Card {
    -String last4
    +authorise(Money amount) Receipt
  }
  PaymentMethod <|.. Card
  Order "1" *-- "*" LineItem : items
  Order --> PaymentMethod : paidWith
  %% updated: 2026-09-20T07:25:49Z

Read it as prose and it is already close to English: PaymentMethod is an interface whose authorise is abstract, Card implements it, an Order is composed of many LineItems, and an Order uses a PaymentMethod. A dozen lines hold a design that would take a page of description and still be ambiguous.

That compactness is the whole trick. It is small enough to sit in front of an agent alongside the code it is actually editing, precise enough that there is nothing to misread, and plain text — so it diffs one line per change, lives in a commit, and renders anywhere else that understands Mermaid.

The agent needs the picture more than you do

This is the part that is easy to miss, and it is the strongest reason to keep diagrams now.

An agent working on a fault reads a few hundred lines at a time out of a system that may be hundreds of thousands. It is given a narrow goal and it holds a narrow window. Inside that window it cannot see the shape of the thing it is standing in — so it traces outward through call after call, filling the window with code, and the further it goes the less room is left for the point of the exercise.

That is where duct-tape fixes come from. Not carelessness: a change that makes the symptom go away, and quietly breaks how the system was supposed to work, because nothing in front of the agent ever said how it was supposed to work. Then the next fault arrives and the same thing happens one layer further out.

A diagram is the part that does not fit in the window, made small enough that it does. It is the whole system in a few dozen lines, and it says what is supposed to happen and who is supposed to decide it. Hand the agent that before it starts and two things change:

• It keeps the system in view while working on one corner of it, so a fix is judged against the design rather than against the symptom.
• It stops guessing at the parts it has not read. Most of the confident, plausible, wrong answers about a multi-part system come from inferring the missing half.

Tip — tell your agent to work this way. It will not do it unprompted. Say something like: "Think in system and sequence diagrams. Draw the actors — the systems and services, not only the people. Keep the design on the canvas in Mermaid, and keep it updated as you go." An agent asked to hold a diagram reasons about the system; an agent left alone with the code reasons about the file it happens to be in. Ask it to check the diagram before it changes anything, and to redraw it after.

And because a diagram is an object on a canvas rather than a message in a conversation, it is also memory. The next session — yours or the agent's — starts from the picture, with the previous round's observations still on it, instead of starting from nothing and re-deriving the system from the code all over again.

It is kept in three places at once, and they are the same thing: on the canvas, as the drawing you move around; in your documents, as text you can keep beside anything else you are writing; and in the code, as a comment or a file that travels in the commit. Ask for a diagram at any time, or reopen one you drew last month and carry on from it.

That changes how you talk to the agent, too. Say "I have the sequence diagram open — why does the retry happen before the check?" and it reads the document you are looking at. A diagram, a hand-drawn sketch, a sheet, a page of code: it can open any of them. You point at the picture and it answers from the picture — a two-way visual interface alongside the conversation, rather than describing your screen to something that cannot see it.

What you actually work with

Each of these is a real object on a canvas, editable by you and readable by the agent:

Tap to enlargeTap to enlargeTap to enlarge

Every one of them is the same kind of object: drawn on a canvas, named, editable by you, and read back by the agent.

None of them is a picture pasted into a conversation. They stay on the canvas, they have names, and the agent re-reads them from the canvas each time it looks — so it sees your edits and anything an earlier session left behind, not a copy it is holding.

The loop

Design it. Agree the participants, the messages and the ownership before any code exists. It is much cheaper to move an arrow than to move a subsystem.

Build it. The diagram is the brief — hand it to the agent as the thing to implement.

Check the code against the design. Ask the agent to walk the written code step by step against the diagram: does this happen in this order, and is it this participant that decides? Reading code tells you the sequence it intends. The design is the sequence you agreed it should perform. The gap between the two is where the faults are.

Run it, and draw what happened. Put logging in every part, run it under real conditions, and have the agent gather those logs and draw the run — as a new diagram, or as annotations on the design with the real timings on it.

Compare. The same scenario under different conditions, side by side, shows you which step diverges and when.

Each pass makes the picture sharper for both of you. That is the point: the artefact carries what has been learned, so the next session starts from it instead of from nothing.

Architecture is a team artefact

A design that lives only between you and the agent is still a design in one person's head. Share opens the real document on everyone else's screen, at their own zoom — they can point at it, draw over the part they are questioning, and edit alongside you.

That is what a design review, an onboarding, or an argument about an approach should be held over: the thing itself, rather than a screen share of it.

What this changes

You are not reviewing output and hoping. You are holding a description of the system that you wrote, that the agent works from, and that gets marked up with what really happened when it ran.

That is the difference between directing the work and receiving it.

Tips

Tips for working with diagrams — drawing a run from its logs, keeping a diagram worth trusting, and what to ask for.

Next

• Flowcharts — steps, decisions and loops, drawn by hand or by the agent from how the code actually works
• Sequence diagrams — draw one, or have the agent draw one, and use it as the shared reference
• Class diagrams & data models — what exists and how it is built, drawn by hand or from the code
• Visual engineering — the two-way trip between code and architecture
• Workflows — a design that also runs