FindMoreAI

Developer field guide · UML for coding agents

UML diagram maker for coding agents

Coding agents can make fast, locally correct changes while missing the relationships between files. A UML diagram gives the agent—and the reviewer—a shared system map before code changes.

Why UML works Open the Mermaid maker Copy the agent skill
  1. 01Agent problem
  2. 02UML view
  3. 03Mermaid source
  4. 04Reviewed change
Agent problem
Missing system map
Shared solution
UML diagram
Best-fit renderer
Mermaid

Coding agents can edit files without seeing the system

An agent usually builds context from the files, searches, and instructions available in its current task. The invisible part is often the relationship between them.

  1. The architecture is spread across files

    Routes, services, queues, schemas, and state changes rarely appear in one place during an agent task.

    ResultA locally correct edit can still violate a distant system assumption.

  2. Prose hides missing relationships

    “Update checkout” does not name every actor, call, dependency, retry, or terminal state the change touches.

    ResultAmbiguity survives the plan and reaches implementation.

  3. The first real review is the code diff

    Without a shared model, reviewers often discover a wrong boundary only after the agent has written code.

    ResultA cheap diagram correction becomes an expensive rewrite.

Give the agent a UML diagram before the diff

For architecture-heavy tasks, UML is better than a longer prompt because it forces boundaries, relationships, order, and failure behavior into a model both the agent and reviewer can inspect.

  1. What belongs to the system?

    Prompt only

    “Read the relevant files.”

    With UML

    Classes, components, and dependencies are named.

  2. What happens at runtime?

    Prompt only

    “Handle the request.”

    With UML

    Actors and messages appear in execution order.

  3. What happens when it fails?

    Prompt only

    “Cover edge cases.”

    With UML

    States, guards, retries, and terminal outcomes are explicit.

Choose the view by uncertainty

Use the smallest diagram that answers the agent’s question

More boxes do not make a more accurate model. Pick one view, ground it in repository evidence, and label anything proposed.

  1. UML Class diagram

    classDiagram

    Types, interfaces, inheritance, composition, and the dependencies that shape a codebase.

    “Map the domain types and show only relationships confirmed in source.”

  2. UML Sequence diagram

    sequenceDiagram

    Request flow, service calls, async jobs, retries, and the order in which a runtime interaction unfolds.

    “Trace this request from entry point to persistence and response.”

  3. UML State diagram

    stateDiagram-v2

    Lifecycle states, allowed transitions, failure paths, guards, and terminal outcomes.

    “Model the states and transitions for this workflow, including failure recovery.”

  4. UML Data-model diagram

    erDiagram

    Entities, persisted fields, ownership, and cardinality. This is UML-adjacent rather than strict UML.

    “Draw the persisted entities and cardinality from the current schema.”

Best UML renderer for coding agents: Mermaid

“Best” here means best fit for a text-first, repository-native agent workflow—not the most feature-heavy modeling suite.

Mermaid turns a small text definition into a rendered diagram. That makes the model easy for an agent to write, a developer to review, and a repository to preserve.

  1. Agent-writable

    The source is plain text, so a coding agent can create and revise it with the same tools it uses for code.

  2. Reviewable

    A Mermaid file produces a useful Git diff instead of hiding changes inside a binary diagram document.

  3. Broad enough

    Class, sequence, state, and ER syntax cover the system views most coding-agent tasks need.

  4. Portable

    The same source can render here, in GitHub Markdown, or anywhere Mermaid is supported, with SVG for handoff.

Where Mermaid stops: Choose a modeling suite when you need strict UML compliance, a governed model repository, round-trip engineering, or drag-and-drop authoring.

Mermaid repository Class diagram syntax Rendering API

Live workbench · Mermaid 11

Make a UML diagram from text

Edit the Mermaid source and the browser renders an SVG. Your diagram text is not uploaded by FindMoreAI.

Loading renderer…
01

Mermaid source

diagram.mmd
⌘ / Ctrl + Enter
02

SVG preview

Strict render
UML class diagram preview DiagramRequest guides AgentSkill, which emits Mermaid source to MermaidRenderer. DiagramRequest + prompt: String + type: DiagramType + validate(): Result AgentSkill + inspectCodebase() + createDiagram() MermaidRenderer + render(source): SVG + exportSVG(): Blob guides emits
Mermaid on GitHub

This generator uses Mermaid’s browser renderer with securityLevel: "strict". It supports the examples above; it is not a full drag-and-drop UML modeling suite.

From model to implementation

How to use this UML diagram generator

