c4-codebase-architecture

C4 模型代码库文档编写技能

目的

此技能可帮助 Agent 检查代码库并编写实用的 C4 风格架构文档。当仅靠检查代码不足以确定系统边界、职责、运行时拓扑或业务意图时，技能应结合代码库中的证据，并提出有针对性的后续问题。

此技能应注重实用，而非教条。目标不是强迫每个代码库都生成一套完美的四张图，而是在恰当的细节层次上，尽可能清晰地呈现架构。

---

何时使用此技能

当用户想要：

• 了解现有代码库的架构
• 为代码库编写 C4 文档
• 生成系统上下文图、容器图或组件图
• 使用架构文档帮助新工程师熟悉项目
• 根据代码和基础设施定义反向分析系统结构
• 比较预期架构与已实现架构

如果代码库至少包含以下部分内容，此技能的效果最佳：

• 源代码
• 基础设施即代码
• 部署描述文件
• README 或文档
• API 规范
• CI/CD 配置
• 测试套件

---

此技能应生成的内容

根据代码库的实际情况，此技能应尽力生成以下部分或全部内容：

1. 系统上下文

   • 正在研究的系统
   • 人类用户或用户角色
   • 外部系统、API、服务提供商或依赖项
   • 关键关系

2. 容器视图

   • 主要可部署或可运行单元
   • 数据库、队列、前端、API、工作进程、无服务器函数、数据存储
   • 它们之间使用的协议及交互方式

3. 组件视图

   • 所选容器中的主要内部组件
   • 它们的职责和关系

4. 辅助说明

   • 根据代码检查得出的假设
   • 尚未解决的模糊之处
   • 要向用户提出的问题
   • 值得注意的架构风险或不一致之处

5. 可选的图表源文件

   • Mermaid、PlantUML、Structurizr DSL 或纯文本图表说明

除非用户明确要求，否则此技能无需生成完整的代码级图表。只有在能显著增进理解时，才提及类、模块或包。

---

默认工作原则

1. 证据优先

尽可能根据代码库中可观察到的证据提出架构相关结论。优先查看：

• 入口点
• 路由定义
• 包清单
• 部署描述文件
• 基础设施代码
• 环境变量的使用方式
• API 客户端和 SDK 的使用方式
• 集成测试
• 队列／主题的使用方式
• 持久化代码

不要将猜测当作事实陈述。

2. 区分事实与推断

根据代码推断架构时，应明确标注推断内容。

例如：

• 观察到的事实：代码库包含一个 React 应用、一个 Express API，以及用于创建 RDS 实例的 Terraform 代码。
• 推断：该系统可能使用基于浏览器的前端，调用由 PostgreSQL 支持的后端 API。

3. 只提出高价值问题

当检查代码仍不足以得出结论时，应分批提出简洁且影响重大的问题。避免询问那些很可能可以从代码中查明的细节。

4. 尊重系统边界

代码库并不总是整个系统。应明确说明文档的范围是：

• 仅限此代码库
• 更大平台中的单个服务
• 包含多个系统的单体代码库
• 更广泛架构的部分实现

5. 默认采用实用的细节层次

通常最实用的内容包括：

• 一张系统上下文图
• 一张容器图
• 一到两张关键容器的组件图

不要强行为简单服务拆分组件。

---

代码库分析工作流

阶段 1：确定范围

首先，判断此代码仓库所代表的内容。

查找：

• 仓库名称
• README 摘要
• 工作区或单体仓库结构
• 顶层文件夹
• 包清单
• 构建文件
• 基础设施文件夹
• 部署文件夹
• 文档文件夹

尝试回答：

• 这是一个什么系统或子系统？
• 这是完整产品、服务、库，还是基础设施？
• 哪些内容属于范围，哪些不属于？

如果范围不明确，请询问用户。

阶段 2：识别运行时构件

找出主要的可执行单元或可部署单元。

查找：

• Web 前端
• 后端服务
• 命令行工具
• 无服务器函数
• Worker 或定时任务
• 数据库
• 缓存
• 队列和流
• 搜索引擎
• 存储桶
• 第三方 SaaS 依赖

重要说明：在 C4 中，“容器”指可部署或可运行的单元，并非特指 Docker 容器。

阶段 3：识别交互

梳理运行时构件之间的交互方式。

查找：

• HTTP 客户端和服务端
• SDK 调用
• 消息发布或消费
• 数据库访问层
• 身份验证中间件
• 事件处理程序
• cron 或调度器配置
• 文件或对象存储访问

