在日常研发和架构设计工作中，“画图”常常是一件既重要又费时的事情：
既要体现系统全局结构，又要让组件、数据流、云服务、安全边界一目了然，还得兼顾美观与统一风格。很多团队最后要么依靠某个“画图侠”同学，要么堆砌出一张风格凌乱、难以维护的架构图。

随着 AI 工具的发展，“让 AI 帮我画一张架构图”正在从想法变成现实。
本文围绕一个非常实用的工具——Architecture Diagram Generator，讲清楚它解决了什么问题、如何使用、底层是怎么设计的，以及在实际工程中的落地方式和注意事项。

---

一、为什么需要一个“AI 架构图生成器”？

1. 架构图的痛点

在真实项目中，和架构图相关的常见痛点包括：

• 产出成本高：需要熟悉系统细节的人来画，且要掌握专业绘图工具（如 draw.io、Visio、Excalidraw 等），沟通成本高、产出慢。
• 难以保持最新：代码变更频繁，架构图往往半年甚至一年不更新，一线开发不再信任图上的信息。
• 风格难统一：不同人画图风格、颜色、布局都不同，很难保证跨团队的一致性和专业感。
• 协作与分享割裂：图文件分散在各种网盘、邮件、Wiki 中，很难沉淀成统一的架构知识库。

如果能把“画图”这件事交给 AI，工程师只需要提供结构化的文字描述，自动产出专业、统一风格的 HTML 架构图，并可以在聊天中迭代修改，就能极大降低成本、提升效率。

2. Architecture Diagram Generator 的定位

Architecture Diagram Generator 就是这样一个面向 Claude AI 的技能（Skill）：

• 你用自然语言描述系统架构（组件、连接、技术栈、云服务等）；
• Claude 调用这个 Skill，把描述渲染成一张深色主题、专业风格的系统架构图；
• 输出为单一 HTML 文件，内嵌 SVG 和 CSS，无需任何依赖，任意浏览器即可打开。

从使用者角度，你只需要会写架构说明，不需要掌握任何前端或绘图技术；从团队角度，架构图风格统一，可方便地嵌入文档、分享和归档。

---

二、整体能力概览：一句话描述 + 关键特性

1. 一句话概览

使用 Claude.ai 搭配 Architecture Diagram Generator 技能，只需用英文描述你的系统架构，即可在几秒内生成一张深色主题、语义配色、可分享的专业架构图，并以单文件 HTML 形式输出。

2. 主要特性一览

Architecture Diagram Generator 的核心特性可以概括为：美观、专业、易用、易分享。

• 美观的深色主题
  • 背景使用 Slate-950（接近黑色）搭配细腻网格纹理，凸显技术氛围。
• 语义色彩编码
  • 前端、后端、数据库、云服务、安全组件、外部系统使用不同颜色，提升可读性和一致性。
• 单文件、自包含输出
  • 输出是一个 HTML 文件，其中内嵌所有 CSS 与 SVG，无外部依赖，直接发文件即可浏览。
• 无需前端/设计能力
  • 不需要懂 SVG、不需要改 HTML，只通过对 Claude 的文字指令迭代图形内容与样式。
• 高度可迭代
  • 在 Claude 对话中持续修改：增删组件、调整布局、修改颜色/标签，立刻得到新的 HTML 输出。

下文会从使用流程、示例场景、视觉与技术细节等维度深入拆解。

---

三、使用流程：从零开始让 AI 帮你画图

完整的使用流程可以概括为三个步骤：安装 Skill → 准备架构文字描述 → 让 Claude 生成图并迭代。

1. 步骤一：在 Claude 中安装 Architecture Diagram Skill

这个工具是以 Claude Skill 的形式存在，因此前提是你有支持 Skill 的 Claude 付费账号（Pro、Max、Team 或 Enterprise）。

安装步骤：

1. 下载 architecture-diagram.zip。
2. 打开 Claude.ai，进入 Settings → Capabilities → Skills。
3. 点击 “+ Add”，上传刚才下载的 zip。
4. 打开该 Skill 的开关，确保已启用。

如果你不熟悉 Claude Skills 的概念，可以先参考官方文档“Using Skills in Claude”，了解技能的通用用法和权限模型。

除了直接在 Claude Web 上安装，该 Skill 还支持几种变体集成方式：

