这些图表的目的是让新加入仓库的人能够信任它们。一个发明了服务或遗漏了数据库的图表比没有图表更糟糕，因此这里的一切都基于代码实际展示的内容来绘制。
1. 绘制前先调查
在代码库根目录下运行 scripts/survey.py（本技能中的路径相对于其文件夹）：
python3 scripts/survey.py /path/to/repo > /tmp/mermaid-survey.txt
它会列出带有文件数量的模块、配置文件、入口点、从声明的依赖中发现的外部服务、数据模型来源，以及模块间的导入图（含计数）。每个导入边的来自真实的导入语句，因此请使用这些边作为架构图的主干。如果一个模块包含了大部分代码并需要拆分，可以加上 --depth 3 参数重新运行。
然后阅读脚本无法看到的内容：
- README 和任何现有文档，以获取团队已使用的名称
- 入口点，以了解哪些内容作为独立进程运行（服务器、任务队列、CLI、定时任务、Lambda）
- 部署配置（Dockerfile、compose 文件、fly.toml、serverless/CDK、Terraform），以了解哪些内容是独立部署的以及它和哪些服务通信
- 跨进程边界的调用：HTTP 客户端和基础 URL、队列发布者和消费者、外部服务的 SDK 客户端
简要记录每个框和箭头对应的文件，这将成为输出中的 "Sources" 列表。
如果用户只要求一个图表（例如“我们数据库的 ER 图”），则只制作那个图表，但仍需先进行调查。
2. 架构总览
绘制一个 flowchart，展示可部署的组件及其内部的模块，以及它们使用的数据存储和外部服务。目标为 6 到 20 个节点。较大的代码库应该按可部署单元分组到子图中，而不是增加更多框。
- 节点应该是开发者会命名的东西：如“API server”、“web app”、“firehose consumer”、“PostgreSQL”、“Stripe”。使用团队在 README 或包名中使用的名称。
- 箭头从调用方指向被调用方，并在跨进程时说明方式（如“REST /api”、“SQL”、“S3 upload”）。进程内的导入则不加标签。
- 删除那些不解构系统的内容：每个人都会导入的工具模块、仅类型的包、测试、构建脚本。如果它们重要，可以在文本中提及。
- 不要画出你无法验证的东西。 如果你怀疑有连接但找不到代码，就将其省略，并在文本中说明。
形状和样式约定请参考 references/diagram-guide.md。
3. 数据模型
仅当调查列出了数据模型来源时，才绘制 erDiagram；如果没有来源，则用一句话说明并跳过。不要根据 API 类型或变量名推断表，因为猜测的模式看上去和真实的模式一样权威。
- 当存在迁移文件时，迁移就是真相。 按顺序应用它们，因此后来的
ALTER、DROP和重命名优先。如果 ORM 模型与迁移不一致，则遵循迁移，并说明不一致之处。 - 两组迁移（例如旧的
supabase/migrations/和当前的drizzle/目录）通常意味着有一组已过时。遵循应用的迁移命令或 ORM 配置指向的那一组（如drizzle.config.*、prisma/schema.prisma、package.json 中的migrate脚本），并在文本中命名过时的那一组。 - 展示键和标识行的列：主键、外键、唯一列，以及读者需要识别实体所需的少数列。除非重要，否则跳过时间戳和其他记账列。
- 从约束中读取基数。 非空的外键在主表侧恰好是一个，可空的外键是零或一个，唯一外键使关系成为一对一。用简洁的动词短语标记每个关系。
- 超过大约 15 个实体后，按领域拆分图表，而不是绘制一个庞大的表墙。
4. 写入文件
写入 docs/architecture.md，如果已存在则更新。如果代码库将文档放在其他地方，则遵循那个路径；如果用户指定了路径，则使用他们的路径。对于每个图表：
## 架构
用两到三句话说明图表展示的内容以及省略了什么。
<!-- mermaid-gen:start architecture -->
```mermaid
flowchart LR
...
```
<!-- mermaid-gen:end architecture -->
**来源：** `cmd/server/main.go`、`internal/handler/`、`fly.toml`
标记注释允许后续运行仅替换图表内容，而不影响手动编辑的文本。当更新现有文件时，只更改标记之间的内容，以及直接围绕它们的说明和来源。
5. 检查渲染
对文件运行 scripts/lint_mermaid.py：
python3 scripts/lint_mermaid.py /path/to/repo/docs/architecture.md
它会捕获最常见导致渲染错误的问题：未加引号的标签中的特殊字符、用作节点 ID 的保留字（如 end）、未闭合的 subgraph，以及格式错误的 ER 关系或属性。在完成前修复所有错误。如果安装了 mmdc（mermaid-cli），也可以用它进行渲染。
最后，告诉用户文件的位置、每个图表覆盖的内容，以及你省略或无法确认的任何内容。