Claude Code 内容结构图实战：信息架构与 Mermaid 流程图生成指南

1. 先想清楚Claude Code 里画 diagram 到底是拿来干嘛的Claude Code 这类命令行编程助手很多人第一个反应是“能不能帮我写代码、改代码、跑测试”。确实这是它最常用的场景。但实际用一段时间后你会发现真正让项目变得好维护、好交接的反而是文档和设计图。尤其是当项目文件变多、模块关系变复杂、或者要给别人讲清楚某块逻辑时一张 diagram 比几十行注释都管用。所以我看到 “Editorial diagram types for Claude Code” 这个主题时第一反应不是“它支持画图吗”而是“它能画什么类型的图画出来能不能直接用以及这些图在项目协作里究竟解决什么问题”。先说结论Claude Code 本身是一个终端里的 AI 编程助手主要交互方式是命令、文件读写和代码生成。它能不能画 diagram取决于你有没有提供合适的提示词、有没有让模型输出结构化文本以及你后续是不是用 Mermaid、Graphviz、PlantUML 或 Draw.io 这类工具把文本渲染成图。这篇文章不打算从零教你怎么安装 Claude Code而是把重点放在“editorial diagram types”这件事上。也就是说当你想让 Claude Code 帮你整理文档结构、梳理代码模块、规划页面信息架构、拆分任务流程时应该让它生成哪些类型的 diagram生成之后怎么验证怎么避免画出一堆花里胡哨但没法落地的图。如果你正准备用 Claude Code 做项目设计、文档梳理或者想在自己的工作流里加入图表辅助这篇文章会按流程拆开讲清楚。2. 先理解 “Editorial Diagram” 和普通技术图表的区别2.1 它不是架构图也不是流程图那么简单平时说到技术图表大家脑海里第一个冒出来的通常是“系统架构图”比如前端、后端、数据库、缓存、消息队列之间怎么连。这种图解决的是运行时调用关系属于 engineering diagram。但 editorial diagram 的重点不在“系统怎么运行”而在“内容怎么组织和表达”。它更接近编辑、内容策划、文档设计、信息架构领域使用的图表。举个容易理解的例子技术架构图用户请求 → Nginx → 后端服务 → MySQL这属于运行时路径。Editorial diagram一篇技术博客包含哪些章节章节之间是顺序关系、依赖关系还是并列关系各章节应该覆盖哪些关键问题这属于内容和编辑结构。Claude Code 这类模型在处理代码和文本任务时天然擅长梳理“内容之间的关系”所以“editorial diagram types”这个方向核心是让模型产出一张能表达内容结构的图而不是一张表达系统调用的图。2.2 模型生成图表时最常见的三种形式在 Claude Code 里画图最后落到文件里的大概率是这三种形式之一形式常见格式适合场景需要的外部工具Mermaid 时序/流程图.mmd 或嵌入 Markdown流程、状态、时间线支持 Mermaid 的编辑器、博客平台、VS Code 插件Graphviz DOT.dot节点关系、层级结构、依赖图Graphviz 命令行PlantUML.pumlUML 用例图、类图、部署图PlantUML 插件或服务器我自己用得最多的是 Mermaid。原因很直接Markdown 文档、GitHub、博客平台、VS Code 都支持渲染成本低Claude Code 生成准确率也高。Graphviz 适合节点数量多、需要精确控制布局的结构但语法相对硬核。PlantUML 对 UML 场景更专业不过多一层 Java 依赖。2.3 那 “editorial diagram types” 到底有哪些根据实际使用经验当你想让 Claude Code 帮你整理“内容”而不是“系统”时最常用的图类型有这些概念结构图展示一个主题下包含哪些子概念以及概念之间是包含、并列还是对照关系。内容流程图表达撰写、编辑、审核、发布的内容生产流程。信息架构图展示网站、文档、博客的页面层级和导航结构。心智图从主题向多个分支扩散适合做内容策划和选题拆解。对比图A 方案和 B 方案的差异、利弊、适用场景对比。时间线图展示内容推进的时间节点、版本计划、里程碑。任务拆解图把一个大型写作或开发任务拆成多个子任务并标注依赖顺序。这些图用在 Claude Code 里就是通过提示词控制模型输出对应类型的 Mermaid 文本。3. 真正开始实操前先检查你的环境和项目目录3.1 Claude Code 安装完成后先跑通最小命令如果你还没有装 Claude Code建议先确认几个基础条件再进入画图环节。虽然我不想把“安装教程”重复一遍但和环境相关的问题还是得提。因为我们在后面画图时需要在项目目录里创建.md文件并调用模型生成文本如果 Claude Code 没安装好、登录状态异常或目录权限有问题后面所有的步骤都会卡住。建议按这个顺序检查确认 Node.js 版本是否满足要求。确认 Claude Code 是否已经全局安装命令行里claude命令能否正常唤起。确认登录状态。很多报错不是因为模型能力而是订阅或账号访问权限问题。在目标项目目录里启动 Claude Code而不是在系统根目录或没有写权限的目录里启动。注意如果启动时提示该区域不可用、订阅访问被禁用先不要急着换网络环境或找其他绕行方案。先到官方支持页面确认账号状态、订阅类型和套餐适用条件多数情况下是账号配置问题。3.2 项目目录里先建一个 docs 文件夹画 diagram 之后会生成文件我不建议把图文件散落在代码根目录。一个比较稳妥的结构是这样my-project/ ├── src/ ├── docs/ │ └── diagrams/ ├── README.md └── .claude/在.claude目录里你可以放项目级配置比如系统提示词、常用指令或者团队共享的 skill。这样做的好处是Claude Code 在对话时能读取更多项目上下文生成的 diagram 会更贴合你的实际目录结构而不是输出一堆通用模板。如果你只是临时测试也可以跳过.claude配置直接在 docs 目录里对话生成。但从长期使用角度建议把“常用提示词”和“输出规范”放到配置里。3.3 准备好测试用的输入内容画 editorial diagram 和写代码还不一样它非常依赖输入内容。同一个提示词如果项目背景完全不同输出的图也会完全不一样。我一般会先在项目里放入三样东西一份 README 或者项目简介让模型知道整体背景。一份待整理的内容清单比如博客提纲、章节列表、模块说明。一份目标格式说明比如“用 Mermaid 输出一张流程图”。这样模型看到的不是“你会画什么图”而是“根据这些实际内容帮我把结构画出来”。4. 从最简单的 Mermaid 流程开始验证图和渲染链路4.1 先让 Claude Code 生成一个最基础的 Mermaid 流程不要一上来就让它画几十个节点的复杂结构。先用一个小样例验证两件事模型能不能正确输出 Mermaid 语法以及你的 Markdown 编辑器能不能正常渲染。假设我们在分析一篇技术博客的内容结构可以在 Claude Code 里输入帮我画一个 Mermaid 流程图主题是这篇博客的内容编辑流程节点包括确定主题、收集资料、搭建大纲、撰写初稿、交叉审校、发布上线。用 flow chart TD 方向节点用中文。只输出 Mermaid 代码块。正常情况下模型会输出类似这样的内容flowchart TD A[确定主题] -- B[收集资料] B -- C[搭建大纲] C -- D[撰写初稿] D -- E[交叉审校] E -- F[发布上线]4.2 这里为什么用 flow chart TD而不是其他方向Mermaid 支持很多方向值比如 TD 表示从上到下LR 表示从左到右。编辑类流程图通常比较线性TD 方向更符合阅读习惯。主题太多、步骤太长时可以用 LR 减少换行。但这不是唯一标准。当你画信息架构图时更可能会用flowchart LR因为页面层级在横向排列时更容易看出导航关系。如果你画的是时间线用 Mermaid 的timeline类型可能更直观。关键是判断标准。至少要让模型清楚“这张图服务于什么阅读场景”而不是让模型自己猜。4.3 图生成后必须检查三个地方第一语法是否合法。把 Mermaid 代码粘贴到支持的编辑器里如果没报错就说明语法没问题。第二节点标签是否有歧义。比如“交叉审校”这个节点到底是“审校文字”还是“审校代码”如果节点名称有歧义图就失去了表达力。第三连线方向是否符合真实流程。模型可能在语义理解上出错把前后顺序连反了。我见过不少例子Mermaid 语法完全正确渲染出来的图也漂亮但连线方向是错的因为它没有真正理解业务。所以图生成后不要只看“能不能渲染”要看“合不合逻辑”。5. 针对不同内容场景选择合适的 diagram 类型并写提示词5.1 场景一梳理文档结构用信息架构图很多人写技术文档写到一半发现层级混乱目录之间互相嵌套读者根本不知道从哪里切入。这时候适合用信息架构图。我常用的提示词模板是这样当前项目是一个使用 React 编写的前端组件库docs 目录下有安装指南、组件说明、主题定制、贡献指南、API 参考等文档。请用 Mermaid 的 flowchart 类型输出这个文档站点的信息架构图。要求体现首页、一级导航、二级页面之间的层级关系。不要输出额外解释。这类图重点在“层级和导航”。模型会尽量按父子关系连线。你可以在拿到结果后检查一级导航是否完整。每个二级页面是否都挂在正确的一级导航下。有没有遗漏跨模块跳转关系。5.2 场景二内容生产流程用泳道图或流程图如果你要表达多个角色共同参与的内容生产流程比如产品经理、研发、设计、编辑都要经过某个节点模型可以输出带分组的 Mermaid 流程图。示例提示词用 Mermaid 泳道图描述一个技术内容团队的每周内容生产流程涉及作者、编辑、技术审核、发布运营四个角色。从选题开始到发布后数据回收结束。流程节点不超过 12 个。用 flowchart LR通过 subgraph 按角色分组。泳道图的价值在于能一眼看出每个角色在哪个环节介入哪个环节阻塞时间最长哪个环节容易出现角色空缺。5.3 场景三对比方案优劣用左右结构或表格图很多人纠结“这篇文章应该用 A 方案还是 B 方案”如果你让 Claude Code 生成一个静态对比图它只能做简单罗列表达能力有限。我更推荐的做法是先让模型用 Markdown 表格把方案差异逐行列出来然后根据表格内容生成简洁的 Mermaid 决策流程图。这样既有数据判断依据又有流程方向。示例提示词对比“单仓库多包”和“多仓库”两种前端组织方式先用表格列出包管理、依赖更新、构建耗时、团队协作、误操作风险五个维度的差异。然后根据表格中哪一方占优输出一张 Mermaid 决策流程图帮读者快速定位应该选择哪种方案。5.4 场景四拆分内容任务用任务依赖图当你需要把一个大型内容项目拆成多个可并行、可串行的子任务任务依赖图比文字清单更直观。我喜欢用 Mermaid 的graph LR来画然后在节点里加上负责人或状态标记。把写一篇万字技术教程的任务拆解成 8 个步骤用 Mermaid 输出任务依赖图要求标出哪些步骤可以并行哪些步骤必须等待前序步骤完成。节点命名尽量是动词短语。5.5 场景五时间线和里程碑用 Mermaid timeline内容发布计划、版本排期、季度 OKR这些带时间属性的内容很适合用 Mermaid 的timeline类型。用 Mermaid timeline 展示一个开源项目从立项到发布 1.0 版本的季度里程碑包含四个阶段立项、功能开发、社区测试、正式发布。每个阶段列出两个关键节点。但是要注意Mermaid 的timeline类型在不同渲染器里支持程度不完全一致有些老插件可能不支持。如果渲染不出来先确认插件版本再考虑换成 flowchart。6. 把 diagram 生成从“一次性问答”变成“可复用 skill”6.1 为什么需要把提示词固化下来如果你只在 Claude Code 里临时画一次图那每次对话现场写提示词就够了。但如果你是一个团队的负责人或者需要每个月、每个项目都生成类似的内容结构图每次都重新写提示词就太浪费了。而且临时对话生成的图风格、节点命名、连线逻辑都不统一长期下来会变成另一种混乱。这时候就应该把“editorial diagram 生成规范”配置成 Claude Code 的 skill 或项目级提示词让模型在之后的对话里自动遵循。6.2 一个最简单的内容结构图 skill 配置示例在.claude/skills/目录下创建一个 skill 目录比如diagram-editor里面放一个SKILL.md文件内容可以写成# 内容结构图生成 Skill ## 适用场景 - 整理技术博客章节结构 - 梳理文档站点信息架构 - 拆分内容生产流程 - 对比不同方案并输出决策图 ## 输出要求 - 优先使用 Mermaid - 节点使用中文或与项目一致的语言 - 只输出 Mermaid 代码块不输出额外解释 - 节点数量控制在 20 个以内 - 流程图方向默认 flowchart TD ## 流程 1. 读取项目 README 或 docs 目录说明。 2. 确认用户需要的图类型。 3. 先用小规模节点生成初稿。 4. 检查节点是否重叠、连线是否有歧义。 5. 最终输出可渲染 Mermaid。这样做的好处是模型看到这个 skill 后会严格按照既定规则生成图。你不需要每次把同一套要求重复输入一遍。6.3 桌面版和 CLI 版在使用 skill 时略有差别Claude Code 目前既有命令行工具也有桌面客户端。命令行更适合开发者在终端里直接处理项目文件桌面版对不会用终端的人更友好而且能直接在界面里查看生成的文档。但不管哪个版本核心逻辑都是模型通过上下文理解项目结构再生成结构化文本。所以你真正要积累的不是某个版本的按钮位置而是一套“如何描述内容结构”的提示词和校验规则。7. 图生成完之后必须做一次“反向验证”7.1 用图反推原文检查信息是否丢失我自己的习惯是生成 diagram 后不急着放文档里而是先看着图说一遍思路再回看原始输入。如果看着图无法讲清楚原来的内容结构说明这张图只是语法正确但语义不够。比如你让 Claude Code 根据博客大纲画图生成的图节点不少、连线也完整但少了一个关键章节。这时候问题不在画图能力而是提示词里没有强调“不要遗漏大纲中的任何一级标题”。反向验证的步骤对照原始输入逐个节点找来源。检查是否有节点合并过度导致信息丢失。检查是否有模型自行添加的节点如果有判断是否合理。尝试只读图不看原文看能否理解结构。7.2 注意模型“编造节点”的问题模型生成 diagram 时出现少量“补全”是常见现象。比如你只给了 5 个章节它可能基于通用知识补出第 6 个章节。这个补全有时是合理的比如“你遗漏了 FAQ 章节”有时是多余的比如把无关的内容加了进来。处理方式很简单不要无条件接受模型补全的节点。要问一句“这个节点和你的输入内容有什么关系”。如果关系不明确就删掉。7.3 长图和复杂图的渲染限制虽然 Mermaid 能画很多节点但我不建议一张图超过 30 个节点。节点太多视觉负担重协作时也没人愿意细看。如果你发现内容结构很大拆分方式有两种按模块拆成多张图分别放在不同文档里。用首页图 子图的方式首页只显示一级节点点击进入二级结构。这两种方式都比“一张巨图”更实用。8. 踩过坑之后我建议你这样配置 Claude Code 的 diagram 工作流8.1 先定图类型再写提示词不要含糊地让模型“画一下”很多人最开始这样输入“帮我画一张图”。模型会迷茫最后输出一张大众模板图毫无针对性。正确方式是先想清楚这五个问题这张图的读者是谁。这张图要表达什么关系。用哪种图类型最合适。节点数量控制在多少。输出格式用什么。只要把这几个信息在提示词里说清楚模型输出质量会明显提升。我一般会把这样一段话放在每个画图任务的末尾要求只输出 Mermaid 代码块不要解释节点使用项目同语言最多 15 个节点连线方向必须符合实际前后顺序。8.2 建立“先写文字提纲再生成图”的习惯一个比较好的做法是先让 Claude Code 输出 Markdown 文字提纲比如章节列表、模块列表、流程步骤然后确认无误后再让模型根据这份提纲生成 diagram。这样做有两个好处文字提纲更容易审查错了直接改比改图快。模型在生成图时不会一边想内容一边想格式输出更稳定。操作上就是两次对话第一次根据项目 README 输出这份文档的章节提纲用 Markdown 列表。 第二次把上面的提纲转换成 Mermaid flowchart节点用一级标题连线用顺序关系。8.3 尽量把渲染检查放在本地编辑器里在 Claude Code 的终端界面里通常不会直接显示渲染后的图形。你需要把 Mermaid 代码复制到支持预览的地方查看。推荐的检查链路VS Code 安装 Markdown Preview Mermaid Support 插件。Typora、Obsidian 这类写作工具也支持 Mermaid。如果代码要提交到 GitHubGitHub 原生也支持部分 Mermaid 渲染。不要把“有没有渲染出来”当作通过标准还要在真实 Markdown 环境里检查一次。8.4 代码块语言标识必须写对如果 Mermaid 代码没有包在带mermaid标识的代码块里很多平台不会触发渲染。标准写法是mermaid flowchart TD A[开始] -- B[结束] 有些平台也支持mmd标识但mermaid是兼容性最好的。8.5 团队协作时把“图源文件”和“渲染图”一起保留如果团队里有人用 Draw.io有人用 Mermaid有人用 Figma最后很容易出现“图源文件只在自己电脑上”的问题。我的建议是文本型图源Mermaid、PlantUML、Graphviz直接保存在 Git 仓库方便版本管理。每次有结构变更时更新图源而不是只替换图片。如果必须导出 PNG在文档里同时保留一段 Mermaid 源码。这样别人能够复现、修改、对比历史版本。9. 常见问题排查生成图不对、渲染失败、结构混乱怎么办9.1 模型输出的 Mermaid 渲染失败遇到渲染失败不要先怀疑 Claude Code 模型能力大概率是语法层面出了问题。Mermaid 对中文字符、引号、特殊符号比较敏感。排查顺序检查是否所有节点标签都用[]或[text]包起来了。检查节点文本里是否包含未处理的双引号、括号。检查是否误用全角标点。检查连线符号是否是--而不是→或-的变体。检查代码块是否包裹完整。如果还是无法定位把 Mermaid 代码复制到 Mermaid Live Editor 在线编辑器里它会给出更具体的语法错误提示。9.2 生成的图缺少关键节点这通常不是模型“不会画”而是你的提示词没有明确列出关键内容。模型会优先选择它认为重要的信息但它的判断不一定等于你的判断。解决办法在提示词里直接列出必须包含的节点清单。示例必须包含以下节点用户注册、权限校验、内容发布、审核通知、失败重试。其他节点可以省略。9.3 节点很多但逻辑很乱如果节点超过 30 个图基本很难一眼看懂。此时建议拆图而不是继续调整布局。拆图原则按层级拆主流程一张子模块单独一张。按角色拆每个角色存在独立泳道子图。按阶段拆不同阶段在不同文档里维护。9.4 Claude Code 生成的 diagram 不支持目标平台有些图类型在 GitHub 上不支持比如部分 Mermaid 的timeline旧版本不支持。生产环境使用前先在目标平台实测一次不要等文档提交上去才发现渲染失败。稳妥写法是优先使用基础flowchart和sequenceDiagram这两种兼容性最好。10. 从“生成一张图”到“形成一整套内容图表体系”10.1 不要只生成一次要持续维护很多技术项目刚开始有设计图随着代码演进文档和图表的维护就断了。等到新成员加入才发现信息架构已经和代码实现完全脱节。Claude Code 的价值不止在于帮你画一张图而在于你每次改动代码或文档结构时可以触发它更新对应 diagram。维护思路把 diagram 图源文件放在和代码同仓库的 docs 目录下。在 CI 或本地脚本里简单校验 Mermaid 语法。当文档目录结构变化时重新生成一次信息架构图。人工 review 时检查模型对变化的理解是否正确。10.2 把常见 diagram 类型固化为团队模板团队协作时每个人对“流程图”“结构图”的理解都会有区别。为了不出现“UI 设计师画一种图后端工程师画另一种图”的情况建议团队内部定义一套 diagram 类型模板。模板里可以固定这些内容图源文件放在哪个目录。用什么图类型表达层级关系。用什么图类型表达流程关系。用什么图类型表达对比关系。节点命名规范。是否允许自行添加节点。这些规则不一定要很复杂但需要能统一表达方式。10.3 最终还是要回归“阅读者视角”无论生成多少种 diagram最终目的都是帮助人更快理解内容。所以每张图生成后我都会问自己一个问题如果我是第一次接触这个项目看到这张图能不能在 30 秒内抓住主要结构如果能这张图就合格了。如果不能问题可能出在节点命名、连线逻辑甚至图类型选择上而不是渲染效果好不好看。11. 一些更进阶的用法让 Claude Code 结合目录生成信息架构图11.1 用项目目录直接驱动 diagram 生成Claude Code 能读取当前项目目录结构所以你可以不手动输入所有章节而是让它扫描目录后生成信息架构图。示例提示词请读取 docs 目录下的所有 .md 文件依据文件之间的目录层级和链接关系生成一张 Mermaid 信息架构图。不需要列出每个文件内的标题只需要展示目录层级。这种用法的好处是图能紧跟项目真实变化不容易遗漏文件。但要注意Claude Code 对目录的读取范围依赖于用户授予的权限。如果发现它没有读取到某个目录先检查目录权限和路径是否正确。11.2 用一张总览图关联多张子图如果项目很大一张图画不下可以让 Claude Code 先生成总览图再为每个重要模块生成子图。总览图通常只画一级节点和模块间关系flowchart TD A[文档首页] -- B[快速上手] A -- C[核心概念] A -- D[API 参考] C -- C1[状态管理] C -- C2[插件机制]子图再对每个模块单独展开。这是目前我觉得最适合大型项目的做法。11.3 用 diagram 辅助代码阅读和重构虽然文章重点在 editorial diagram但这类图也能反哺代码理解。当你接手一个陌生项目时可以先让 Claude Code 根据代码目录生成“模块关系图”再根据模块职责生成“内容结构图”。这样既能理解系统运行逻辑也能理解项目文档结构。两者结合才是完整的项目认知。12. 收尾真正该留意的不是功能列表而是内容结构如果你只是临时需要一张简单的流程图让 Claude Code 直接生成就行不需要额外准备太多配置。只要提示词清楚、输出格式明确、渲染环境正常几分钟就能搞定。但如果你想把 diagram 持续用在内容策划、文档维护、团队协作里就要认真考虑三件事图类型是否匹配表达目的。图源文件是否纳入版本管理。模型生成后是否经过人工语义校验。踩过几次之后我越来越确信很多 diagram 问题不是模型不能画而是我们没告诉它“画给谁看、表达什么关系、遵守什么格式”。把这三件事写在提示词里Claude Code 生成的 editorial diagram 就有机会从“能渲染”升级为“能看懂、能维护、能复用”。如果你准备在自己项目里试建议先用一个小型 docs 目录做实验生成一张信息架构图再生成一张流程对比图分别跑通渲染和修改流程。能稳定复现之后再逐步扩展到团队级别。