| name | mermaid-map |
| description | Have the agent encode project structure as Mermaid diagrams — architecture, data flow, module dependencies, entity relationships, and state — so agent and humans share an accurate mental model of how things relate. Part of the "keep the agent on track" suite. Use when a system has enough moving parts that prose alone loses the relationships. |
Mermaid map (structure as a shared diagram)
Why
Text describes parts; a diagram shows relationships. Keeping a Mermaid map in the repo gives the agent (and you) a stable picture of how things connect, so changes respect the structure.
Which diagram for what
| Need | Mermaid type |
|---|
| Architecture / data flow | flowchart |
| Data model / entities | erDiagram |
| Request / interaction flow | sequenceDiagram |
| Lifecycle / states | stateDiagram-v2 |
| Module dependencies | graph |
Example (MAP.md)
flowchart LR
API[Public API] --> ETL[Ingest + validate]
ETL --> DB[(SQLite)]
DB --> RPT[Weekly report]
RPT --> MAIL[Email]
Protocol
- Keep the map in a
MAP.md (or atop the relevant doc). The agent reads it to orient, and updates it whenever structure changes.
- One diagram per concern — don't cram architecture, data model, and sequence into one.
Anti-patterns
- Diagrams that drift out of sync with the real system (worse than none).
- Over-detailed diagrams nobody will maintain. Capture the relationships that matter.
