Coding agent

Diagram-driven development.

The diagram stops being documentation produced after the fact and becomes the instruction the code is written from.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh
Notification service architecture. 12 components across 4 tiers.
Notification service architecture. Produced by the app's layout engine from a semantic graph, not placed by hand.

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

shell
# 1. Design the notification service in the Diagram tab
# 2. Implement in code
# 3. Review the diffs
# 4. Later: regenerate the diagram from the code
FAQ

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