AI Agents Guide

Diagrams as context for coding agents: what a model gets from a picture

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The instinct once a team has a good architecture diagram is to hand it to the agent. It is the artifact that finally made the system legible to people, so it should do the same for a model. It mostly does not, and the reason is worth understanding before you spend a session pasting PNGs into a prompt. This page is about the form the context takes, picture or prose, and where each one earns its place. What to write in the instruction file itself is a separate question, covered in architecture context for AI coding agents.

Try it free
7 min readFor teams whose agents keep writing code that works and does not belong

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

135/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What an agent is missing when it opens the repo

Decisions that are visible in the codebase, an agent follows well: existing patterns, naming conventions, the shape of the tests. Decisions that are not visible in any file, it complies with far less often, because there is nothing to comply with. Boundaries are the main casualty, since a boundary is usually an agreement rather than a construct: nothing in the source of a data layer says that the reporting module is not supposed to call it directly.

The result is code that passes review on its own terms and quietly erodes the structure. Duplication is the second casualty: an agent that does not know a shared client exists writes another one, correctly.

This is not a reasoning failure. It is a missing input, and inputs are something you control.

Text is the context, the picture is for the humans

A model reads a short architecture document far better than it reads a PNG. Names, boundaries, and allowed dependencies belong in prose, in the repository, in a file the agent loads. The diagram is what makes the same facts legible to people, and the two should come from the same place so they cannot disagree.

That is exactly what a repository sync produces on the Datadef side: a diagram and an architecture document generated from the same parse of the source, refreshed daily. For a Terraform repository the document states what each stack provisions, how the modules wire together, how environments differ, and ends with a module reference table whose columns are Stack, Module, Source, Resources and Notes. That table is composed from the parse rather than written by the model, and a registry module the parse cannot expand reads "external" in its Resources cell instead of a number it would have to invent. It is markdown, so it can live next to the code the agent is reading.

Keep it short. Context competes for attention with the code, and a fifty-page document is not read carefully by anyone, model included. The parts that pay are the boundary rules and the list of what already exists.

Three moments where the picture is the right artifact

A structural pull request. The reviewer needs to see the before and the after, and two paragraphs of prose describing a moved boundary take longer to read than the shape does to look at. This is the case where an image attached to the review earns its keep and a document does not.

An incident. The question is which way the data flows and which component sits between the two that are arguing, and it has to be answered in seconds by somebody who was asleep ten minutes ago. Prose loses that race.

A conversation with someone outside the team. Vocabulary is not shared, and a node carrying the real vendor icon communicates before its label is read. The Datadef set holds 2,095 of those marks, 439 AWS and 624 Azure and 226 GCP among them, which is why the picture survives the handoff to a security reviewer or an auditor better than a names-only sketch.

None of those three readers is the agent. The agent is the reason the picture can exist in that workflow at all, because it is the thing that can redraw it in the same session as the change: over the MCP server an assistant calls create_diagram, edit_diagram and the canvas_* tools against the canvas you already have. Publish it once as a live embed and the pull request, the runbook and the README all show the current version.

<!-- README.md: one line, renders the current canvas -->
![Architecture](https://datadef.io/api/embed/acme-platform)

<!-- docs/architecture.md is what the agent loads. Same daily
     parse of the same repository, so the two cannot disagree. -->

Generate both halves from one read

The failure mode of keeping a picture and a document side by side is that they diverge, and then the model and the humans are working from two different systems without anyone noticing. The way out is not discipline, it is a single parse: a read-only repository connection on GitHub, GitLab or Azure DevOps, pinned to a branch or a tag, writing the diagram and an architecture.md from the same daily pass over the source.

Two properties make that survivable for the picture specifically. A commit that changes nothing structural does not redraw the canvas, and nodes somebody moved by hand keep the positions they were given, so the layout a person arranged for reading accumulates instead of being reshuffled every night. That is what lets the same artifact serve the review, the runbook and the README for months.

The cheapest version of this

Ten lines of boundary rules in text, plus one embed line for the picture, covers most of the value. What goes in those ten lines is covered in architecture context for AI coding agents; whether to trust what the agent drew is covered in keeping an AI-generated diagram trustworthy.

FAQ

Does giving a coding agent an architecture diagram improve its output?

Giving it architecture context does, and the effective form is text rather than an image. Agents already comply with decisions visible in the codebase; what they miss are the ones that live only in agreements, such as which module may call which. Writing those down as a short document the agent loads is what changes the output.

Should the context be a picture or a document?

A document for the model, a picture for the people. Models read names, boundaries, and rules in prose far more reliably than they read a rendered image, while humans need the diagram to see the shape. Generating both from the same source keeps them from contradicting each other.

Can a coding agent read an architecture diagram image?

A multimodal model can describe one, but it is a poor way to pass architecture. Node labels are the only part it can act on, the arrows lose direction and meaning under compression, and nothing in the image says which of the drawn calls are permitted. The same facts written as a short markdown document are read reliably and cost fewer tokens.

What happens when the diagram and the architecture document disagree?

Two readers act on two different systems, and neither notices until something breaks. The fix is structural rather than procedural: generate both from one pass over the source so they cannot diverge, instead of keeping a hand-drawn picture beside a generated document and hoping somebody updates the picture.

How do you keep an architecture document current without writing it by hand?

Generate it from the source. A read-only repository connection can parse the declared structure and write both the document and the diagram from the same model of the repository, daily and on demand, skipping regeneration for commits that change nothing structural.