• Claude.ai Projects 模式：在某个 Project 的知识库中上传 zip，适用于团队级别的项目协作。
• Claude Code CLI：将 zip 解压到全局 ~/.claude/skills/ 或项目本地 ./.claude/skills/ 目录，方便在命令行/本地开发环境中调用。
• 手动集成：只要让 Claude 能访问 architecture-diagram/SKILL.md 和 assets/template.html，就能完成最小化接入。

2. 步骤二：准备“架构描述文本”

这个工具的输入，并不是一堆配置或图形操作，而是一份系统架构的自然语言描述。你可以通过多种方式获得这份描述。

2.1 方式 A：让 AI 帮你分析代码

如果你已经有一个成熟代码库，可以在 Cursor、Claude Code、Windsurf 或 ChatGPT 等开发辅助手中打开项目，让它分析架构：

示例指令（英文）：

Analyze this codebase and describe the architecture. Include all major components, how they connect, what technologies they use, and any cloud services or integrations. Format as a list for an architecture diagram.

这种方式的优势在于贴近真实实现，有助于避免“图文不符”。缺点是：如果代码架构本身比较混乱，生成结果可能也比较复杂，需要你稍作整理后再交给绘图 Skill。

2.2 方式 B：自己写一份结构化描述

对于已经熟悉系统的架构师/核心开发来说，直接写一份结构化列表通常效率更高。

示例结构：

• React 前端应用，通过 HTTPS 调用 Node.js API
• Node.js/Express 服务作为 BFF（Backend For Frontend）
• PostgreSQL 数据库存储核心业务数据
• Redis 用于缓存 Session 与热点数据
• 系统部署在 AWS 上，使用 CloudFront 作为 CDN，后端在 ECS 或 Lambda 上运行

在实际工作中，建议你尽量采用列表 + 分组的形式描述，包括：

• 各主要组件（前端、后端服务、数据库、队列、缓存等）
• 组件之间的调用/数据流向
• 使用的云服务（如 API Gateway、S3、RDS、DynamoDB 等）
• 安全边界、防火墙、安全组、认证/授权模块
• 外部系统与第三方集成

描述越清晰、越结构化，生成的图越接近你心中理想的架构图。

2.3 方式 C：没有项目？让 Claude 给你一个典型架构

如果你在做方案设计或培训，不绑定具体项目，可以直接让 Claude 给你一个典型架构作为素材。

例如：

What’s a typical architecture for a SaaS application?

Claude 会给出一个包含多层组件、常见云服务和数据流向的典型架构，你再用这个描述去生成图即可。

3. 步骤三：让 Claude 使用 Skill 生成架构图

准备好架构描述之后，就可以真正开始“让 AI 画图”了。

在 Claude 对话中，将描述粘贴进去，并明确指示它使用架构图技能，比如：

Use your architecture diagram skill to create an architecture diagram from this description:
[PASTE YOUR ARCHITECTURE DESCRIPTION HERE]

Skill 启用后，Claude 会调用 Architecture Diagram Generator，根据你的文字生成一个完整的 HTML 文件，你可以直接下载、在浏览器中打开，或者在对话中继续要求改动。

接下来，你可以用非常自然的方式迭代：

• “把 Redis 从后端旁边挪到数据库下面，并且用虚线连接。”
• “给所有外部系统加上标签，标注是第三方服务。”
• “把数据库拆成 PostgreSQL（事务）和 ClickHouse（分析）两个节点。”
• “在图上标出东区和西区两个 Region，用虚线框出来。”

Claude 会根据你的指令生成更新后的 HTML 文件，实现**“聊天式画图”**。

---

四、典型场景与 Prompt 示例

为了帮助你快速上手，工具提供了若干常见场景的 Prompt 示例，可直接作为模板使用。

1. Web 应用架构

适用于经典的“前端 + 后端 + 数据库 + 缓存”模式。

Prompt 示例（英文）：

Create an architecture diagram for a web application with:

• React frontend
• Node.js/Express API
• PostgreSQL database
• Redis cache
• JWT authentication

生成的架构图通常会包括：

• 浏览器/客户端 → React 前端
• 前端 → Node.js/Express API
• API → PostgreSQL/Redis
• 认证模块（JWT Issuer/Verifier）
• 边界、网络区域、安全组等

2. AWS Serverless 架构

适用于基于 AWS Serverless 技术栈的系统，如 API Gateway + Lambda + DynamoDB。

Prompt 示例：

Create an architecture diagram showing:

• CloudFront CDN
• API Gateway
• Lambda functions (Node.js)
• DynamoDB
• S3 for static assets
• Cognito for auth

生成的图形中会使用专门的云服务配色，帮助读者快速识别云资源与自建组件的边界。

