diagram-quality

agent-uml 图表质量最佳实践

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

适用时机

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

规则类别及优先级

优先级	部分	影响	参考
1	渲染安全	严重	syn-safety.md、_presets.md
2	对话机制	高	_conversation.md
3	设计有效性	中	_design.md

快速参考

1. 渲染安全（严重）

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

关键规则：

• 每个元素都要设置 as Alias——否则元素无法在画布上点击
• skinparam backgroundColor transparent——默认白色与 #f4f1ec 画布冲突
• 从 _presets.md 复制正确的预设——每种图表类型对应一个代码块，并与画布 CSS 变量匹配

2. 对话机制（高）

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

关键表格：

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

3. 设计有效性（中）

4 条启发式规则，附有具体阈值。规划图表序列或准备导出时，请阅读 _design.md。

关键启发式规则：

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

使用方法

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

参考文件

文件	描述
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	版本与参考信息