Diagram-driven development.
The diagram stops being documentation produced after the fact and becomes the instruction the code is written from.
The usual order is backwards
Normally code is written and a diagram is drawn afterwards to explain it, which means the diagram is derivative, optional, and the first thing to go stale. Inverting that, drawing the structure first and generating from it, makes the diagram load-bearing. Artifacts that are load-bearing stay current; artifacts that are documentation do not.
Why a diagram is a good specification
Structure is what a diagram is good at and what prose is bad at. A component list with tiers and directed relationships is unambiguous in a way that a paragraph describing the same thing is not, and ambiguity in a specification is where an agent's output diverges from what you meant. Converting the canvas to markdown keeps that precision in a form a model reads well.
What it does not specify
Error handling, data types, idempotency, retries, and the hundred decisions that determine whether an implementation is correct. A diagram gives shape, so what comes back is structurally faithful scaffolding rather than finished work. This is most useful starting something new and least useful for a subtle change to something existing.
The loop
Draw or generate the architecture, refine it as a graph until the shape is right, convert to a specification, run a coding turn, review the diffs. When the system changes, regenerate the diagram from the code so the picture and the system reconverge rather than drifting.
The loop
Questions
Is this just model-driven development again?
It shares the ambition and avoids the part that killed it. Model-driven development required a complete formal model and round-tripping. Here the diagram is a specification for a normal coding turn, and the output goes through normal review, so nothing depends on the model being complete or authoritative.
What if the implementation diverges from the diagram?
It will, immediately, because implementation adds detail the diagram never had. Regenerating from the code is how they reconverge, which is why generation in both directions matters more than either one alone.
Does this work for existing codebases?
Generate the current diagram, edit it to the shape you want, and use the difference as the specification. That is a more realistic entry point than starting from a blank canvas on a system that already exists.
Related
- Terminal Coding AgentOne binary, no runtime, no browser. Free and open source.
- AI Assistant for ObservabilityWorth being precise about what this is: it drives the observability tools you already run. It is not an LLM tracing platform, and if that is what you searched for, the tools below are the right ones.
- AI Assistant for GrafanaThe value is not writing the query. It is going from the query result to the line of code without leaving the session.
- PromQL Query AssistantPromQL is not difficult, it is just impossible to remember the exact shape of a rate over a histogram at the moment you need it.
Last updated