Use Sequence Diagrams

Two years ago, I liked to use sequence diagrams in my RFCs. I found them useful for weighing architectural decisions with my teammates.

If you're unfamiliar with sequence diagrams, they can be used to model application behavior, focusing on a sequence of actions performed between actors. Here's one of a dog barking at a cat, then a cat meowing back to it:

Actions are arrows. They are ordered (top is first, botom is last) and occur between defined actors, here Dog and Cat. Here's the complete Mermaid syntax to represent this diagram:

sequenceDiagram
    Dog->>Cat: Woof
    Cat->>Dog: Meow

As a more complex example, here's a diagram for how this page is served to modern browsers, at least as of when I wrote this post:

With coding agents, architectural decisions are more reversible and even large-scale changes can be prototyped during framing. Sequence diagrams have moved from something that I use monthly to something that I use daily. They are a key method for me to communicate with my agents.

Practically, I use sequence diagrams in the start prompt to Claude or background agents while extending an existing system. This leads to prompts like this: "Plan how to extend [service name] diagram: [paste sequence diagram] to call [external API] once for each user and to export the following per-user fields from the new endpoint: [...]. Leverage your subagents."

I'll often also ask coding agents to put a new sequence diagram in the PR description to facilitate my review of the agent's work. Sometimes, I identify architecture issues before looking at the code at all, which saves me review time.

Part of the reason I use sequence diagrams so much is because there is such great tooling to create them. Mermaid is an excellent diagramming system recommended by a colleague. It can be rendered in Github markdown using ```mermaid and is easy to integrate into existing docs.

Mermaid is so valuable is because it exposes a concise, semantic domain-specific language that LLMs can easily create and read. Sequences can be annotated with links to external and internal docs. So, on top of being easy for LLMs to use and edit, the rendered diagram provides a human-friendly, easy-to-copy-paste architectural overview for use in prompts.

Adopting mermaid provided immediate gains in framing speed and agent prompt precision. In 2024, as I worked with sequence diagrams monthly, I didn't optimize my tooling. As I began using them to prompt coding agents in 2025, I went from using general charting software like Excalidraw or Google Sheets to using a syntax specifically for sequence diagrams.

The outcome was a transition from a manual, verbose, information-diffuse and often-illegible diagram to an agent-friendly, easy-to-version control, semantic DSL for architecture design. Mermaid charts are beautiful and make it easy to engage humans on the important parts of my work.

For tasks of similar complexity, using sequence diagrams today lets me frame architectural discussions at the cadence of a synchronous slack conversation, in contrast with multiple days of async RFC work as I would do two years ago. I can then trigger coding agents to implement them with little to no additional prompting required.

Critically, having beautiful sequence diagrams doesn't just help my team and my agents understand our work. It helps everyone in my organization, since the exact docs my coding agents are using every day are also available to anyone else who needs to understand my systems, the external APIs that they interface with, or how they can access key outputs of my data pipelines. This makes communication easier and faster, especially for colleagues in different timezones.

Diagram-based prompting is lined up with how I think we should do agentic development: we should find formats that are mutually intelligible for coding agents and for human engineers, and use domain-specific languages like Mermaid diagram syntax can provide concise solutions to targeted problems.