ac-diagram

Diagram - Code relationships + Business mapping + Mermaid export

For software engineers to read code and business context and generate explainable Mermaid diagrams. By default, output structured conclusions + Mermaid source code; when the user requests images, PDFs, or shareable links, then use as needed mermaid-live MCP to export local files or generate visualization links.

Usage

/ac-diagram [模块|文件|函数|业务流程描述] [--type architecture|callflow|mapping|all] [--format code|svg|png|pdf|url]

Parameter description

Parameter	Description
模块｜文件｜函数｜业务流程描述	Diagram analysis scope. Can be a module name, file path, class/function name, or business process description.
--type architecture	Generate a code structure / module context diagram.
--type callflow	Generate a caller → callee relationship diagram.
--type mapping	Generate a business goal ↔ code implementation mapping diagram.
--type all	Generate all of the above views at once when the scope is controllable.
--format code	Output only the Mermaid source code and explanation. Default value.
--format svg/png/pdf	Export a local diagram file.
--format url	Generate a Mermaid Live shareable link. Use only when the user explicitly requests it or confirms the content is not sensitive.

Role division

Role	Responsibility
Claude (main thread)	Clarify requirements, read code and business context, extract relationships, generate Mermaid diagrams, call mermaid-live MCP to export artifacts, output the final explanation
subagents	Read-only retrieval of code context, call chains, and business mapping clues; do not modify files, do not directly deliver final results

---

Execution constraints

Working directory：

• Use the current working directory as the root directory for diagram analysis
• If the user has added multiple workspaces via /add-dir , first use Glob/Grep to determine the target workspace
• If it cannot be determined, use AskUserQuestion to ask the user to choose the target workspace

Diagram boundary：

• By default, first draw the smallest explainable scope; do not cram unrelated modules into the same diagram for the sake of a "panorama"
• If the user requests --type all and the scope is too large, first split it into multiple diagrams, and if necessary ask to narrow the scope
• When generating a business mapping diagram, if business goals, business actions, roles, or process information are missing, you must ask first; guessing business meaning is prohibited

Conditions for using subagents：

• Applicable: the target scope is relatively large, there are many modules, call chains are unclear, or multiple submodules need to be investigated in parallel
• Preferred:Explore for read-only retrieval of code paths, call chains, and dependency boundaries
• Not applicable: scenarios where the file path is known, the call relationship of a single function is involved, or a few reads on the main thread are enough to converge

Export and security：

• By default, output Mermaid source code; do not generate external shareable links by default
• If the user requests images or PDFs, prefer using mermaid-live MCP to export local files
• If the user requests a URL or needs a visualization link, you must first confirm the content is not sensitive; handle code structure, internal systems, and business links with caution by default
• Do not repeat retrieval content already delegated to subagents on the main thread

---

Execution workflow

Diagram task：$ARGUMENTS

🔍 Phase 0: Requirement enhancement and convergence

[模式：准备]

1. Identify the type of diagram the user really wants to see:
   • architecture: modules, entry points, dependencies
   • callflow: callers, callees, key call chains
   • mapping: mapping of business actions and business goals to code implementation
2. Identification scope: projects, modules, files, classes, functions, interfaces, task chains, business processes
3. Identification outputs: Mermaid source only, images/PDF, local files, shareable links
4. If any of the following is unclear, you must use AskUserQuestion：
   • diagram type is unclear
   • scope is too large or too broad
   • business mapping lacks business context
   • the user requests exporting a file but does not specify the target format

🔎 Phase 1: Context retrieval

[模式：研究]

1. When paths, files, or symbols are known, the main thread reads the relevant files directly
2. For fuzzy search:
   • Prefer using ace-tool for semantic retrieval
   • When the scope is large or parallel investigation is needed, use Agent(Explore) to launch read-only subagents
3. Extract at least the following evidence:
   • entry files / core modules
   • key classes, functions, interfaces
   • callers and callees
   • code entry points, services, jobs, storage, or external systems corresponding to business actions
4. Ground all conclusions as much as possible in file_path:line_number evidence

🧭 Phase 2: Relationship modeling

[模式：建模]

Organize relationship data according to the user's goal:

1. Code context relationships
   • module boundaries
   • entry points and core components
   • upstream and downstream dependencies
2. callers / callees
   • who initiates the call
   • where it is called
   • call type: call / read / write / publish / subscribe / return
3. Code-to-business association
   • business actions or business goals
   • corresponding API / service / Job / Repository / external system
   • the responsibility of each technical node in the business
4. If the scope allows:
   • architecture、callflow、mapping can output independent Mermaid diagrams separately
   • If the user only wants one comprehensive diagram, the main thread must first control the number of nodes to avoid an unreadable diagram

🧩 Phase 3: Generate Mermaid diagrams

[模式：绘图]

Prioritize the following diagram methods according to the scenario:

Scenario	Default diagram method	Description
Code structure / module context	flowchart TD	Show modules, entry points, and dependencies from top to bottom
Call chain	flowchart LR	Show caller → callee from left to right; if emphasizing sequence, you can switch to sequenceDiagram
Business mapping	flowchart TD or mindmap	business action → technical implementation → downstream system

When generating Mermaid diagrams:

• Use camelCase for node IDs
• Use verbs for edge labels whenever possible:calls、reads、writes、publishes、uses、maps to
• A node expresses only one clear responsibility
• For complex scopes, prefer multiple diagrams rather than stitching them into an oversized single diagram

📦 Phase 4: Export and delivery

[模式：输出]

1. Default output:
   • scope description
   • key context summary
   • call relationship table
   • business mapping table (if applicable)
   • Mermaid source
2. If the user requests svg/png/pdf：
   • use mermaid-live MCP to export the local graph file
   • return the actual output path
3. If the user requests url：
   • generate a Mermaid Live URL only when the user explicitly requests it or confirms the content is not sensitive
4. If mermaid-live MCP is unavailable:
   • fall back to outputting only the Mermaid source code and the suggested manual export method

✅ Stage 5: Self-check

[模式：审查]

Pre-delivery check:

• Whether all graph nodes and edges can be mapped to code or business evidence
• Whether the caller / callee is clearly represented
• Whether the association between code and business is clearly represented
• Whether it exceeds the scope requested by the user
• Whether internal structures that should not be disclosed were mistakenly exposed

---

Output template

## 🗺️ 图谱结果

### 范围
- 图类型：<architecture / callflow / mapping / all>
- 分析范围：<模块 / 文件 / 函数 / 业务流程>

### 关键上下文
| 类型 | 内容 | 证据 |
|------|------|------|
| 入口 | <描述> | `path/to/file:line` |
| 核心模块 | <描述> | `path/to/file:line` |

### 调用关系
| 调用方 | 被调用方 | 关系 | 证据 |
|--------|----------|------|------|
| A | B | calls | `path/to/file:line` |

### 业务映射
| 业务动作 | 代码元素 | 职责 | 证据 |
|----------|----------|------|------|
| 下单 | OrderService.create | 创建订单 | `path/to/file:line` |

### Mermaid 图
```mermaid
flowchart TD
    A --> B

Export artifacts

• <本地图文件路径 或 Mermaid Live URL>

---

## 规则

1. **证据优先** – 所有关系尽量回到 `file_path:line_number`
2. **先问后画** – 图类型、范围、业务上下文不清晰时必须先提问
3. **主线程交付** – 最终 Mermaid 图与导出产物由主线程统一生成
4. **subagents 只读辅助** – 仅做检索与关系提炼，不直接交付最终图
5. **默认谨慎外发** – 默认不生成 URL，优先本地文件或 Mermaid 源码