adr-graph-easy-architect

ADR Graph-Easy 架构设计

使用 graph-easy 为架构决策记录（ADR）创建全面的 ASCII 架构图。纯文本输出，自动布局，无需渲染图像。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要变通处理，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

• 编写涉及架构变更的新 ADR
• ADR 描述迁移、集成或系统变更
• 用户要求对某项决策进行可视化呈现
• 需要审查或更新现有 ADR 图表

预检

确保在渲染图表之前已安装并能正常使用 graph-easy。

完整设置说明：预检设置

快速验证：

echo "[Test] -> [OK]" | graph-easy --as=boxart &>/dev/null && echo "✓ graph-easy ready"

---

DSL 快速参考

完整语法及示例、节点样式、边样式和表情符号规则：DSL 语法参考

基本语法

[Node]                          # Node
[A] -> [B]                      # Edge
[A] -- label --> [B]            # Labeled edge
[A] <-> [B]                     # Bidirectional
( Group: [Node A] [Node B] )    # Group/container
[id] { label: "Display"; }     # Custom label

流向（必需）

graph { flow: south; }   # Top-to-bottom (architecture, decisions)
graph { flow: east; }    # Left-to-right (pipelines, sequences)

图表标签（必需：每个图表都必须包含表情符号和标题）

警告：这是最常被遗忘的要求。没有标签的图表无效。

正确示例：

graph { label: "🔄 Database Migration"; flow: south; }
[Old DB] -> [New DB]

反面示例（无效）：

graph { flow: south; }
[Old DB] -> [New DB]

缺少带表情符号的 label:。预检验证器会阻止任何包含未使用 graph { label: "emoji ..."; } 的图表的 ADR。

表情符号选择（仅用于图表标签，绝不可放在节点内）

图表类型	表情符号	图表类型	表情符号
迁移/变更	🔄	架构	🏗️
部署/发布	🚀	网络/API	🌐
数据流	📊	存储/数据库	💾
安全/身份验证	🔐	监控	📡
错误/故障	⚠️	Hook/事件	🪝
决策/分支	🔀	之前/之后	⏮️/⏭️

节点和边样式摘要

样式	语法	用途
圆角	{ shape: rounded; }	开始/结束节点
双边框	{ border: double; }	关键/强调内容
粗边框	{ border: bold; }	重要节点
点状边框	{ border: dotted; }	可选/可跳过内容
实线箭头	->	主路径/正常流程
点状箭头	..>	条件/备用路径
粗箭头	==>	强调/关键路径
带标签的边	-- label -->	带注释的连接

字符安全性

• 节点内的图形表情符号：绝不可使用（会破坏方框对齐）
• 节点内的 Unicode 符号（勾号、叉号、警告符号）：可以使用（单宽字符）
• 节点内的 ASCII 标记（[x] [+] [!]）：始终安全
• graph { label: } 中的图形表情符号：可以使用

完整符号参考：等宽字体安全符号

---

常见图表模式

迁移（之前 -> 之后）

graph { flow: south; }
[Before] -- migrate --> [After]

多组件系统

graph { flow: south; }
[A] -> [B] -> [C]
[B] -> [D]

流水线（从左到右）

graph { flow: east; }
[Input] -> [Process] -> [Output]

带选项的决策

graph { flow: south; }
[Decision] -> [Option A]
[Decision] -> [Option B]

分组组件

( Group:
  [Component 1]
  [Component 2]
)
[External] -> [Component 1]

双向流

[Client] <-> [Server]
[Server] -> [Database]

按 ADR 类型分类的更多模式：图表示例

---

渲染

命令（必需：始终使用 boxart）

graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

绝不可使用 --as=ascii——它会生成难看的 +--+ 方框，而不是简洁的 ┌──┐ 线条。

验证工作流

# 1. Write DSL to heredoc
# 2. Render with boxart
# 3. Review output
# 4. Iterate if needed
# 5. Copy final ASCII to ADR

---

嵌入 ADR

每个渲染后的图表都必须包含带有 graph-easy 源码的可折叠 <details> 区块。完整格式指南和 GFM 语法规则：ADR 嵌入指南

必需格式：