3. 微服务 + Kubernetes 架构

适用于微服务拆分、多种语言、多种数据库组合的复杂系统。

Prompt 示例：

Create an architecture diagram for a microservices system with:

• React web app and mobile clients
• Kong API Gateway
• User Service (Go), Order Service (Java), Product Service (Python)
• PostgreSQL, MongoDB, and Elasticsearch databases
• Kafka for event streaming
• Kubernetes orchestration

生成的图会体现：

• 客户端 → API Gateway → 多个 Service
• 各服务对不同数据库的依赖关系
• Kafka 在事件流中的位置
• Kubernetes 作为编排层的“基础设施边界”

这类图对系统设计评审、培训新同学、对外技术分享都非常有帮助。

---

五、视觉与设计系统：如何保证图“看起来就很专业”

一个好用的架构图工具，除了能“画出来”，还要“画得好看”。Architecture Diagram Generator 在视觉设计上做了很多统一性和可读性上的设计。

1. 深色主题与背景

• 背景颜色基于 #020617（接近 Tailwind 的 slate-950），营造现代感和对比度。
• 背景叠加 40px 间距的网格图案，让图形在视觉上更有“场景感”和“空间感”。

深色背景的好处是：在大屏展示、演讲或录屏时，对比度高，组件和连线更加醒目。

2. 语义化配色方案

组件类型有固定的配色映射，便于跨图识别和理解：

组件类型	颜色	典型用途
Frontend	Cyan	客户端应用、UI、边缘设备
Backend	Emerald	服务端、API、业务服务
Database	Violet	数据库、存储、AI/ML 相关组件
Cloud/AWS	Amber	云服务、基础设施
Security	Rose	认证、授权、安全组、加密等
External	Slate	外部系统、第三方服务、抽象外部依赖

这种语义配色的好处是：在同一张图甚至跨多张图中，只看颜色就能大致判断组件角色，非常适合培训和快速浏览。

3. 字体与层级

• 字体使用 JetBrains Mono，这是一款非常适合技术图表和代码展示的等宽字体。
• 箭头在绘制时优先渲染，再由组件的背景覆盖部分连线，保证“线穿过盒子、但不会显得凌乱”。

这种“智能分层”的处理，避免了箭头与文本、组件边框相互遮挡造成的视觉噪音。

4. 布局与分组

在布局方面，Skill 会根据你的描述自动推断合理的排列方式，包括：

• 上下游数据流方向（例如客户端在上，数据库在下）；
• 核心服务 vs 边缘组件的相对位置；
• 通过虚线框、背景块等方式表示安全组、VPC、Region、Bounded Context 等概念。

你可以通过反复与 Claude 交互，调整布局，使其更加符合自己的理解与阅读习惯。

---

六、输出结构与技术细节：为什么它这么好集成？

1. 输出内容：不仅是一张图

Architecture Diagram Generator 输出的 HTML 文件不仅包含一张架构图，还包括完整的页面结构：

1. 头部区域（Header）
   • 展示项目名称、系统名称，以及一个带动画的状态指示器（比如类似“● LIVE”这种标志）。
2. 主图区域（Diagram）
   • 使用 SVG 渲染所有组件和连线，支持缩放、平滑展示。
3. 概要信息卡片（Summary Cards）
   • 底部通常有三个信息卡片，总结关键点（例如“前端栈”、“数据存储”、“安全与合规”等）。
4. 页脚（Footer）
   • 包含项目元数据，如生成时间、版本信息等。

这使得输出文件不仅可以作为“图像资源”，还可以作为可以直接挂在静态站点上的说明页面，极适合作为架构文档的一部分。

2. 技术实现要点

从技术实现角度看，这个工具的几个关键点包括：

• 自适应 SVG viewBox
  • SVG 视口宽度通常在 1000–1100 像素区间，保证在各种屏幕设备上都能清晰呈现。
• 字体加载
  • 使用 Google Fonts 加载 JetBrains Mono 字体，确保跨平台统一排版效果。
• 无 JavaScript 依赖
  • 整个输出页面不依赖任何 JS，完全静态，安全、稳定、易于托管。
• 单文件结构
  • 所有 CSS、SVG 都在同一个 HTML 中，减少静态资源管理成本。

3. 为何选择 HTML 而不是 PNG/SVG 单文件？

相比直接导出 PNG/SVG 图片，HTML 单文件有几个优势：

