Improve your Prompt Engineering with the help of a little Mermaid

#promptengineering #llm #promptascode #mermaid

Spoiler Alert: This article is about using Mermaid diagrams as a method of re-enforcement in LLM prompting and not about the fary tail The Little Mermaid written by Danish author Hans Christian Anderson.

Summary

You probably have seen a lot of Mermaid Diagrams already without even realizing that what is powering them is a formal description language which is very well understood by LLMs.

Mermaid syntax is very good for describing formal, structural, or temporal information like "A happens, then B, and if X, then C".
It forces clarity and guarantees that the visualization precisely reflects the text definition which makes it a perfect choice for a prompt as code approach.

Complementing your text with additional Mermaid code in your prompt will provide the LLM so called "Dual-Path Reinforcement":

Text provides the context, intent, nuance, and soft constraints.
- It explains the goal of the sequence and the purpose of the participants,
- clarifies ambiguities present in the structural diagram
- and guides the overall interpretation.
Complementary Mermaid Code provides the strict, non-negotiable logic to ground the text.
- It explicitly defines the flow, participants, timing, and conditions (loops, branches) in a way that is less prone to misinterpretation
- and confirms the exact, step-by-step logic, preventing the LLM from "hallucinating" or misinterpreting the flow based on ambiguous human language.

Once a diagram is defined, you as the prompt engineer will simply refer to the visualization, removing the need to re-read the verbose Mermaid code for logical flow. This visual clarity is a significant advantage over other prompt as code approaches like JSON or TypeScript.

Why Mermaid Syntax Helps an LLM

For a Large Language Model (LLM) Mermaid syntax offers several critical advantages when processing structured information:

Natural language descriptions of complex systems ("A uses B, which calls C unless D is present") are inherently ambiguous. the LLM needs to interpret the context and resolve linguistic relationships.
Mermaid syntax is a Domain-Specific Language (DSL) that is highly structured and unambiguous. A --> B means A connects to B. This structure immediately tells the LLM the entities and the directed relationship between them, converting a natural languageinterpretation task into a simple, efficient parsing task.
Mermaid allows the LLMto map the text directly to a well-defined conceptual structure (a graph, a tree, a timeline). This is analogous to how a human can immediately internalize a flowchart versus reading a dense text description.

Example: Describing a Purchase Order Process

To demonstrate the efficiency and structural clarity of adding complementary Mermaid syntax to your LLM prompt, we will analyze a common scenario: a user purchasing an item in an e-commerce system, which involves interaction between three services - Frontend, OrderService, and InventoryService:

User clicks 'Buy' on the Frontend.
Frontend sends a request to the OrderService to initiate the order.
OrderService checks the stock by asking the InventoryService.
InventoryService returns the stock level.
If stock is available, OrderService deducts the stock from InventoryService.
OrderService confirms the order back to the Frontend.
Frontend shows a success message.

Textual Representation

The purchase process begins when the Frontend sends a request to the OrderService, specifying the Product ID and the desired quantity.

The OrderService then takes on the responsibility of verifying inventory. It issues a call to the InventoryService to check the current stock levels for that specific product ID.

After this check, the InventoryService responds back to the OrderService with the current quantity available.

Importantly, the process includes a critical conditional branch: If the stock is available, the OrderService sends another message back to the InventoryService to officially deduct the purchased quantity. Following this, the OrderService sends an Order Confirmation, including the new Order ID, back to the Frontend.

Conversely, if the stock is unavailable during the initial check, the OrderService terminates that branch and sends an immediate 'Error: Out of Stock' message back to the Frontend.

Regardless of the outcome of the order, the final step involves the Frontend internally displaying an appropriate success or failure message to the user.

Complementary Mermaid Sequence Diagram (DSL)

What the LLM actually sees is not the above image but this Mermaid code:

sequenceDiagram
    participant F as Frontend
    participant O as OrderService
    participant I as InventoryService

    F->>O: Initiate Purchase (Product ID, Qty)
    O->>I: Check Stock (Product ID)
    I-->>O: Stock Available (Qty)
    alt Stock Available
        O->>I: Deduct Stock (Qty)
        O-->>F: Order Confirmation (ID)
    else Stock Unavailable
        O-->>F: Error: Out of Stock
    end
    F->>F: Display Success Message

The combined input compensates for the core weaknesses of the LLM:

Ambiguity in Text: Mermaid provides the strict, non-negotiable logic to ground the text.
Hallucination/Creativity: Mermaid forces the model into a rigid structure (like code), constraining its creative freedom to invent steps that aren't there.
Losing Track in Long Context: The diagram acts as an easy-to-parse summary. The model can cross-reference the text against the visual logic flow, improving its long-term attention to the process.

Appendix: Mermaid Diagram Types you should consider for your Prompts

Diagram Type	Suitable For Knowledge Representation Aspect	Example Use Case in Code/System Analysis	Key Benefit for the LLM
Flowchart (`graph TD`, `LR`, etc.)	Temporal Flow, Process Logic, Decision Trees.	Mapping the execution path of a complex function, describing a deployment pipeline, or outlining a user sign-up workflow.	Easily extracts process order and conditional logic (e.g., if statement paths) due to explicit node-to-node connections.
Sequence Diagram (`sequenceDiagram`)	Temporal Interaction, API Calls, Message Passing.	Documenting the step-by-step interaction between microservices, a client-server authentication handshake, or the order of event emission.	Clearly defines the order of events over time and the participating entities (lifelines), which is excellent for tracing bugs.
Class Diagram (`classDiagram`)	Structure, Hierarchy, Relationships between Entities (OOP).	Defining the structure of a new module, documenting inheritance, or showing the composition of objects within a codebase.	Unambiguously captures Object-Oriented Programming (OOP) concepts like inheritance, composition, and public/private methods.
Entity Relationship Diagram (ERD) (`erDiagram`)	Data Structure, Relationship between Data Models.	Describing the schema of a database, defining the relationship between data entities (e.g., User, Order, Product) in a system.	Provides a structured map of data entities and their cardinality (one-to-many, etc.), essential for data-driven applications.
State Diagram (`stateDiagram-v2`)	State Transitions, Finite State Machines.	Documenting the lifecycle of an object (e.g., Order status: Draft -> Pending -> Shipped -> Delivered) or a UI component's behavior.	Offers clear logic on valid transitions and the events that trigger them, perfect for analyzing complex object lifecycles.

Note that this article is NOT the single response of a prompt that I gave to an LLM.

It was written by combining and structuring aspects of various interactions I had with Gemini about using Mermaids in prompting, defining initial context in GEMINI.md, and also about guard railing an LLM in the MCP Service I am working on.

My motivation to share this approach simply is because I think it is something genuine and new and might help you in your daily work with LLMs.