尝试记录：

• 流向
• 可见的传输方式或协议
• 同步或异步行为
• 信任边界

阶段 4：推断参与者和外部系统

代码通常会揭示外部系统，但不一定能看出最终用户或业务参与者。

查找：

• 身份验证提供商
• 支付系统
• 电子邮件提供商
• 云服务
• 合作伙伴 API
• 身份系统
• 可观测性系统

对于参与者，可谨慎地根据以下内容进行推断：

• UI 标签
• 路由名称
• 领域术语
• 角色检查
• 文档

如果用户画像不明确，请询问用户。

阶段 5：将重要容器分解为组件

对于最重要或最复杂的容器，识别主要的内部组件。

查找：

• 模块
• 包
• 功能文件夹
• 控制器
• 服务
• 存储库
• 适配器
• 领域层
• 处理程序
• 中间件

良好的组件拆分通常侧重于职责，而不是逐个列出文件。

避免生成仅仅罗列文件夹名称的组件图。

阶段 6：编写文档

最终输出应包含：

• 已说明的范围
• 假设
• C4 视图
• 必要时提出的澄清问题
• 用户要求时提供的图表源文件

---

此技能可能会向用户提出的问题

仅在问题能实质性提高正确性时才提出。优先将 3 至 7 个问题合并提问。

关于范围

• 此代码仓库代表整个系统，还是更大平台中的一个服务？
• 你希望文档仅涵盖仓库中的内容，还是也涵盖它所依赖的相邻系统？
• 图表是否有特定的受众，例如新入职的工程师、利益相关者或运维团队？

关于参与者和用户画像

• 此系统的主要用户或运维人员是谁？
• 是否有不同的用户画像或角色，例如客户、管理员、支持人员或合作伙伴？
• 系统上下文视图中是否应包含内部运维团队？

关于部署／运行时拓扑

• 仓库中的可部署单元是否也是生产环境中的实际运行时容器？
• 是否有代码中未体现的重要外部组件，例如托管数据库、外部队列或共享网关？
• 此系统以单体、微服务、无服务器函数还是混合形式部署？

关于系统边界

• 上下文图中，哪些内容应视为系统边界之外？
• 由其他团队负责的共享平台服务是否更适合显示为外部系统？

关于不明确的依赖项

• 此外部依赖是否足够关键，值得在图表中明确展示？
• S3、Redis 或 EventBridge 等基础设施服务应作为系统内部的容器展示，还是作为外部托管服务展示？

关于组件

• 你希望组件图聚焦于哪个容器？
• 你希望采用面向领域的划分、按技术层划分，还是最贴近代码结构的划分？

关于输出格式

• 你希望使用 Mermaid、PlantUML、Structurizr DSL，还是仅提供文档文本？
• 你更喜欢简洁的文档，还是更具解释性、便于新手入门的文档？

---

常见代码库结构的启发式判断

单体应用

如果代码库包含一个主应用和一个数据库，可能的输出包括：

• 上下文：用户、系统、外部集成
• 容器：Web 应用或 API、数据库，可能还有后台工作进程
• 组件：控制器、服务、存储库、集成

包含前端和后端的 Monorepo

如果代码库包含多个应用或软件包：

• 确定哪些可以独立部署
• 将库与容器区分开
• 仅在有助于解释架构时展示共享库

无服务器系统

对于无服务器架构：

• 在适当情况下，将函数归入有意义的运行时容器
• 除非用户明确要求展示该细节层级，否则避免为每个函数单独绘图
• 在相关时展示 API Gateway、队列、存储桶、事件总线和数据存储
• 即使“API”“异步工作进程”和“定时处理器”由多个函数实现，也可考虑将它们作为容器

微服务

对于微服务代码库：

• 将每个可独立部署的服务显示为一个容器
• 标明服务之间的通信路径
• 注意不要将库或软件包误认为服务

库或 SDK

如果代码库主要是一个库，完整的 C4 文档可能并不合适。在这种情况下：

• 说明该代码库本身并不是一个完整的运行时系统
• 如果用户提供了相关背景，则记录它在更大范围内所起的作用
• 可以选择为该库本身创建精简的上下文图和组件视图

---

输出模板

默认使用以下结构。

1. 范围

说明文档涵盖的内容以及任何重要的范围边界。

示例：

