diagram-as-code 解决的是文件格式问题，不是维护问题。文本图表仍然可能变旧、误导人，或者根本无法审阅。工作流必须说明这张图为什么存在、谁负责，以及哪些工程改动需要更新它。
每张图只支持一个决策
在源码旁边写一句简短的目的说明。“展示公共 API 的信任边界”是可以验证的；“系统架构”就太宽泛了，容易把所有组件都塞进一张图里。
根据要回答的问题选择合适的图类型。流程图适合决策，时序图适合交互顺序，ER 图适合数据关系，甘特图适合轻量计划。不要为了少几个文件就强行把所有视图都放进同一种符号里。
把源码放在相关文档旁边
如果一张图解释的是某个 API，就把源码放在 API 文档附近，而不是放在远处的设计目录里。物理上接近，更容易让所有权和审阅发生。给源码起一个可预测的名字，并且只有在发布平台不能直接渲染 Mermaid 时，才导出渲染产物。
如果同时提交源码和导出的 SVG，一定要说明哪个文件才是权威版本。生成产物不应该手工修改。
定义更新触发条件
一份有用的 Pull Request 检查单，应该写清楚具体触发条件：
- 新增、删除或变更某个服务的所有权。
- 信任边界或数据去向发生变化。
- API 调用变成异步，或者多出失败分支。
- 数据库关系的可选性或基数发生变化。
- 文档中声明的交付里程碑发生变化。
这种写法比让每个 PR 作者笼统地“如果需要就更新文档”更有效。
先审语义，再看外观
审阅者应该先确认节点、关系、顺序和标签是否和实现一致，再看布局和颜色。一个视觉上很漂亮但基数错了的图，实际上是有害的，因为读者往往会相信视觉结构。
让变更足够小，方便用文本 diff 审阅。稳定的节点 ID 和“一行一句话”能减少无关噪音。如果一次格式化会把整文件重写，应该把格式化和语义变更分开。
验证发布运行时
不同 GitHub、文档生成器和嵌入式编辑器里的 Mermaid 版本和安全策略都可能不同。新的语法应该在最终渲染器里测试，或者明确标注所需版本。若图表必须通过严格安全策略，最好避免交互链接和原始 HTML。
使用 Mermaid 编辑器 做本地迭代和导出，但应把仓库里的源码和代码评审流程当作真正的长期资产。