写技术文档最怕啥？配架构图。严格来说Visio 太重，手绘截图塞进去，俩月后代码早改了图还停在上古版本，后来人照着走直接迷路。我前阵子被这破事折腾够呛，转去用 Mermaid——一种拿文本定义图形的语言，basically 就是把图当 code 写。

最戳我的是它能进 Git。graph TD; A–>B 这种写法，diff 一拉谁动了箭头清清楚楚，图跟代码同步过期的问题算根治了。CI 挂个渲染，PR 里直接看图，reviewer 省劲。

常用的没几个：flowchart 画流程，sequenceDiagram 画时序，classDiagram 画类关系。我有时让 AI 吐 Mermaid，服务调用链几分钟捋顺，比白板乱划强。

门槛也低，GitHub、VS Code、Notion 都原生认，零安装。我现在真回不去截图时代了，你们有啥私藏玩法也来唠两句。

把图当 code 写这路子没问题，但"图跟代码同步过期算根治了"这话我得泼点冷水。Mermaid 干的事只是把改图的成本压到和改代码一样低，真正逼着人去更新的，是你们挂的那个 CI 渲染——图进了 build，render 不出来 PR 就红，人才会动。光把 .md 推进仓库、本地能看，该忘还是忘。

给你补几个踩过的坑。

版本问题最阴。GitHub 后台跑的 Mermaid 是固定版本的，本地 VS Code 插件往往更新。见过不止一次，本地 flowchart 画得好好的，推上去 GitHub 直接渲染失败，根因是新语法老版本不认。文档流水线里最好用 mermaid-cli（mmdc）锁个版本跑，别赌两边一致。

AI 吐出来的 Mermaid 十张里三四张语法是坏的。常见毛病：标签里带括号或中文顿号不包引号、把 end 当节点名撞了 flowchart 关键字、箭头方向写反。让 AI 生成之后一定过一道 mmdc 校验，能 render 才算数，不然 reviewer 点开是个裂图，比没图还糟心。

你那句"谁动了箭头 diff 一拉清清楚楚"，小改动确实爽，但往 graph 中间插一个节点，整个块会作为一个 hunk 整段变掉，行级 diff 其实是糊的。一个图单独存一个 .md 文件、别都塞进大 README，diff 才干净。

Mermaid 真正治不了的，是"该画没画"。再顺手的工具也拦不住人懒得动手，这事儿 CI 管不着。

楼主把这帖子叫做"把脑子画出来"，这说法让我停了一下。我们总想用整齐的箭头去兜住一条不断改道的河，可 graph TD 落笔的那一刻，念头早已流向下游了。能把这种痕迹留在 git 里，倒像是给易逝之物立了座温柔的小纪念碑。

进 Git 能 diff 这点稳！之前照着上古架构图走直接迷路，文本画图算治本了。AI 吐 Mermaid 我也试过，几分钟捋顺比白板强，冲就完了