本文档介绍当前代码库所体现的架构。它似乎涵盖后端服务及其部署配置，但不包括完整的终端用户平台。

2. 代码库观察结果

总结在代码库中发现的最有力的具体信号。

示例：

• apps/web 中的 React 前端
• apps/api 中的 Node.js API
• PostgreSQL 依赖项和迁移脚本
• 用于 VPC、ECS、RDS 和 SQS 的 Terraform 模块
• 消费队列消息的后台工作进程

3. 假设与推断

列出推断所得而非直接观察到的内容。

4. 系统上下文

提供简短说明，并在用户要求时提供图表定义。

5. 容器视图

提供简短说明，并在用户要求时提供图表定义。

6. 组件视图

仅聚焦于一个或多个重要容器。

7. 待解决的问题

列出尚未明确的问题；澄清这些问题有助于完善文档。

8. 建议的后续完善

建议接下来需要澄清或记录的内容。

---

绘图指南

通用指南

每张图都应：

• 有清晰的标题
• 明确标出范围
• 使用描述性框标签
• 使用简短的动词或短语标注关系
• 仅在有用时注明关键技术细节
• 避免视觉杂乱

标签示例

优先使用：

• Web Application\nReact SPA used by customers
• Orders API\nNode.js service handling checkout and order retrieval
• PostgreSQL\nStores users, orders, and payment state

而不是含糊的标签，例如：

• Frontend
• Backend
• DB

关系示例

优先使用以下标签：

• Submits order via HTTPS
• Reads product catalog
• Publishes job messages
• Verifies identity token

避免使用没有标签的箭头。

---

如何处理基础设施和托管服务

该技能在将云资源纳入 C4 图时，应运用判断力。

适合在容器层级展示的对象

当这些对象会实质性地影响架构时，应将其展示出来：

• 主数据库
• 消息队列
• 事件总线
• 作为核心工作流环节使用的对象存储
• 缓存
• 搜索引擎
• 身份提供商
• 主要外部 API

通常属于低层细节，除非与设计相关

除非它们是设计的核心，否则通常属于实现细节：

• 子网
• 安全组
• IAM 角色
• 自动扩缩策略
• 日志组
• CI 运行器

边界判断

拿不准时：

• 如果团队拥有该资源，并将其视为应用架构的一部分来分析，它可能属于系统边界之内
• 如果它是由其他团队或供应商提供的平台依赖项，作为外部系统展示可能更合适

---

技能的质量标准

好的结果应当：

• 忠实反映代码库
• 明确说明不确定之处
• 对人类读者有用
• 避免图表变成一团方框和箭头
• 聚焦重要的运行时结构

不好的结果会：

• 混淆包与可部署单元
• 在没有依据的情况下臆造参与者
• 过度记录琐碎细节
• 生成包含许多未标注箭头的图表
• 混淆事实与猜测的界限

---

交互模式示例

开场示例

我检查了代码库，目前已经看到一个前端应用、一个 API 服务、一个工作进程，以及一些用于 PostgreSQL 数据库和 SQS 队列的基础设施代码。我可以据此起草一份初步的系统上下文图和容器图。

在定稿前，我需要澄清几个代码未能完全说明的问题：

1. 这个代码库是整个系统，还是更大平台的一部分？
2. 上下文图中应展示哪些主要用户角色？
3. SQS 和 S3 这类托管 AWS 服务应放在系统边界内，还是作为外部支撑服务展示？
4. 你希望我在哪个容器上进一步绘制组件级视图？

后续行为示例

如果用户没有回答所有问题，请继续尽力起草，并清楚说明所作假设。

---

建议的默认交付内容

除非用户另有要求，否则该技能应尝试提供：

• 一份简洁的系统上下文视图
• 一份简洁的容器视图
• 一份最核心容器的组件视图
• 一段简短说明，阐述假设和待解决的问题

如果系统规模较大，建议逐步编写文档，而不是强行将所有内容塞进一份回复。

---

可选输出格式

根据要求，该技能可以以下列格式输出图表：

• Mermaid
• 使用 C4 扩展的 PlantUML
• Structurizr DSL
• 带结构化章节的纯 Markdown

如果用户没有偏好，默认使用 Markdown 叙述加 Mermaid。

---

给 Agent 的最终指示

仔细检查代码库，谨慎推断架构，并通过有针对性的问题解决代码无法说明的问题。生成精确、易读且如实说明不确定性的 C4 文档。