diagram-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-uml Diagram Quality Best Practices

agent-uml 图质量最佳实践

Make the human-Claude design conversation converge faster on the agent-uml canvas.

让人类与Claude的设计对话在agent-uml画布上更快达成一致。

When to Apply

适用场景

Before every
```
diagram_upsert
```
call — check syntax safety rules and apply the correct skinparam preset
After every
```
design_feedback
```
response — consult the versioning decision table to choose the right next action
When starting a new design session — follow the progressive detail layers for diagram ordering
Before calling
```
design_export
```
— run the export-readiness checklist
When a diagram renders blank or elements aren't clickable — consult rendering safety rules

每次调用
```
diagram_upsert
```
之前——检查语法安全规则并应用正确的skinparam预设
每次收到
```
design_feedback
```
响应之后——参考版本决策表选择合适的下一步操作
启动新设计会话时——遵循渐进式细节层来确定图的绘制顺序
调用
```
design_export
```
之前——运行导出就绪检查清单
当图渲染为空白或元素无法点击时——参考渲染安全规则

Rule Categories by Priority

按优先级划分的规则类别

Priority	Section	Impact	Reference
1	Rendering Safety	CRITICAL	syn-safety.md, _presets.md
2	Conversation Mechanics	HIGH	_conversation.md
3	Design Effectiveness	MEDIUM	_design.md

优先级	章节	影响程度	参考文档
1	渲染安全性	关键	syn-safety.md, _presets.md
2	对话机制	高	_conversation.md
3	设计有效性	中	_design.md

Quick Reference

快速参考

1. Rendering Safety (CRITICAL)

1. 渲染安全性（关键）

18 rules that prevent blank canvas and ensure interactive SVG. Read syn-safety.md before writing any PlantUML source.

Key rules:

Every element gets
as Alias
— without it, element is not clickable on canvas
skinparam backgroundColor transparent
— white default clashes with #f4f1ec canvas
Copy the correct preset from _presets.md — one block per diagram type, matched to canvas CSS variables

包含18条防止空白画布并确保SVG可交互的规则。在编写任何PlantUML代码前，请阅读syn-safety.md。

核心规则：

每个元素都要添加
as Alias
——没有它，画布上的元素将无法点击
skinparam backgroundColor transparent
——默认白色会与#f4f1ec画布冲突
从_presets.md中复制正确的预设——每种图类型对应一个预设块，与画布CSS变量匹配

2. Conversation Mechanics (HIGH)

2. 对话机制（高）

5 decision tables for the feedback-response loop. Read _conversation.md when deciding what tool to call next.

Key tables:

Table 4: Signal → Action — maps annotation, chat, silence, and timeout to the correct tool call
Table 5: Message content — what to write in the
```
message
```
parameter (explain change + ask focusing question)

包含5个用于反馈响应循环的决策表。在决定下一步调用哪个工具时，请阅读_conversation.md。

核心表格：

表4：信号→操作——将注释、聊天、无响应和超时映射到正确的工具调用
表5：消息内容——
```
message
```
参数中应填写的内容（说明更改+提出聚焦问题）

3. Design Effectiveness (MEDIUM)

3. 设计有效性（中）

4 heuristics with concrete thresholds. Read _design.md when planning diagram sequences or preparing for export.

Key heuristics:

Progressive detail layers — L1 context → L2 container → L3 class → L4 behavior → L5 state
Cross-reference traceability — every sequence participant must map to a component; every interface belongs to exactly one component boundary
Decomposition thresholds — component >12, class >15, sequence >10 participants or >20 messages → split

包含4个带有具体阈值的启发式规则。在规划图序列或准备导出时，请阅读_design.md。

核心启发式规则：

渐进式细节层——L1上下文→L2容器→L3类→L4行为→L5状态
跨引用可追溯性——每个序列参与者必须映射到一个组件；每个接口仅属于一个组件边界
分解阈值——组件>12个、类>15个、序列参与者>10个或消息>20条时，需拆分图

How to Use

使用步骤

Starting a session: Read _conversation.md Table 3 (diagram type scope) to decide which diagram to create first
Writing PlantUML: Apply the skinparam preset from _presets.md, then check syn-safety.md for the rules relevant to your diagram type
After feedback: Consult _conversation.md Table 4 (signal → action) to decide whether to push a new version or reply with a question
Before export: Run the checklist in _design.md Heuristic 4

启动会话： 阅读_conversation.md中的表3（图类型范围）来决定首先创建哪种图
编写PlantUML代码： 从_presets.md应用skinparam预设，然后根据你的图类型检查syn-safety.md中的相关规则
收到反馈后： 参考_conversation.md中的表4（信号→操作）来决定是推送新版本还是回复问题
导出前： 运行_design.md中启发式规则4的检查清单

Reference Files

参考文件

File	Description
references/_sections.md	Section definitions and ordering
references/syn-safety.md	18 rendering safety rules (Incorrect/Correct)
references/_presets.md	5 copy-paste skinparam presets per diagram type
references/_conversation.md	5 decision tables for conversation loop
references/_design.md	4 heuristics with thresholds
assets/templates/_template.md	Template for adding new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	章节定义与排序
references/syn-safety.md	18条渲染安全规则（错误/正确示例）
references/_presets.md	按图类型划分的5个可直接复制的skinparam预设
references/_conversation.md	5个对话循环决策表
references/_design.md	4个带阈值的启发式规则
assets/templates/_template.md	添加新规则的模板
metadata.json	版本与参考信息