• 可以嵌入更多信息（卡片、描述、元数据等）；
• 可以在浏览器中放大、缩小、滚动，而不失真；
• 更容易与文档系统集成，比如直接用 iframe 嵌入到内部 Wiki；
• 可以随时更新替换，无需调整引用路径（如果作为独立页面托管）。

当然，如果你只需要图片，也可以用浏览器的“打印为 PDF”或截图工具从 HTML 中导出。

---

七、进阶用法：与团队开发流程结合

1. 作为“架构评审会”的标准产物

在设计新系统或对现有系统进行大规模重构时，往往会开架构评审会。你可以通过以下方式把此工具纳入流程：

1. 架构师事先写好目标架构的文字描述。
2. 使用 Architecture Diagram Generator 生成初版架构图。
3. 在评审会中展示 HTML 页面，根据讨论结果现场调整文字描述，让 Claude 生成新的图。
4. 会后把最终版 HTML 归档到架构仓库或知识库。

这样可以大幅提升评审会议的可视化效果和决策效率。

2. 将架构图纳入 CI/CD 或文档自动化

得益于 Skill 以文件和模板为基础，你可以构建自己的自动化流程，例如：

• 在文档仓库中维护一份 architecture.md 描述文件；
• 使用 Claude Code CLI + Architecture Diagram Generator，在每次发布时自动生成/更新架构图 HTML；
• 把 HTML 部署到内部文档站点，或者挂到 Release 说明中。

虽然官方仓库没有直接给出 CI/CD 脚本，但从其“ZIP + 模板 + SKILL.md”的结构可以看出，它是完全可以与自动化流程结合的。

3. 与“代码即文档”理念结合

越来越多团队开始尝试“文档即代码”（Docs as Code）模式。你可以把架构描述视为“架构即代码”的一部分：

• 将架构描述与基础设施代码（Terraform、CDK 等）置于同一仓库；
• 在重大变更时要求更新架构描述；
• 通过 Architecture Diagram Generator 定期生成架构图，保证文档与实践一致。

---

八、安装方式对比：选择最适合你的集成路径

下表对几种安装方式做一个简单对比，方便你根据团队环境选择合适方案。

安装方式	场景	特点
Claude.ai Settings	个人使用 / 小团队	Web 界面操作简单，适合快速上手，是官方推荐方式。
Claude.ai Projects	团队/项目级协作	将 Skill 作为项目知识的一部分，方便多人共享。
Claude Code CLI	本地开发 / 自动化集成	通过命令行集成到开发脚本、CI 流程中，更适合工程化落地。
手动暴露 SKILL.md 等	高度自定义接入、私有环境等	只要 Claude 能访问 SKILL.md 和模板 HTML 即可，适合有特殊合规/网络要求的环境。

---

九、实践建议与注意事项

在实际落地过程中，有几个经验值得注意：

1. 输入越结构化，输出越可靠

   • 建议采用“组件列表 + 连接关系 + 分组/边界”三部分来描述架构，而不是纯自然语言段落。

2. 多次迭代，小步快跑

   • 不必一开始就期望“一步到位”的完美架构图，先生成一个粗略版本，再通过对话不断 refine。

3. 区分“逻辑架构”和“物理部署”

   • 可以分别生成两张图：一张强调业务组件和依赖关系；一张强调部署环境、Region、VPC 等。

4. 注意英文描述对齐

   • 当前 Skill 主要面向英文描述，如果你在中文环境中使用，推荐将关键组件和关系用英文表达，以提升识别效果。

5. 与现有文档体系打通

   • 输出的 HTML 文件可以：
     • 直接上传到内部 Wiki；
     • 通过静态站点托管；
     • 作为“架构快照”随版本一起归档。

---

十、总结

在 AI 工具快速发展的今天，让工程师把时间花在“理解和设计系统”上，而不是反复调整箭头和图形对齐，是顺理成章的选择。

Architecture Diagram Generator 将“架构描述 → 专业架构图”这一过程高度自动化，通过 Claude 的 Skill 能力，把过去需要半天甚至几天的绘图工作缩短到几分钟，而且可以通过自然语言不断迭代优化。

对于个人开发者，它是一个让你“随手就能做出漂亮架构图”的生产力工具；对于团队和企业，它是“架构文档工程化”的重要一环，可以帮助你建立更加统一、可维护的架构资产库。

如果你正在为项目准备技术分享、设计评审、培训材料，或者只是想把脑中的系统结构更清晰地呈现出来，不妨试试这套 AI 驱动的架构图生成方案，让 AI 替你画图，把精力留给真正重要的系统设计决策。