←Back/Engineering/Claude Code
AdvancedEngineering

Improve AI Code Awareness with Mermaid Diagram Context

Compress a codebase’s architecture into source-grounded Mermaid diagrams, store them beside the repository, and load only the relevant diagrams into an AI coding session.

Improve AI Code Awareness with Mermaid Diagram Context

Source episode · 04:00

Beyond Vibe Coding: Advanced AI Engineering with John Lindquist

with Claire Vo

John generates Mermaid diagrams from existing code, stores them as Markdown in memory/ai/diagrams, preloads them with Claude Code’s append-system-prompt option, and explains when to refresh them.

Read the full episodeWatch on YouTubeListen on SpotifyListen on Apple

Before you start

What you need

  • A working codebase and a specific flow to document
  • Claude Code or another agent that can inspect the repository
  • A repository directory for AI context files
  • A way to render Mermaid for human review

What you’ll make

A small set of reviewed Mermaid diagrams that help both engineers and coding agents understand the actual application flow.

Tools used

Step by step

The workflow

Follow the sequence once, then adapt the prompts, checks, and handoffs to your own setup.

4 steps

Step01

Generate Application Diagrams

Choose one bounded application flow, such as authentication or a database write. Ask the agent to inspect the relevant code and cite the files and symbols behind every diagram element.

Example prompt
Inspect this repository and document the [authentication flow] as Mermaid. Include UI entry points, API routes, services, persistence, success, and failure paths. Beside the diagram, list the file and symbol evidence for every node and edge. Do not infer components that are not present.
Step02

Organize Diagram Files

Save the reviewed diagram in a domain-specific Markdown file under memory/ai/diagrams. Keep explanatory notes and source paths beside the Mermaid block.

Step03

Load Context via System Prompt

Load only the diagram files relevant to the current task through Claude Code’s append-system-prompt option or an equivalent context mechanism.

Example prompt
claude --append-system-prompt "$(cat memory/ai/diagrams/authentication*.md)"
Step04

Query the AI with Full Context

Ask a focused architecture question or coding task, then compare the answer with the linked source files. Update the diagram after the implementation works and include that update with the related pull request.

Example prompt
Using the loaded authentication diagrams and repository code, explain the login and session-creation path, name the files involved, and identify where [requested change] belongs. Flag any conflict between the diagram and current code.

This method has a higher upfront token cost but saves time by eliminating the need for the AI to perform slow file searches during the session.

What good looks like

  • Every node and edge can be traced to current code.
  • The diagrams cover the requested flow without attempting to model the whole repository.
  • Only relevant files are loaded for the task, keeping context focused.
  • Diagram updates are coupled to material code changes.

Build your next product with ChatPRD

Turn an idea into a PRD, user stories, and a plan.

Try ChatPRD free

After the steps

Runbook notes

How to recover when the loop fails and where human judgment helps.

Recover

If it goes sideways

The diagram includes services, states, or edges that do not exist
Ask for file and symbol evidence beside each component, then remove anything the repository cannot support.
The diagram describes an older implementation
Regenerate or update it after the related feature works and review it in the same pull request.
Loading every diagram consumes too much context or distracts the agent
Group diagrams by domain and load only those needed for the current task.
The Mermaid syntax does not render
Run it through the repository’s Mermaid renderer or linter and repair syntax before using it as context.

Keep building

Related workflows

Create an Automated Workout Tracker with a Simple Claude Voice Note
beginnerPersonalClaude

Create an Automated Workout Tracker with a Simple Claude Voice Note

Log your workouts effortlessly without ever opening a spreadsheet. This workflow uses the Claude mobile app to parse a simple voice note and automatically update your workout tracking spreadsheet in the background.

Open
How to Rebuild Your Gmail Inbox Inside Claude to Manage Email
advancedOperationsClaude

How to Rebuild Your Gmail Inbox Inside Claude to Manage Email

Create a custom email management interface within Claude to read, triage, and draft replies without opening the Gmail tab. This workflow helps you reclaim focus and compound your learnings by training your AI on every interaction.

Open
Automate Client Proposals and Onboarding with a Claude 'Pipeline Operator'
intermediateSalesClaude

Automate Client Proposals and Onboarding with a Claude 'Pipeline Operator'

Build a fully automated system in Claude to generate personalized, interactive HTML proposals and client onboarding materials, saving hours on administrative work and creating a high-touch experience.

Open

Start shipping
better products.

Join 100,000+ product managers who use ChatPRD to write better docs, align teams faster, and build products users love.

Start building freeRequest a demo
Free to start
No credit card
SOC 2 certified
Enterprise ready