Every project has the same dead diagram. Someone drew the architecture in a whiteboard tool, exported a PNG, and pasted it into the docs. Three sprints later the design has moved, the PNG hasn't, and now the picture quietly lies. Nobody updates it, because updating it means reopening some other app, re-exporting, re-pasting. The diagram and the words have drifted apart.
There's a second, newer problem on top of that one. If you're handing your docs to an AI coding agent - Claude Code, Copilot, Codex, whatever - a pasted screenshot is a black box to it. The agent reads your prose and your code, but the picture that explains how it all fits together is just an opaque blob it skips over. The most information-dense artifact in the doc is the one the agent can't use.
This week I shipped a fix for both, and the interesting part isn't the feature - it's the file format trick underneath it, which works in any tool, not just mine.
Full disclosure: I'm the creator of SPECLAN, a VS Code extension that manages product specifications as plain Markdown files with YAML frontmatter - Git-native, one file per requirement, organized in a hierarchical tree. A spec file looks like this:
---
id: R-0603
type: requirement
title: "Franchisee Lifecycle Management"
status: draft
---
# Franchisee Lifecycle Management
A franchisee moves through Prospect, Applicant, Eligibility
Check, and Approved...
The whole point is that the spec is the source of truth a human reviews and the prompt an AI agent implements from. So a diagram that's invisible to half that audience is a real problem. The pattern below works without SPECLAN - it's just where I hit the problem and engineered around it.
The trick: one file that's both a picture and its own source
Here's the part worth stealing regardless of your toolchain. Excalidraw can export a diagram as *.excalidraw.png - and that file is two things at once:
- A completely normal, standards-compliant PNG. GitHub renders it. Your Markdown previewer renders it. An
<img>tag renders it. Nothing special required. - The full editable source of the diagram, encoded as a
tEXtchunk inside the same PNG.
PNG's spec allows arbitrary ancillary text chunks; decoders that don't care about them just ignore them. So a viewer sees a picture, and an Excalidraw-aware editor reads the embedded scene back out and lets you keep editing. One file, two purposes - no sidecar .json, no separate "source" and "export" to keep in sync.
This is the same idea Obsidian's Excalidraw plugin uses with .excalidraw.svg. PNG is just the more compact, more universally-renderable variant.
The consequence is what makes it good: the diagram is now an ordinary file you commit to Git, sitting right next to the doc it explains. And in the Markdown, it's referenced like any other image:
Read that line as your AI agent does. It's not an opaque blob anymore - it's a standard image link with a descriptive alt text and a descriptive filename, in a self-describing folder, in plain Markdown. The agent parses it exactly the way it parses every other image reference. The picture rejoined the prompt.
What this looks like in practice
In SPECLAN, the file trick is wired into the editing flow so you never think about the format. While editing a spec, you click an insert-diagram button (or add one from the spec's Artifacts panel), name it, and the Excalidraw canvas opens. Draw your boxes and arrows, save, and the diagram renders inline in the spec - right under the prose it illustrates.
The payoff is editing. Click the diagram, the canvas reopens, you change it, you save, and the inline render updates. Same file, same window, no re-export step where drift creeps in. When the design moves, the picture moves with it, because updating it costs one click instead of a tool round-trip.
And because it's all plain files in a folder:
requirements/R-0603-franchisee-lifecycle/
R-0603-franchisee-lifecycle.md
artifacts/
lifecycle.excalidraw.png # renders on GitHub, edits in Excalidraw
it's versioned in Git like everything else, it renders on your repo host and your docs site for free, and it stays fully editable forever. No external service holds your diagram hostage; no broken embed link when someone's Figma trial expires.
The one catch: rendering vs. editing are different jobs
There's a design decision here worth calling out, because it's the kind of thing that's easy to get wrong. Viewing an .excalidraw.png needs nothing - it's a PNG, every tool already renders it. But editing needs an Excalidraw engine. Rather than bundle a whole drawing app (and its fonts, and a sanitizer, and a render cache) into my extension, I lean on the excellent free Excalidraw editor by pomdtr, installed side by side. SPECLAN owns the spec and the inline render; the Excalidraw extension owns the canvas. Two small tools, each doing one job well, instead of one tool badly reimplementing the other.
That's the general lesson, really: when a capability splits cleanly into "everyone can consume it" and "few people produce it," you don't have to ship the producer to everyone. Pick a file format the whole world already reads, and delegate the authoring to a focused tool. The PNG-with-embedded-scene format is what makes that delegation clean - the artifact is self-contained and portable, so it doesn't matter which tool drew it.
Why a "dead diagram" is worse than no diagram
The reason I cared enough to build this: a stale diagram is actively harmful in a way stale prose isn't. Readers trust pictures. A paragraph that's slightly out of date gets skimmed and second-guessed; a clean architecture diagram gets believed. When the believed thing is wrong, you've manufactured confident misunderstanding - in your teammates and now, increasingly, in the agent implementing the work.
Making the diagram cheap to update - one click, same window, versioned in the same commit as the code change that motivated it - is the only thing that actually keeps it honest over time. Format tricks are nice; the workflow that removes the friction is what matters.
Try it
-
The format idea costs you nothing to adopt today: export from excalidraw.com with "Embed scene" on, commit the
.excalidraw.png, reference it as a normal image. It renders everywhere and stays editable. - The integrated flow (draw and edit inside your specs) ships in SPECLAN v0.9.9 - free on the VS Code Marketplace - plus the free Excalidraw extension by pomdtr running alongside it.
- The 2-minute walkthrough is the video up top.
How do you keep diagrams from rotting in your docs? Diagrams-as-code with Mermaid? Generated from source? Or have you just made peace with the dead PNG? Curious what's working for people.
Top comments (3)
This is a good point because the diagram is usually the highest-signal artifact and the least machine-readable one. I've had better results when architecture diagrams live close to code as text or structured files, with generated visuals as the output rather than the source of truth.
The agent doesn't need pretty. It needs current and parseable.
Interesting approach. Mermaid solves this in a code-first way, this is more visual-first I guess .
😘