Agent Workflow

Agent rules for diagram tools: the lines worth writing down once

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

An agent connected to a diagram server makes the same handful of mistakes in every session: it generates a second diagram of something that already exists, it redraws when a two-node edit was needed, it re-syncs a canvas somebody spent an afternoon arranging. None of these are model failures exactly. They are missing instructions, and instructions in a prompt last one session while instructions in a rules file last forever.

Try it free
6 min readFor whoever set up the MCP connection for the rest of the team

See it as a diagram

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

121/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why a rules file and not a better prompt

A prompt says what you want this time. A rules file says how the tools behave, which is the same every time and which nobody wants to retype. Claude Code reads CLAUDE.md, several clients follow the AGENTS.md convention, and Cursor has project rules. What they share is the property that matters: the file is loaded at the start of a session, before the model has done anything expensive.

The rules that pay off are the ones that prevent a mistake with a cost: a duplicate diagram, a spent credit, a replaced canvas, a false claim of freshness in a pull request description. Style preferences do not belong there, because the design guide the tools expose already carries the drawing standard and it is maintained on the tool side rather than yours.

Keep one copy. A rules file per client that says slightly different things is how a team ends up with two behaviours and no explanation. Write it once and point the other files at it.

Six rules that pay for themselves

Read the design guide before drawing. One call, and it is the difference between a diagram that matches the rest of the workspace and one that announces it was made by a machine.

Never generate a second diagram of something that already exists. The list tool is one call and returns names, ids, node counts and last-updated dates, most recent first, so checking is cheaper than the duplicate.

Never call create_diagram twice for one request. Generation waits about 35 seconds and then continues in the background, returning an id, so the correct follow-up is polling and the incorrect one costs a credit and leaves two diagrams to reconcile.

Edit instead of redrawing when the change can be named. Default the scope to overview, and ask before producing a detailed diagram that itemises everything.

Do not refresh a repository-linked project that someone hand-tuned without asking, because a sync regenerates from source and replaces canvas edits.

Before telling anyone a diagram is current, check the status tool and quote the commit. "Synced today at commit 4f1c9a2b" is checkable; "the diagram is up to date" is a claim nobody can verify.

Two numbers belong in the same file as context rather than as rules. Syncs are rate limited to ten in ten minutes per account, and a sync of a single link is deduplicated, so an instruction to refresh every project in the workspace produces a queue rather than twenty simultaneous generations. Writing that down is what stops the next person adding a retry loop around the rate-limit message.

## Diagrams (Datadef MCP)

- Call get_design_guide before the first canvas_* call in a session.
- Check list_diagrams before creating anything. Do not create a second
  diagram of a system that already has one.
- create_diagram waits ~35s. If it returns an id and no image, poll
  get_diagram every 30s. Never call create_diagram twice for one request.
- Prefer edit_diagram over regenerating. Default scope is "overview";
  ask before using "detailed".
- Never call repo_refresh on a hand-tuned project without asking: a sync
  regenerates from source and replaces canvas edits.
- Before claiming a diagram is current, call repo_status and quote the
  commit and sync time.

Rules that do not survive contact

Do not encode layout in the rules file. Node counts, coordinates, spacing and colour rules go stale against a tool that maintains its own standard, and an agent following your outdated copy produces diagrams that look subtly wrong next to generated ones. Point at the design guide instead.

Do not ask for tighter polling than every 30 seconds. It does not make generation faster, and it burns the session context on status text.

Do not name tools the way prose names them. Every canvas primitive is exposed to clients with a canvas_ prefix, so a rule that says run layout_canvas points at a tool that does not exist; the callable name is canvas_layout_canvas. The server rewrites bare references inside its own tool descriptions for exactly this reason, and a rules file you wrote by hand gets no such treatment. The cheapest way to avoid the class of error is to generate the tool names from the live surface, which tools/list returns without a key.

Do not write rules that require the agent to know something it cannot check. "Only refresh diagrams nobody is editing" reads well and is unenforceable; "ask before refreshing a project with daily sync turned off" points at a flag the status call actually returns.

Where each client reads them

Claude Code takes CLAUDE.md, clients following the AGENTS.md convention take AGENTS.md, and Cursor takes project rules. The exact paths move faster than the conventions do, so take yours from that client's own documentation on the day you set it up rather than from a blog post. What does not move is the shape of the answer: keep the real content in one file and reference it from the others, so three copies cannot drift into three behaviours.

One more placement note: rules about diagrams belong in the repository whose diagram it is. A rule in a personal configuration file works for you and for nobody else on the team, which is how a workspace ends up with one person producing consistent diagrams and everyone else producing something else.

The test for a rule

If it does not prevent a specific mistake with a specific cost, delete it. Everything else is noise the model has to read before it starts. See agent workflows for documentation.

FAQ

Where do you put instructions for an agent about a diagram tool?

In the rules file the client reads at the start of every session: CLAUDE.md for Claude Code, AGENTS.md for clients following that convention, project rules in Cursor. Take the exact path from that client's current documentation, then keep the real content in one file in the repository whose diagram it is and reference it from the others, so the copies cannot drift into different behaviours.

What is the most common mistake an agent makes with a diagram server?

Calling the generation tool twice for one request. Generation waits about 35 seconds, then returns a diagram id and continues in the background, so a model that sees no image assumes failure and asks again, producing a duplicate diagram and spending another credit. The fix is one rule saying to poll instead.

Should the rules file describe the diagram style we want?

No. The tool exposes a design guide with the same sizing, edge and zone standard its generator follows, and it is maintained on the tool side. A style copy in your rules file goes stale and produces diagrams that look wrong next to generated ones.

How do you stop an agent overwriting a diagram someone tuned by hand?

One rule: never trigger a repository sync on a linked project without asking, because a sync regenerates from source and replaces manual canvas edits. The status tool reports whether daily sync is on, which is a checkable signal that someone deliberately protected that canvas.

Do rules files replace reviewing what the agent produced?

No. Rules prevent mechanical mistakes such as duplicates, redraws and unverified freshness claims. Whether the diagram is right, whether a component is missing, and whether the labels mean what the team means still needs a person who knows the system.