Diagram Design架构决策记录解读5个ADR背后的设计权衡【免费下载链接】diagram-design29 editorial diagram types for Claude Code. Self-contained HTML SVG. No shadows, no Mermaid-slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-designdiagram-design 是一个面向 Claude Code 等 AI 编码助手的开源图表生成技能能输出 27 种视觉类型的自包含 HTML SVG 图表。这个项目真正值得学习的不只是它产出的精美图表而是它用 5 份架构决策记录ADR把好设计固化成可验证的工程约束。这篇架构决策记录解读文章带你逐一拆解这 5 个 ADR 背后的设计权衡看看一个 AI 时代的开源项目是如何做技术选型、如何用脚本锁死设计原则的。什么是架构决策记录ADR为什么这个项目要写决策文档ADRArchitecture Decision Record是一类把为什么这么设计写下来的工程文档。与普通文档不同它记录的是决策的上下文、取舍过程和可预期的后果而不是单纯的结论。diagram-design 在 docs/adr/ 目录下维护了 5 份 ADR编号从 0001 到 0005。它们覆盖了四个关键主题静态输出与动效安全、图表类型分类法、动效行为规范、Agent 技能的可发现性以及几何校验自动化。每一条决策都不是拍脑袋而是有脚本在 CI 里强制执行的——这正是这份架构决策记录解读中最值得关注的地方。ADR 0001 解读为什么图表默认必须是静态的核心权衡动效的表达力 vs 分享文件的安全与可审查性。diagram-design 的图表以单个 HTML 文件的形式分享会被嵌入博客文章、幻灯片和技术文档。如果允许任意内联 JavaScript那么每一个生成的文件都需要人工审计脚本——这是巨大的安全面和审查负担。但另一方面动效确实能帮助理解有序变化比如队列填满、策略追踪分叉。于是决策是输出默认静态、无脚本data-motion-modenone只有当用户明确请求动效时文件才能携带恰好一个script />这个决策的回报是27 种视觉类型成为一句可验证的声明——scripts/verify-semantic-motion.py 和 scripts/verify-docs-sync.py 都会统计它。新增一种行为成本只是一个模式段落加一行路由表而不是新类型参考、模板集和示例三件套。反过来如果某个模式真的需要现有类型给不了的布局那才是新增类型的信号。ADR 0003 解读动效如何做到不打扰读者核心权衡自动播放的表达力 vs 注意力与无障碍。动效契约把加载即自动播放列为反模式但规范的控制器本身又在加载时启动一次reveal播放——早期版本的 references/animation.md 同时写了这两句话读起来自相矛盾。ADR 0003 把规则说清楚了reveal模式可以在初次加载时运行一次它服务于简短的有序解释此时点击开始反而是摩擦运行完保持完整状态它不会在视口重新进入、标签页返回时重启也不会在没有明确 Replay 操作时重播。其余模式要么由用户发起step要么是 CSS 作用域内的装饰性循环loopnone保持完全惰性。在prefers-reduced-motion: reduce或无 JavaScript 环境下所有模式都展示完整的静态画面。于是反模式被精确定义为重复的或吸引注意力的自动播放而不是交互前的任何动效。由于控制器是唯一能启动播放的代码verify-motion.py 甚至不需要自动播放启发式规则——策略已经固化在代码里了。ADR 0004 解读40KB 字节上限如何保护 Agent 技能的可发现性核心权衡SKILL.md 的精简 vs Agent 触发技能的词汇钩子。SKILL.md 在每次技能调用时都会加载进 Agent 的上下文所以它必须精简字节上限能让增长保持诚实。但 v2.3 最初把上限设为 35,000 字节并把 frontmatter 的description删减到极限——结果 27 个类型名全被删掉了。问题来了description是 Agent决定是否加载这个技能之前唯一能看到的文本。删掉 flowchart、Gantt、org chart 这些词就等于删掉了让 帮我画个流程图 能命中这个技能的词汇钩子。ADR 0004 定下两条优先级规则frontmatterdescription必须列出选择表中的每一个视觉类型加上导入格式和主要功能词汇——由 scripts/verify-docs-sync.py 强制。路由面绝不与正文散文做交易。MAX_SKILL_BYTES设为 40,000 字节——由 scripts/verify-semantic-motion.py 强制。文件接近上限时砍正文、把细节挪进references/但绝不能动 description。这个决策的代价也很有意思新增一个视觉类型必须动 description否则 CI 直接失败——这是有意为之。另外字节数按原始字节计算CI 检出固定core.autocrlffalseWindows 贡献者需要为 SKILL.md 保持 LF 换行。ADR 0005 解读标签位置为什么要靠几何校验而不是人工审查核心权衡规则的存在 vs 规则的被执行。SKILL.md 第 6 节有两条规则箭头标签要离自己的连接线 6–10px连接线不能穿过非端点的盒子。但两条规则都没约束标签与节点的关系。由于绘制顺序固定为 背景→区域→箭头→标签→节点落在节点内部的标签遮罩会被节点填充盖住文字渲染成趴在节点边框上的碎片。结果9 个已发布示例architecture 和 swimlane 两种类型都带着这个问题上线了而所有现有关卡全部通过——lint-skin.py 检查颜色、字体和无障碍 SVG 契约self_check.py 检查 DOM 结构和动效契约没有一道关卡读取坐标。缺陷只在渲染时可见所以它在一式三份的变体审查中存活了下来。ADR 0005 的决策是标签位置获得明确规则SKILL.md 第 6 节规则 6不再依赖作者的目测。规则由 scripts/verify-geometry.py 强制执行解析rect坐标报告与文档中后声明的节点重叠的遮罩。判断标准是文档顺序而非单纯的重叠——遮罩盖住先绘制的区域容器是合法的遮罩完全在节点内部则是徽章。scripts/test-verify-geometry.py 携带对抗性测试覆盖正反两种极性被裁剪的遮罩必须报错合法情况必须放行。这个 ADR 传达的核心理念是只活在散文里的规则一定会带着坏示例发布。几何契约在仓库里以检查器 测试夹具的形式存在。当然它也有边界启发式基于形状节点 ≥60×40遮罩 20–120×8–14未来出现比例差异很大的新类型可能需要放宽阈值而 6–10px 的连接线间隙需要描边几何而非矩形判断目前仍是清单项。总结5 个 ADR 的共同设计哲学把 5 个 ADR 放在一起看能清晰地读出这个项目的设计哲学ADR权衡的核心落地方式0001 默认静态表达力 vs 安全可审查单控制器字节级校验0002 类型封顶扩展性 vs 分类法精简语义模式独立成轴0003 唯一自动播放动效 vs 无障碍精确边界 代码固化0004 字节上限精简 vs 可发现性路由面优先 CI 强制0005 几何校验规则存在 vs 规则执行检查器 对抗测试它们的共同点只有一个把设计意图翻译成可验证的约束。无论是 SHA-256、类型计数、字节上限还是矩形坐标每一条原则背后都有脚本在默默把关。对于任何想为 AI Agent 打造高质量开源技能skill的开发者来说这份架构决策记录本身就是一份极好的范本——决策文档不是写给流程看的而是写给未来每一个改动它的人看的。【免费下载链接】diagram-design29 editorial diagram types for Claude Code. Self-contained HTML SVG. No shadows, no Mermaid-slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考