关于
使用自底向上的分析方法，为现有代码仓库生成全面的 C4 架构文档。
name: c4-architecture-c4-architecture description: "使用自底向上的分析方法，为现有代码仓库/代码库生成全面的 C4 架构文档。" risk: unknown source: community date_added: "2026-02-27"
C4 架构文档工作流
使用自底向上的分析方法，为现有代码仓库/代码库生成全面的 C4 架构文档。
[Extended thinking: 此工作流实现了遵循 C4 模型（Context、Container、Component、Code）的完整 C4 架构文档流程。它使用自底向上的方法，从最深层的代码目录开始向上工作，确保在综合为更高层抽象之前，每个代码元素都已被记录。工作流协调四个专门的 C4 代理（Code、Component、Container、Context）来创建完整的架构文档集，服务于技术和非技术利益相关者。]
何时使用此技能
- 处理 C4 架构文档工作流任务或工作流时
- 需要 C4 架构文档工作流的指导、最佳实践或检查清单时
何时不使用此技能
- 任务与 C4 架构文档工作流无关时
- 需要此范围之外的不同领域或工具时
说明
- 明确目标、约束和所需输入。
- 应用相关最佳实践并验证结果。
- 提供可操作的步骤和验证方法。
- 如需详细示例，请打开
resources/implementation-playbook.md。
概述
此工作流遵循官方 C4 模型创建全面的 C4 架构文档，通过：
- 代码层：自底向上分析每个子目录，创建代码级文档
- 组件层：将代码文档综合为容器内的逻辑组件
- 容器层：将组件映射到部署容器并附带 API 文档（展示高层技术选择）
- 上下文层：创建高层系统上下文，包含角色和用户旅程（关注人员和软件系统，而非技术）
注意：根据 C4 模型，你不需要使用所有 4 个层级的图表——系统上下文图和容器图对大多数软件开发团队来说已经足够。此工作流为完整性生成所有层级，但团队可以选择使用哪些层级。
所有文档写入仓库根目录下新建的 C4-Documentation/ 目录。
阶段 1：代码级文档（自底向上分析）
1.1 发现所有子目录
- 使用代码库搜索识别仓库中的所有子目录
- 按深度排序目录（最深优先）以进行自底向上处理
- 过滤常见的非代码目录（node_modules、.git、build、dist 等）
- 创建待处理目录列表
1.2 处理每个目录（自底向上）
对每个目录，从最深层开始：
-
使用 Task 工具，subagent_type="c4-architecture::c4-code"
-
Prompt: | 分析目录中的代码：[directory_path]
按以下结构创建全面的 C4 代码级文档：
- 概述部分：
- 名称：[此代码目录的描述性名称]
- 描述：[此代码功能的简短描述]
- 位置：[相对于仓库根目录的实际目录路径链接]
- 语言：[使用的主要编程语言]
- 用途：[此代码完成的功能]
- 代码元素部分：
- 记录所有函数/方法的完整签名：
- 函数名、参数（含类型）、返回类型
- 每个函数功能的描述
- 位置（文件路径和行号）
- 依赖项（此函数依赖什么）
- 记录所有类/模块：
- 类名、描述、位置
- 方法及其签名
- 依赖项
- 记录所有函数/方法的完整签名：
- 依赖部分：
- 内部依赖（此仓库中的其他代码）
- 外部依赖（库、框架、服务）
- 关系部分：
- 如果关系复杂，可选 Mermaid 图表
将输出保存为：C4-Documentation/c4-code-[directory-name].md 使用清理后的目录名（将 / 替换为 -，移除特殊字符）作为文件名。
确保文档包含：
- 包含所有参数和类型的完整函数签名
- 指向实际源代码位置的链接
- 所有依赖项（内部和外部）
- 清晰、描述性的名称和描述
- 概述部分：
-
预期输出：C4-Documentation/ 中的 c4-code-<directory-name>.md 文件
-
上下文：目录及其子目录中的所有文件
对每个子目录重复，直到所有目录都有对应的 c4-code-*.md 文件。
阶段 2：组件级综合
2.1 分析所有代码级文档
- 收集阶段 1 中创建的所有 c4-code-*.md 文件
- 分