Why the board beats the doc
Lesson 1 of 6 in Whiteboarding Agent Systems: Drawing the Thing You Built.
You can build an agent system and still be unable to explain it. That is not a communication footnote; it costs real things. A design review you cannot lead ends with your architecture decided by whoever draws faster. An interview where you describe an agent in prose reads as though you have only read about one. And at 2 a.m., when four people are on a call about a system only you have seen end to end, the shared understanding you can produce in ninety seconds on a board is the incident response.
The board also does something a document cannot. Drawing forces you to commit. Where exactly does the loop stop? Which box decides that? What does the arrow between these two carry? Prose lets you write “the agent then handles the response”, and everyone nods. A marker makes you choose a shape, and choosing the shape surfaces the question you were avoiding.
This module is short on theory and long on procedure: a notation small enough to memorise, an order to draw in, four sketches, and the words to say.
| Setting | What they actually want | What to draw | Failure if you get it wrong |
|---|---|---|---|
Design review | The seams: who owns control, what crosses each boundary, what happens when a hop fails | The architecture, drawn in the six-step order — and lead with control ownership rather than components | You present a component diagram, they ask “what happens if the tool times out”, and you are now designing live in front of an audience |
Interview | Evidence you have run one of these — which means the trade-offs and the failure modes | The smallest correct sketch, then name the trade out loud and the cap you would set | An impressively complex board with no numbers, no stop condition, and no cost story reads as a diagram you memorised |
Incident, 2 a.m. | What happened, in order, and what changed in the world | Not the architecture. A timeline: hops as bars left to right, with a mark where the world changed | You draw the system while people need the sequence — the architecture cannot show that step 7 ran twice |
Two notes on what this module is not. It is not a replacement for formal notations — C4, sequence diagrams, and data-flow diagrams are all excellent, and lesson five says when to reach for each. And it is not a claim that agent systems need a new diagramming language. They need a small one, because the constraint on a whiteboard is not expressiveness. It is the ninety seconds you have before the room stops watching you draw.
Key terms: stopping condition, C4 model, sequence diagram, data-flow diagram
Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.