```
┌───────┐     ┌──────┐
│ Build │ --> │ Test │
└───────┘     └──────┘
```

<details>
<summary>graph-easy source</summary>

```
graph { label: "🚀 Pipeline"; flow: east; }
[Build] -> [Test]
```

</details>

<details> 区块为必需内容——绝不可在不附带源码的情况下嵌入图表。

---

强制检查清单（渲染前）

图级设置（必须有）

• graph { label: "🚀 Title"; } - 语义化 emoji + 标题（最容易遗漏——先检查！）
• graph { flow: south; } 或 graph { flow: east; } - 明确指定方向
• 命令使用 --as=boxart - 绝不使用 --as=ascii

嵌入（必须有——不可妥协）

• 包含源代码的 <details> 块 - 每个图都必须有可折叠的源代码块
• 格式：在 ``` 块中放置渲染后的图，后接包含源代码的 <details><summary>graph-easy source</summary>
• 绝不提交没有可复现源代码的图

节点样式（视觉层级）

• 起始/结束节点：{ shape: rounded; } - 入口/出口
• 关键/重要节点：{ border: double; } 或 { border: bold; }
• 可选/可跳过节点：{ border: dotted; }
• 较长的标签使用 \n 换行 - 每行最多约 15 个字符

边样式（语义含义）

• 主路径/正常路径：-> 实线箭头
• 条件/替代路径：..> 点线箭头
• 强调/关键路径：==> 粗体箭头
• 边标签要简短（1-3 个词）：-- YES -->、-- error -->

字符安全（对齐）

• 节点内禁止使用图形 emoji（会破坏对齐）
• 节点内可以使用 Unicode 符号（单宽）
• ASCII 标记始终安全（[x] [+] [!] [OK]）
• 图形 emoji 只能用于 graph { label: "..."; } 标题

结构（组织）

• 有 4 个或更多相关节点时，使用 ( Name: ... ) 进行逻辑分组
• 节点 ID 简短，标签描述清晰：[db] { label: "PostgreSQL"; }
• 每张图不超过 7-10 个节点（更多时拆分）

成功标准

正确性

1. 解析无误 - graph-easy 能接受该 DSL
2. 渲染清晰 - 没有错位的方框或断裂的线条
3. 内容匹配 - 描述中的所有关键元素都有呈现
4. 保留源代码（强制要求） - 每张图都有包含源代码的 <details> 块

美观性

1. 使用 boxart - 使用简洁的 Unicode 线条，而非 ASCII +--+
2. 视觉层级 - 起始/结束节点用圆角，重要节点用粗体/双线，可选节点用点线
3. 样式一致 - 相同的边框样式在全文中代表相同的语义
4. 标签易读 - 使用 \n 换行，不截断
5. 流程清晰 - 方向符合自然阅读顺序（从上到下或从左到右）

全面性

1. 标题中使用语义化 emoji - 选择符合图表用途的 emoji
2. 按需添加图例 - 对复杂图表使用 \n 设置多行标题
3. 边的语义 - 实线 = 正常，点线 = 条件，粗体 = 关键
4. 逻辑分组 - 将相关节点放入 ( Group: ... ) 容器中

故障排除

问题	原因	解决方案
command not found	未安装 graph-easy	运行预检
方框错位	使用了 --as=ascii	始终使用 --as=boxart
方框边框断裂	节点中有图形 emoji	从节点中移除 emoji，改用 ASCII 标记
节点重叠	过于复杂	拆分为多张图（最多 7-10 个节点）
边标签被截断	标签太长	缩短为 1-3 个词
未显示标题	语法错误	使用 graph { label: "Title"; flow: south; }
布局异常	未指定流程方向	添加 graph { flow: south; } 或 flow: east
解析错误	节点中有特殊字符	转义或简化节点名称

资源

• CPAN 上的 Graph::Easy
• Graph::Easy 手册
• Graph::Easy GitHub

执行后反思

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要变通处理？ — 如果你不得不采用临时方案（不同的标志、额外步骤），请更新此 SKILL.md，以便下次调用时无需重复采用相同的变通方案。

仅当问题真实且可复现时才更新，不要基于猜测更新。