The useful sequence is question → evidence → diagram → reviewed change. Start from the uncertainty the agent needs to resolve, not from a blank canvas.

  1. 01

    Name the question

    Use a class diagram for static structure, a sequence diagram for runtime order, or a state diagram for lifecycle logic. Keep each diagram responsible for one question.

  2. 02

    Replace the example with evidence

    Use names from the code, API contract, or schema. When you are designing a future system, mark proposed nodes and relationships so they are not mistaken for implemented behavior.

  3. 03

    Render while the source is small

    Mermaid reports broken syntax quickly. Add one relationship at a time, keep labels short, and split a crowded UML model diagram before it becomes unreadable.

  4. 04

    Review the model, then implement

    Resolve missing actors, wrong boundaries, and unhandled states before the diff. Export SVG for docs, or install the agent skill to repeat the inspect, model, validate, and handoff loop.

Keep the workflow

Install the UML diagram maker skill

Give your coding agent a repeatable Mermaid workflow: inspect the code, choose the right diagram, preserve real symbols, and validate before handoff.

SKILL.md
Portable Agent Skill 
---
name: uml-diagram-maker
description: Create, update, or review UML and software diagrams as Mermaid text. Use when the user asks for a class, sequence, state, component, use-case, data-model, or codebase architecture diagram.
---

# UML Diagram Maker

Create diagrams that are traceable to the user's request and, when available, the codebase.

1. Read the repository guidance and inspect the relevant code, schemas, and documentation before drawing.
2. Choose the smallest diagram that answers the question:
   - `classDiagram` for types, interfaces, inheritance, composition, and dependencies.
   - `sequenceDiagram` for request flow, call order, async work, and service boundaries.
   - `stateDiagram-v2` for lifecycle states, transitions, guards, and terminal outcomes.
   - `flowchart` for components, deployment topology, decisions, or a use-case view.
   - `erDiagram` for persisted entities and their cardinality.
3. Preserve names found in source. Do not invent services, methods, relationships, or guarantees. Label user-provided or inferred structure as an assumption.
4. Keep the Mermaid source reviewable:
   - Start with the diagram declaration.
   - Prefer short stable identifiers and readable labels.
   - Keep one relationship or message per line.
   - Add `%% Source: relative/path` comments when the diagram is grounded in files.
   - Avoid click handlers, embedded HTML, and external links.
5. Optimize for comprehension. Show the main path first, group related nodes, and omit detail that does not change the reader's understanding.
6. Follow the repository's existing diagram location and style. If none exists and the user asked for a file, default to `docs/diagrams/<descriptive-name>.mmd`.
7. Validate with the repository's existing Mermaid check or an already-installed `mmdc`. Do not install packages without permission. If no renderer is available, inspect the syntax and explicitly say that render validation was not run.
8. Return the Mermaid source, the selected diagram type, material assumptions, source files inspected, and validation performed.

For updates, preserve useful layout and labels unless the requested change requires restructuring the diagram.
Download file
01

Choose your agent

These commands install the same skill at project scope so it can travel with the repository.

Codex

mkdir -p .agents/skills/uml-diagram-maker && curl -fsSL https://www.findmoreai.com/skills/uml-diagram-maker/SKILL.md -o .agents/skills/uml-diagram-maker/SKILL.md

.agents/skills/uml-diagram-maker/SKILL.md

Claude Code

mkdir -p .claude/skills/uml-diagram-maker && curl -fsSL https://www.findmoreai.com/skills/uml-diagram-maker/SKILL.md -o .claude/skills/uml-diagram-maker/SKILL.md

.claude/skills/uml-diagram-maker/SKILL.md

02

Ask for the diagram

Use the UML diagram maker skill to map the checkout request flow. Save it in docs/diagrams.

Want it in every repository? Use ~/.agents/skills/ for Codex or ~/.claude/skills/ for Claude Code instead.

Common questions

UML diagram maker FAQ

What is a UML diagram maker?

A UML diagram maker turns software structure or behavior into a visual model. This page uses text-based Mermaid syntax so diagrams are editable, reviewable in version control, and easy to regenerate.

Is this UML diagram generator free?

Yes. The workbench can be used without an account. It renders in your browser and exports the current diagram as SVG.

Can Mermaid create UML class and sequence diagrams?

Mermaid has dedicated class, sequence, and state diagram syntaxes. It also supports ER diagrams and flowcharts for related software-modeling needs.

Can an AI coding agent generate a UML diagram from my codebase?

Yes, but the useful part is evidence. The included skill tells Codex or Claude Code to inspect relevant files, preserve real symbols, label assumptions, and validate the Mermaid source before handoff.

Where should I save Mermaid UML diagrams?

Follow an existing repository convention when one exists. Otherwise, a focused directory such as docs/diagrams keeps Mermaid source close to the code and makes changes reviewable.