Claude Code Field Guide: Diagrams and Documentation

Part of the Claude Code Field Guide series.

---

Claude Code generates diagrams as easily as writing prose and can maintain documentation that actually stays current.

Mermaid for Everything

Mermaid handles most documentation needs:

I use it for architecture diagrams, data flows, state machines, sequence diagrams. Claude generates them inline while explaining systems.

Sequence diagrams:

State machines:

DrawIO XML

For more complex diagrams or when you need editable visuals, Claude can generate DrawIO XML:

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Component A" style="rounded=1" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

Save as .drawio and open in draw.io or VS Code's DrawIO extension. Useful for diagrams that need manual refinement or export to specific formats.

Documentation as Code

With Mermaid support in markdown renderers (GitHub, GitLab, many static site generators), diagrams live alongside code. They update with PRs, get reviewed with code changes, and never go stale in a separate Confluence page.

I ask Claude to "add a diagram showing the data flow" and it appears in the PR. Documentation becomes a natural byproduct of development.

The Docs + Skills Architecture

I use a layered approach to documentation:

docs/ is the human-readable source of truth. Architecture decisions, API documentation, runbooks—all in markdown, versioned with the code.

.claude/skills/ sits above docs, referencing specific sections and adding LLM-specific guidance. Skills don't duplicate—they point to docs and add context for Claude.

Auto-update loop: In my CLAUDE.md, I enforce that when code changes affect documented behavior, Claude must update the relevant docs. This keeps documentation from drifting.

The result: documentation that's always current because updating it is part of the development workflow, not a separate chore.

Visual Iteration

Claude Code can read images. This enables visual feedback loops:

1. Take a screenshot of current UI state
2. Share with Claude: "This button is misaligned, fix the CSS"
3. Claude sees the issue, makes the fix
4. Screenshot again to verify

This works for:

• UI debugging (layout issues, styling problems)
• Calibrating coordinates (I've used it to map form field positions in PDFs)
• Comparing before/after states
• Reviewing design mock implementations

The visual feedback loop is faster than describing issues in words.

Browser-Based Debugging

The Claude for Chrome extension takes this further. Claude Code can review a live webpage using actual Chrome, inspect elements, and debug issues autonomously. Instead of you taking screenshots, Claude navigates the page itself and identifies problems.

This is powerful for:

• End-to-end visual verification
• Responsive design testing
• Interactive element debugging
• Accessibility checks

Tips for Better Diagrams

Be specific about type:

• "Create a Mermaid flowchart showing..."
• "Generate a sequence diagram for..."
• "Draw the state machine for..."

Iterate:

• "Make the boxes wider"
• "Add a subgraph around the database components"
• "Use dotted lines for async calls"

Keep it simple:

• Complex diagrams become unreadable
• Split into multiple focused diagrams instead
• Let Claude suggest the right level of detail

---

Next: Settings and Security

Back to Claude Code Field Guide