当业务流程、状态机或系统交互用文字难以表达时…

需要展示跨部门/跨系统的业务流程、生命周期、状态机或消息序列时，用图表源文件（而非图片）记录行为，并随代码变更同步维护。

适用场景

解决思路

1. 先确定抽象层级再画图，并让记法匹配层级：业务层用 ArchiMate（跨部门、跨组织、多系统的流程、能力地图、TOGAF 风格视图，受众关注角色、服务、流程而非组件）；系统层用 PlantUML 行为图（系统内外的流程、状态机、序列图，即代码文档，比代码高一层）；代码层不画图（类与包结构由代码自身展示，IDE 按需生成比提交的图更新）。
2. 记法阶梯只决定记法和词汇，不决定工具：同一工具链可服务两个层级，因为 PlantUML 标准库已包含 ArchiMate 记法；仓库使用哪个工具在“源文件而非图片”一节中一次性确定。
3. 图表源文件必须是提交到版本库的文本，使用仓库已用的图表工具；若尚未确定，默认用 PlantUML（标准库丰富，含 ArchiMate）；若选择确实开放，询问负责人并推荐 PlantUML。渲染输出是派生物，过期的渲染要删除而不是留着误导。
4. 每个源文件只放一张图，以它所展示的流程命名，统一放在文档旁边的 diagrams 目录中。
5. 渲染需要仓库自有的工具（脚本、make 目标或构建步骤），由负责人搭建而非图的作者；缺少时告知负责人，绝不为了绕开缺口而改用托管平台恰好能内联渲染的记法。
6. 一条仓库命令渲染全部图；除非托管平台已能渲染仓库选定的源格式，否则渲染结果要提交。源文件变更时，在同一次变更中删除其过期渲染，并在索引中记录缺失的渲染直到重新生成。
7. 没有源文件的截图、导出图片或白板照片，视为所在文档的一个问题：没人能对它做 diff，也就没人会维护它。
8. 按读者带来的问题选择图的种类，一张图只回答一个问题：流程如何跨组织运行→ArchiMate 业务流程图；发生什么、按什么顺序、有哪些决策→活动图；这个东西可以处于哪些状态、什么驱动状态转移→状态机图；谁与谁在什么顺序下交换什么消息→序列图；这个领域存在什么以及如何关联→业务对象层级的概念图。回答两个问题的图两个都答不好，要拆分；需要自创符号图例的图说明它一次回答了太多问题。
9. 参与者只能是系统、角色、模块和业务对象；类、方法、函数留在代码里（见记法阶梯）。
10. 边承载事件或条件，用领域语言表达（如“payment confirmed”），绝不使用回调名；守卫条件可以命名配置键（配置键是契约面），但绝不命名方法。
11. 标题命名流程本身，绝不命名规格、阶段或计划；禁止交付叙事的硬规则同样适用于图表源文件内部，包括注释。
12. 在行为有差异的地方画出错误与异常路径，并画得可区分；对存在真实失败分支的流程只画快乐路径，是夸大的声明。
13. 把怪癖画出来，它们就是内容：无法离开的状态、对某个输入跳过某一步的流程——令人意外的分支正是这张图存在的价值。
14. 超过五张图时，在它们旁边放一个索引文档，作为从文件重建的派生产物：包含覆盖表（每张图展示什么、源文件、若提交则含渲染结果、状态）；每张图所描述的模块（作为漂移锚点，即图指向代码的唯一位置）；渲染命令（使索引同时成为构建说明）；按源文件列出的待渲染项（使缺失的渲染成为被跟踪的状态而非静默缺口）。
15. 改变流程的变更必须在同一次变更中更新对应的图表源文件：图是文档，文档是“完成”的一部分。渲染是图的编译步骤：源文件编辑会不可见地破坏语法，只有运行渲染才会暴露；作者在提交编辑前先渲染，若仓库流水线尚缺，本地一次性运行工具即可满足该检查。
16. 功能被移除时，一次变更要同时覆盖正文、图表源文件、索引行和已提交的渲染。没人愿意更新的图说明它回答的问题太大，沿独立变化的接缝拆分它。
17. 作者在画之前对照代码核实每个框、箭头和守卫条件；推断而非确认的流程要在嵌入文档中图旁标注为推断，绝不静默画成事实。
18. 评审者对照行为阅读图，并评审源文本而非图片：源文本才是下一位编辑者要改的东西。
19. 图表源文件像正文一样会漂移，要加入每一次遗留系统梳理活动：由梳理活动将图表源文件与嵌入它们的文档一起做基线。
20. 一张图与其周围正文对每个事实只有一个归属：正文说明流程为何存在、要注意什么，图展示流程，两者都不逐步复述对方。
21. 渲染前先运行仓库的渲染命令或本地一次性运行工具，以捕获源文件语法错误。

适用边界 · 注意事项

• 不要为了装饰而画图：三四个步骤的线性流程用编号列表即可，用图复述它是摆设。
• 不要画从数据生成的图表（指标、趋势），也不要画实现结构（类、包、方法），后者被行为规则禁止。
• 不要使用没有源文件的截图、导出图片或白板照片，它们无法 diff、无法维护。