Coding agents can’t see your architecture diagrams—fix that.

I’ve been talking a lot about architecture documentation and how it helps both humans and agents.

From my experience, most teams spend 90% of their effort on diagrams and 10% on text.

Why? Because they are the fastest way to communicate a system:

Diagrams show how components interact, how data flows, and what depends on what. They help humans understand complex systems quickly.

That’s why most architecture documentation leans heavily on diagrams.

🤔 The Problem

Most diagrams are images. Images are great for humans, but not for agents.

Some agents can interpret images, but not reliably or consistently. And even when an agent can interpret an image, it can’t reliably reason about it or keep it up to date.

🧠 Make Diagrams Understandable

You don’t need to move away from diagrams to embrace agents. Just make them understandable to agents.

If diagrams are the most valuable part of your architecture documentation, make them readable as code.

📝 Use Code-Based Diagrams

Tools like Mermaid turn text into diagrams.

That means agents can read them, reason about them, and even keep them up to date.

A Mermaid diagram isn’t just documentation—it’s structured context.

💡 Why This Matters

When your diagrams are code:

• They live with your system
• They evolve with changes (as long as you update them)
• They can be versioned
• They can be generated or modified by agents

And most importantly, they become a living, usable context.

🔄 Keep Them Up to Date

Keeping architecture documentation up to date is always a pain. Images make that even harder.

Code-based diagrams are much easier to keep up to date. Especially when you use agents and the architecture sits next to your code.

When you make a change, direct the agent to update the architecture documentation as well. Even if you don’t fully trust agents with code changes, architecture documentation is low risk.

Instead of letting it drift over time, let agents keep it up to date.