先说说最近在项目文档里折腾架构图的感受。以前画流程图要么打开画图工具手动拖框要么用在线工具导出图片再贴到文档里改一次需求就得重画一遍图多了以后根本不知道哪张是最新版本。后来尝试让 Claude Code 直接基于代码和需求描述生成图表发现只要把图表类型说清楚它就能直接输出标准的 Mermaid 代码粘贴到 Markdown 里就能渲染文档更新后重新生成一遍即可维护成本一下子降下来。这篇文章会围绕 Claude Code 的 diagram types 展开既要讲清楚有哪些图表类型也要带大家实际跑一遍安装、配置、生成图表的完整流程。如果你正打算用 Claude Code 来画架构图、时序图、类图或者想把它接入自己的模型 API 使用这篇文章应该能帮你少踩不少坑。1. 为什么要在 Claude Code 里用图表梳理架构与文档1.1 从文档协作痛点说起技术文档里最让人头疼的往往不是文字而是图表。文字写错了可以随时改但一张架构图如果画错了通常意味着整个模块关系、调用链路、数据流向都要重新梳理。更麻烦的是传统画图方式有几个固定痛点图表文件是二进制或私有格式无法用 diff 查看具体改动。人的精力和时间有限代码更新了但图没更新导致“图实不符”。团队协作时每个人用不同工具画同一张图风格差异很大。画图工具导出的图片体积大代码仓库不好维护。这些问题在 Claude Code 这类 AI 编码工具出现之后有了新的解决思路让 AI 直接生成“文本化图表”也就是用代码来表示图。文本化图表放在 Markdown 或代码仓库中既能被 Git 追踪又能根据文档内容随时重新生成真正做到了“图即代码”。1.2 Claude Code 的文本化图表能力Claude Code 是 Anthropic 推出的命令行 AI 编程助手它可以在终端里读取项目文件、理解代码结构并根据用户指令完成代码修改、测试、文档生成等任务。图表生成是它很实用的能力之一尤其是处理大型项目时它能快速分析目录结构和代码之间的依赖关系然后用文本化图表语言输出可视化结果。在 Claude Code 的输出体系中最常见的图表输出格式就是 Mermaid。Mermaid 是一种基于文本的图表描述语言语法简单支持多种图表类型可以直接嵌入 Markdown 文档中也可以通过 Mermaid Live Editor、VS Code 插件等工具渲染成图片。Claude Code 推荐使用 Mermaid 而不是直接生成图片原因主要有三点文本可审查你可以在提交文档前人工查看图表逻辑是否正确。版本可追踪图表代码和普通代码一样进入 Git 历史后可以做 diff。迭代成本低需求变化后让 Claude Code 重新生成一段 Mermaid 代码即可。1.3 常见的 diagram types 有哪些Claude Code 覆盖的图表类型基本沿用了主流文本图表语言的类型体系。围绕“Editorial diagram types”这个场景也就是面向文档编辑、架构说明、设计文档、知识整理等场景常用的类型包括Flowchart流程图适合描述业务流程、判断分支。Sequence Diagram时序图适合描述系统间调用顺序、消息传递。Class Diagram类图适合描述面向对象设计中的类、接口和关系。State Diagram状态图适合描述对象状态流转。ER Diagram实体关系图适合数据库表设计。Gantt Diagram甘特图适合项目排期和任务安排。Pie Chart / Quadrant Chart饼图/象限图适合数据分布和策略分析。Mindmap思维导图适合梳理知识结构和想法。这些类型在实际项目中并不冲突而是互补的。比如写作技术方案时先用思维导图整理思路再用流程图描述核心流程最后用类图和 ER 图补充技术细节整体文档就会非常完整。2. 环境准备安装 Claude Code在使用 Claude Code 的 diagram types 之前需要先把 Claude Code 本身跑起来。安装方式和普通 Node.js 工具差不多但根据你的使用习惯可以选择命令行、桌面版或 IDE 插件三种形态。2.1 命令行安装Claude Code 的官方命令行工具通过 npm 分发包名是anthropic-ai/claude-code。安装前先确认本机已经安装了 Node.js 和 npm。node -v npm -v然后使用 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果你是 macOS 用户也可以使用 Homebrew 安装brew install --cask claude-codeLinux 服务器上通常走 npm 安装流程CentOS 等系统只需要确保 Node.js 版本满足要求然后执行同样的npm install -g命令即可。安装完成后在项目目录里执行claude就能进入交互式命令行。2.2 桌面版如果不想一直面对终端可以安装 Claude Code 桌面版。桌面版本质上是把 CLI 封装成了图形界面适合更习惯鼠标操作的同学。桌面版的下载地址可以通过 Claude Code 官网或产品内置的升级提示获取安装后登录账号即可使用。桌面版和命令行版使用同一个项目工作目录也能读取同样的模型配置。如果你之前已经用命令行配置好 API Key桌面版通常会自动识别已有配置不需要重复设置。2.3 VS Code 集成对于日常写代码的开发者把 Claude Code 集成到 VS Code 里会更顺手。VS Code 安装 Claude Code 插件后可以在编辑器侧边栏直接打开 Claude Code 面板选择文件、查看 diff、执行命令生成图表后也能直接在编辑器中预览。VS Code 插件的安装很直接打开 VS Code进入扩展市场。搜索 Claude Code。安装官方插件。重启 VS Code在侧边栏或命令面板中启动 Claude Code。2.4 初始化登录安装完成后第一次运行时需要登录 Claude 账号完成认证。在终端输入claude按提示跳转到浏览器授权即可。如果你的网络环境无法访问 Claude 官方服务则需要确认当前账号和网络策略是否满足使用条件这类问题一般需要联系企业管理员或使用官方支持的网络环境解决绕过网络限制是不安全也不合规的。如果你不使用 Claude 官方账号而是想接第三方模型 API可以跳过登录直接配置环境变量。具体方法会在后面的章节详细说明。3. Editorial diagram types核心图表类型详解这一节是文章的核心。Claude Code 生成图表时并不局限于某一种格式而是会根据你的描述选择最合适的图表类型。我们要重点掌握的是 Mermaid 体系下的各类型语法因为它在 Claude Code 输出中最常用也最适合嵌入文档。3.1 Mermaid最推荐的“图即代码”Mermaid 的定位是“让图表和文档一样易于编写和修改”。它不需要专业绘图工具只要会写 Markdown就能写出流程图。Claude Code 之所以默认输出 Mermaid是因为它可以原样嵌入 Markdown也可以与现有的文档工作流融合。3.2 Flowchart 流程图流程图是使用频率最高的图表类型适合表达业务流程、程序逻辑和状态判断。flowchart TD A[开始] -- B{是否需要画图} B -- 是 -- C[调用 Claude Code] B -- 否 -- D[直接写文档] C -- E[生成 Mermaid 代码] E -- F[嵌入 Markdown] D -- G[结束] F -- G在 Claude Code 中你可以直接说“请用 flowchart 描述用户下单的流程”它会自动生成类似上面的代码。如果希望它同时给出流程图和说明文字可以在指令中增加“分别输出 Mermaid 代码和步骤说明”。3.3 Sequence 时序图时序图适合描述对象之间的消息传递顺序在微服务调用、接口联调、登录认证等场景非常有用。sequenceDiagram participant 客户端 participant 网关 participant 订单服务 participant 数据库 客户端-网关: 创建订单请求 网关-订单服务: 校验 token 并转发 订单服务-数据库: 插入订单记录 数据库--订单服务: 返回订单 ID 订单服务--网关: 返回创建结果 网关--客户端: 返回订单详情时序图的价值在于可以把一次完整的调用链路讲清楚。Claude Code 读取项目代码后能根据 Controller、Service、Mapper 的实际调用关系生成时序图比人工阅读代码再画图高效得多。3.4 Class 类图、State 状态图、ER 图类图描述类与类之间的关系适合架构设计和面向对象建模。classDiagram class UserService { findById(Long id) User create(User user) Boolean } class UserRepository { findById(Long id) User save(User user) void } UserService -- UserRepository : 注入依赖状态图描述对象的生命周期状态迁移。stateDiagram-v2 [*] -- 待付款 待付款 -- 已付款: 支付成功 已付款 -- 已发货: 发货 已发货 -- 已完成: 确认收货 已完成 -- [*]ER 图描述数据库表关系。erDiagram USER ||--o{ ORDER : creates ORDER ||--|{ ORDER_ITEM : contains ORDER_ITEM }o--|| PRODUCT : refers如果你需要 Claude Code 根据数据库建表语句自动生成 ER 图可以直接把 SQL 文件路径告诉它它会分析表结构并输出对应的 Mermaid 代码。3.5 Gantt、Pie、Quadrant、Mindmap 等辅助图表除了技术设计类图表Claude Code 也能输出项目管理、数据分析和思维整理类图表。gantt title 项目阶段规划 dateFormat YYYY-MM-DD section 需求分析 需求评审 :a1, 2025-01-01, 7d 原型设计 :a2, after a1, 5d section 开发测试 功能开发 :b1, after a2, 15d 联调测试 :b2, after b1, 7dpie title 故障原因分布 网络超时 : 45 代码异常 : 35 配置错误 : 20mindmap root((项目文档)) 架构设计 流程图 时序图 类图 数据设计 ER 图 状态图 项目管理 甘特图 饼图象限图在战略分析、优先级判断时很有帮助Claude Code 也可以输出 Mermaid Quadrant Chart。不过这类图表在不同渲染器里支持程度有差异使用前最好先确认文档平台是否支持。3.6 ASCII 架构图与 PlantUML/GraphVizMermaid 并不是唯一选择。如果你的文档环境不支持 Mermaid 渲染或者项目规范里指定使用其他图表语言Claude Code 也能输出 ASCII 架构图、PlantUML 和 GraphVizDOT代码。ASCII 架构图适合放在代码注释或轻量文档里特点是不依赖渲染器任何环境下都能看懂---------------- ---------------- | Web 前端 | ---- | API 网关 | ---------------- ---------------- | v ---------------- | 业务微服务 | ----------------PlantUML 的语法也很有代表性如果你的团队原本就在用 PlantUML可以让 Claude Code 优先输出 PlantUML 格式。GraphViz 则适合复杂依赖关系图表达能力更强但语法门槛也高一些。实际项目中建议优先使用 Mermaid因为它生态最活跃、渲染器最多、Claude Code 也最擅长。4. 实战让 Claude Code 根据代码和需求生成图表理论讲完下面用一个实际例子演示如何让 Claude Code 生成图表。这个例子模拟一个简单的订单服务项目目标是生成包含流程图、时序图和 ER 图的文档。4.1 准备示例项目结构首先在本地创建一个简单项目目录mkdir order-demo cd order-demo mkdir -p src/main/java/com/example/order/{controller,service,repository}示例项目中包含三个核心层Controller接收 HTTP 请求。Service处理业务逻辑。Repository访问数据库。为了节省篇幅这里只写两个最小文件// 文件路径src/main/java/com/example/order/controller/OrderController.java package com.example.order.controller; import com.example.order.service.OrderService; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/orders) public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService orderService; } PostMapping public String createOrder(RequestBody String orderReq) { return orderService.createOrder(orderReq); } }// 文件路径src/main/java/com/example/order/service/OrderService.java package com.example.order.service; import com.example.order.repository.OrderRepository; import org.springframework.stereotype.Service; Service public class OrderService { private final OrderRepository orderRepository; public OrderService(OrderRepository orderRepository) { this.orderRepository orderRepository; } public String createOrder(String orderReq) { // 简化逻辑真实项目中这里会做校验、落库、发消息 orderRepository.save(orderReq); return order created; } }// 文件路径src/main/java/com/example/order/repository/OrderRepository.java package com.example.order.repository; import org.springframework.stereotype.Repository; Repository public class OrderRepository { public void save(String orderReq) { System.out.println(保存订单 orderReq); } }这个项目的调用链路比较清晰Controller 调用 ServiceService 调用 Repository。我们可以让 Claude Code 直接读取项目结构生成一张类图和一张时序图。4.2 用自然语言指令生成 diagram在项目根目录启动 Claude Codeclaude然后输入如下指令请分析当前项目的代码结构并生成以下内容 1. 一张 classDiagram体现 OrderController、OrderService、OrderRepository 之间的依赖关系。 2. 一张 sequenceDiagram描述一次创建订单请求从 Controller 到 Repository 的调用过程。 3. 每张图都输出 Mermaid 代码并简单说明代码含义。Claude Code 会读取项目文件然后输出类似下面的结果classDiagram class OrderController { -OrderService orderService createOrder(String orderReq) String } class OrderService { -OrderRepository orderRepository createOrder(String orderReq) String } class OrderRepository { save(String orderReq) void } OrderController -- OrderService OrderService -- OrderRepositorysequenceDiagram participant 调用方 participant OrderController participant OrderService participant OrderRepository 调用方-OrderController: POST /orders OrderController-OrderService: createOrder(orderReq) OrderService-OrderRepository: save(orderReq) OrderRepository--OrderService: 保存完成 OrderService--OrderController: 返回 order created OrderController--调用方: 返回 HTTP 200这个过程中不需要任何编码只需要把指令描述清楚Claude Code 就能生成符合项目实际结构的图表。4.3 将生成的图表嵌入 Markdown 文档生成 Mermaid 代码后我们可以创建一份技术文档把图表嵌进去# 订单服务技术说明 ## 类关系说明 mermaid classDiagram class OrderController { -OrderService orderService createOrder(String orderReq) String } class OrderService { -OrderRepository orderRepository createOrder(String orderReq) String } class OrderRepository { save(String orderReq) void } OrderController -- OrderService OrderService -- OrderRepository如果你的文档平台支持 Mermaid这段代码会直接渲染成图片。如果使用 VS Code可以安装 Markdown Preview Mermaid Support 插件在 Markdown 预览中直接查看图表。 ### 4.4 导出与渲染 不同场景对图表输出格式要求不同 - 博客文章直接把 Mermaid 代码放入 Markdown 即可CSDN 等平台如果支持 Mermaid 会自行渲染。 - 离线文档可以通过 Mermaid CLI 将代码转为 SVG 或 PNG。 - 团队内部 Wiki需要确认 Wiki 系统是否支持 Mermaid 语法。 用 Mermaid CLI 转换图片的示例命令如下 bash npx mermaid-js/mermaid-cli -i input.mmd -o output.png需要注意的是Mermaid CLI 依赖浏览器环境第一次运行可能会下载 Playwright 相关依赖耗时较长。如果只是为了自己看效果直接用在线 Live Editor 更快。4.5 配合 Skill 固化图表生成规范Claude Code 支持通过 Skill 来沉淀团队规范和自定义能力。你可以创建一个 skill让 Claude Code 在生成图表时自动遵守团队约定比如默认使用中文注释。类图中的方法签名保留参数和返回值类型。时序图统一用参与者 - 参与者的箭头格式。生成图表后必须同时输出说明文字。这样团队成员在使用 Claude Code 时不需要每次重复描述规范生成结果也能保持一致性。Skill 的目录结构通常是一个带说明文件的文件夹放在 Claude Code 指定的配置目录中即可。具体路径随版本不同会有差异建议在模型内部查看claude skill相关命令帮助。5. 进阶接入第三方大模型与配置切换很多同学没有 Claude 订阅或者希望把 Claude Code 接到 DeepSeek、本地模型等其他服务上。这部分是配置重点。5.1 设置 API Key 的两种方式Claude Code 读取模型配置主要有两种方式方式一环境变量。在启动 Claude Code 前设置 API Key 和接口地址。export ANTHROPIC_AUTH_TOKEN你的APIKey export ANTHROPIC_BASE_URLhttps://你的模型服务地址 claude方式二在 Claude Code 交互界面中设置。如果你进入交互界面时没有登录可以直接在命令面板中配置大模型 API Key。不同版本菜单名称会不同但大致路径是“设置 - 模型配置 - 填写 API Key”。需要特别提醒不要把 API Key 硬编码到项目文件里建议放到本地环境变量或密钥管理工具中避免提交到 Git 仓库造成泄露。5.2 接入 DeepSeek 或本地模型时要注意什么近年来很多国产模型和开源模型都提供 OpenAI 兼容接口Claude Code 要接入这些模型通常需要配置一个兼容层或指定接口地址。接入 DeepSeek 时一个常见报错是deepseek-v4-pro is not a model this version of claude code recognizes这个报错的意思是当前 Claude Code 版本不认识你配置的模型名称。出现这个问题的原因通常是模型名拼写错误或者把模型的对外名称直接写成了内部名称。解决方法如下确认模型服务商提供的准确模型 ID不要凭记忆填写。检查 Claude Code 版本过老版本可能不支持自定义模型列表。查看厂商文档确认是否需要在请求参数中指定 model。更新 Claude Code 后重试。npm install -g anthropic-ai/claude-codelatest至于本地模型例如 Qwen 系列 27B 参数的模型能不能用于 Claude Code答案是“需要测试”。本地模型通常通过 vLLM、Ollama、LM Studio 等工具暴露为 OpenAI 兼容接口然后把这个接口地址配置到 Claude Code 的 base URL 中。不过 Claude Code 本身对工具调用、上下文长度和指令遵循能力要求较高如果本地模型在这些方面表现一般可能导致生成的图表代码质量不稳定。建议先用小任务测试再决定是否在生产环境中使用。5.3 使用 ccswitch 管理多套配置如果你需要在 Claude 官方、DeepSeek、本地模型之间频繁切换可以借助 ccswitch 这类配置切换工具。ccswitch 的作用是将多套 API 配置统一管理切换时只需要修改一个符号链接或配置文件不需要每次手动改环境变量。ccswitch 的典型使用流程在配置目录中定义多个 profile。每个 profile 包含 base URL、API Key、model 等信息。使用命令行命令切换到目标 profile。重启或重新启动 Claude Code。使用这类工具时要注意它只是一个配置管理工具不会改变模型本身的能力。切换后如果出现模型不识别、接口报错仍然需要检查模型服务商的实际配置。6. 常见问题与排查思路问题现象常见原因解决思路claude: command not foundnpm 全局目录不在 PATH 中或安装失败检查 Node.js 版本重新执行全局安装确认 npm 全局 bin 目录已加入 PATHyour organization has disabled claude subscription access for claude code企业账号策略禁止使用 Claude Code联系组织管理员开通权限不要自行绕过组织策略deepseek-v4-pro is not a model this version of claude code recognizes模型名称配置错误或版本过旧核对模型 ID更新 Claude Code确认第三方接口是否正确映射启动时报 529 类错误服务端限流或容量不足稍后重试降低请求频率或检查账号配额Mermaid 代码渲染空白代码缩进错误、括号不匹配或渲染平台不支持该图表类型先用 Mermaid Live Editor 测试修正语法后再嵌入文档生成的图表信息过少项目上下文不足用/read明确指定要分析的文件或在指令中补充业务背景网络提示所在地区不可用当前网络/账号策略不支持访问确认官方支持范围使用企业授权环境不建议采用任何规避手段排错时有一个通用思路先判断是“环境问题”还是“配置问题”还是“模型问题”。环境问题优先检查版本、网络和服务状态配置问题重点检查环境变量、API Key、model 名称模型问题则需要对比不同模型在同一指令下的输出差异。7. 最佳实践与工程建议7.1 图表与代码保持同步生成图表只是第一步真正困难的是让图表长期保持有效。建议把图表代码和源文件放在同一个仓库中并在代码变更时同步更新。如果预算允许可以在 CI 中增加一个简单的检查任务用 Mermaid CLI 验证所有.mmd文件能否正常解析避免文档平台突然渲染失败。7.2 版本管理和 AI 生成规范与普通代码一样AI 生成的图表也要做版本管理和人工审查。建议一个图表对应一个.mmd文件或集中放在docs/diagrams目录。在文档中标注“由 Claude Code 生成最后更新日期”。提交前检查节点命名、箭头方向、分组逻辑是否准确。让 Claude Code 生成图表时同时输出一个简单的文字说明方便 review。7.3 安全边界与最小权限Claude Code 读取项目文件时会有权限控制。生产环境中使用时要遵循最小权限原则只授权它访问必要的目录不要让 AI 在未授权情况下修改关键配置或执行破坏性命令。涉及密钥、证书、生产数据库地址等敏感信息时不要把它们写进会被 AI 读取的文档中。7.4 性能与可维护性当项目文件非常多时Claude Code 分析速度会变慢。建议在指令中明确指定要分析的文件范围而不是让它扫描整个仓库。对于大型项目可以先生成类图、调用链再逐步细化到每个模块避免一次输出过多导致上下文溢出。维护方面优先使用 Mermaid 这类文本化格式不要直接把图片提交到仓库。图片无法 diff也无法自动验证一旦需求变化旧图就失去了维护价值。8. 总结与后续学习方向这篇其实说得比较细了。从 Claude Code 的安装开始到 Mermaid 体系下的各类 diagram types再到实际生成图表、配置第三方模型以及常见的报错处理核心就是想让大家明白一件事在 Claude Code 里画图不要把它当成传统画图工具而要把图表当作文档中的一段可维护代码。如果你平时主要写技术方案、做架构设计下一步可以在实际项目里多试几种图表类型尤其是 classDiagram 和 sequenceDiagram这两个在代码评审和模块梳理时特别实用。如果你刚接触 Claude Code建议先从最简单的 flowchart 开始让 AI 基于一个小模块生成流程图再逐步扩大到全项目。图表生成只是 Claude Code 的其中一个亮点它还能做代码补全、单测生成、重构建议和日志分析。后面我也会继续整理 Claude Code 与 IDE 集成、本地模型接入、团队 Skill 落地这些方向的内容。如果这篇文章对你有所帮助可以收藏备用也欢迎在评论区分享你用它生成图表时遇到的奇怪报错大家一起避坑。