代码越堆越多，但没有一张图能说清楚它在做什么——这才是真正的技术债。
接手新项目，打开代码——满屏文件夹，不知道哪个调哪个。
问 AI？AI 也不知道，因为它没看过全局。
这就是 oh-my-mermaid 要解决的问题。
一、oh-my-mermaid 是什么
一句话：一个帮你把整个项目代码，自动变成架构图的工具。
让 Claude Code 帮你把代码”翻译”成图，你一眼就能看清项目结构、数据流向、模块关系。
什么是 Mermaid？Mermaid 是一种用文字写图表的语言。你写几行代码，就能画出流程图、时序图、架构图。GitHub 原生支持，Obsidian 也支持。oh-my-mermaid 就是让 AI 自动帮你生成这种图。
它的工作流程很简单：
- 你在项目里跑一条命令
- Claude Code 扫描你的代码库
- 自动生成多个视角的架构图
- 存到
.omm/文件夹里，随时查看
项目地址：github.com/oh-my-mermaid/oh-my-mermaid
二、它解决什么问题，和同类工具比怎么样
Vibe Coding 时代，AI 帮你写代码的速度太快了。
你让 Claude 帮你写一个功能，一下子生成 20 个文件。再加几个功能，代码库瞬间膨胀。结果：你自己都不清楚项目里有什么。
再让 AI 改代码，AI 因为没有全局视角容易出错，改了这里坏那里。
WARNING很多人用 AI 做 Vibe Coding 项目，2 周后发现代码库已经是黑盒——改哪里都怕出问题，只能重来。
oh-my-mermaid 的答案是：给代码库建一个”镜像”——随时可以看、可以分享、可以给 AI 当上下文的架构文档。
跑完 /omm-scan 之后，你会得到多个视角的架构图：
overall-architecture：整体结构，模块怎么组合data-flow：数据怎么流转external-integrations：和外部系统（数据库、API、第三方服务）怎么对接
每个模块会被递归拆解——复杂的拆成子模块，简单的保持叶节点。你得到的不是一张图，而是一套可以导航的文档体系。
市面上同类工具不止这一个，我把主要几款放在一起比：
| 工具 | 核心方式 | 适合场景 | 主要限制 |
|---|---|---|---|
| oh-my-mermaid | AI Skill + Claude Code | Vibe Coding / 新项目快速建档 | 需要 Claude Code |
| Swark | VS Code 插件 + GitHub Copilot | VS Code 用户，快速出单张图 | 只出一张图，不递归 |
| CodeBoarding | 静态分析 + LLM | 大型多语言项目，团队协作 | 需要配置 LLM API key |
| C4Diagrammer | MCP 服务器 | 需要标准 C4 模型的团队 | 较复杂，上手门槛高 |
| deepwiki-rs | Rust 本地运行 | 高性能本地分析，C4 文档 | 需要 Rust 环境，面向开发者 |
Swark — 装个 VS Code 插件就能用，不需要 API Key，隐私好。但只生成一张平铺图，大项目会很乱。适合快速看一眼的场景。
CodeBoarding — 技术更扎实，用 AST 静态分析而不是靠 AI 猜。支持 6 种语言，还有 GitHub Action 可接 CI/CD。适合团队项目，但需要配置 LLM。
C4Diagrammer / deepwiki-rs — 走标准 C4 架构模型，输出规范。适合有架构规范要求的团队，对小白门槛偏高。
TIP怎么选？
- 用 Claude Code 做 Vibe Coding 项目 → oh-my-mermaid，最顺手
- 用 VS Code + GitHub Copilot，只想快速看结构 → Swark，零配置
- 团队项目，需要持续维护架构文档 → CodeBoarding，功能最全
- 有 C4 标准输出要求 → C4Diagrammer 或 deepwiki-rs
oh-my-mermaid 最大的优势：跟 Claude Code 的工作流完美融合。 本来就在用 Claude Code 写代码，一条命令就出图，不需要切换工具，不需要额外配置。
三、实战：给 Memoh 项目生成架构图
我用来演示的项目是 Memoh——一个开源的自托管 AI Agent 平台。
你可以把它理解成”自己架设的 AI 助手服务器”，支持 Telegram、微信、飞书等 9 个渠道接入，带长期记忆、MCP 工具调用、定时任务，还可以同时跑多个 AI Bot。技术栈是 Go + Vue 3 + PostgreSQL + Qdrant 向量数据库。
项目地址：github.com/memohai/Memoh（1.5k Stars）
代码量不小，模块关系复杂——正好适合用来验证 oh-my-mermaid 的效果。
第一步：安装
一句话安装：把这句话直接丢给 Claude Code：
Claude Code 会帮你搞定一切。当然你也可以自己手动跑：
npm install -g oh-my-mermaid安装完之后，运行：
omm setup这一步会自动检测你装了哪些 AI 编程工具（Claude Code、Cursor 等），然后帮你注册 /omm-scan 和 /omm-push 两个 Skill。
如果你只用 Claude Code，也可以单独运行：
omm setup claude第二步：进入项目，跑扫描
进入你的项目目录，打开 Claude Code，输入：
/omm-scanClaude Code 会开始分析你的代码库。根据项目大小，可能需要几分钟到十几分钟不等。
第三步：查看生成的架构图
扫描完成后，运行：
omm view会启动一个本地 Web 界面，默认端口是 3000，浏览器访问 http://localhost:3000 即可打开。如果端口被占用，它会自动换一个——我这里 3000 被占用，实际打开的是 http://localhost:3002。
你可以在里面点击每个模块，看它的详细描述、子模块、风险点等。
左侧是导航树，右边是各个视角的架构图预览。点进去任何一个节点，都能看到更深一层的子模块。
目录结构大概是这样的：
.omm/├── overall-architecture/│ ├── description.md ← 整体架构说明│ ├── diagram.mmd ← Mermaid 图表文件│ └── components/│ ├── api-layer/ ← API 层详情│ ├── service-layer/ ← 业务层详情│ └── data-layer/ ← 数据层详情├── data-flow/│ ├── description.md│ └── diagram.mmd└── external-integrations/ ├── description.md └── diagram.mmd实际输出长什么样？以 Memoh 为例，
overall-architecture视角清晰展示了 Api Server、Agent Engine、Channel System、Memory System 的层级关系：
data-flow 视角则追踪了一条消息从进入到响应的完整路径——Inbound Message → Pipeline Context → LLM Inference → Tool Output → Memory Write：
清晰、可读，纯文字格式，可以直接嵌入 GitHub README 或 Obsidian 笔记。
更新文档
代码有变化，图也要跟上。每次大版本更新后，重新跑 /omm-scan 就行。也可以设置 CI/CD 自动触发。
四、实用技巧
语言设置：默认输出是英文，想要中文文档？运行：
omm config language zh之后生成的描述、说明都会是中文，对中文团队更友好。
多 AI 工具用户：如果你同时用 Claude Code 和 Cursor，omm setup 会帮你把 Skill 注册到所有支持的工具上。不用重复配置。
把架构图贴进 README：.omm/ 里的 .mmd 文件，GitHub 原生渲染 Mermaid，直接复制粘贴到 README.md 里就能展示图表，不需要截图。
道理讲完了，该你了
oh-my-mermaid 不是什么黑科技，逻辑很简单：AI 帮你写的代码，让 AI 帮你画成图。
你每次接手新项目、每次做完功能迭代，跑一次 /omm-scan，10 分钟就有一份最新的架构文档。
这件事以前要专门开 Sprint 做，现在一条命令搞定。
三件事，回去就能做：
npm install -g oh-my-mermaid— 装好工具- 在一个项目里跑
/omm-scan— 先试试效果 - 把生成的架构图贴进项目 README — 让团队看得到
就这三步。代码库不再是黑盒了。
好的架构图不是炫技——是让代码有地方说话。 — 牛马翻身计划
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时