c4-architecture-c4-architecture

Name: c4-architecture-c4-architecture
Author: rmyndharis

github.com/rmyndharis开发1.9k43 次安装2 周前更新

代码仓库

关于 c4-architecture-c4-architecture

这项工作流技能用于为现有代码库生成 C4 架构文档，从代码层自底向上分析至系统上下文，并将产出整理到 `C4-Documentation/` 目录。

主要功能

01自底向上的代码库分析
02生成代码、组件、容器和上下文文档
03绘制组件关系图
04编写容器与 API 文档
05将产出整理到 `C4-Documentation/`

适用场景

01为现有代码库编写文档
02梳理组件与部署容器的对应关系
03为技术及非技术相关方建立架构参考

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rmyndharis/antigravity-skills --skill c4-architecture-c4-architecture

安装后在 Claude Code 中输入/c4-architecture-c4-architecture确认已加载。

详细介绍

C4 架构文档工作流

使用自底向上的分析方法，为现有代码库生成全面的 C4 架构文档。

[扩展思考：此工作流按照 C4 模型（Context、Container、Component、Code）实现完整的 C4 架构文档流程。它采用自底向上的方法，从最深层的代码目录开始，逐步向上推进，确保记录每个代码元素后，再将其归纳为更高层级的抽象。此工作流协调四个专门的 C4 Agent（Code、Component、Container、Context），以创建一套完整的架构文档，服务于技术和非技术相关人员。]

适用情形

处理 C4 架构文档工作流相关任务或工作流时
需要了解 C4 架构文档工作流的指导、最佳实践或检查清单时

不适用情形

任务与 C4 架构文档工作流无关时
需要使用此范围之外的其他领域或工具时

说明

明确目标、约束和所需输入。
应用相关最佳实践并验证结果。
提供可执行的步骤和验证方法。

概述

此工作流依据官方 C4 模型创建全面的 C4 架构文档，具体包括：

代码层级：自底向上分析每个子目录，创建代码层级的文档
组件层级：将代码文档归纳为容器中的逻辑组件
容器层级：将组件映射到部署容器，并编写 API 文档（展示高层级的技术选型）
上下文层级：创建高层级的系统上下文，包含角色和用户旅程（关注人员和软件系统，而非技术）

注意：根据 C4 模型，不必使用全部 4 个图表层级——对于大多数软件开发团队而言，系统上下文图和容器图已经足够。此工作流会生成所有层级的文档以确保完整性，但团队可以自行选择使用哪些层级。

所有文档均写入代码库根目录下新建的 C4-Documentation/ 目录。

第 1 阶段：代码层级文档（自底向上分析）

1.1 发现所有子目录

使用代码库搜索来识别代码库中的所有子目录
按目录深度排序（最深的目录排在前面），以便自底向上处理
过滤掉常见的非代码目录（node_modules、.git、build、dist 等）
创建待处理目录列表

1.2 逐个处理目录（自底向上）

从最深层目录开始，逐个处理：

使用 Task 工具，并设置 subagent_type="c4-architecture::c4-code"
提示词：| 分析目录中的代码：[directory_path]

按照以下结构创建全面的 C4 代码级文档：
1. 概述部分：
  - 名称：[此代码目录的描述性名称]
  - 描述：[简要说明此代码的作用]
  - 位置：[指向相对于仓库根目录的实际目录路径的链接]
  - 语言：[使用的主要编程语言]
  - 用途：[此代码实现的功能]
2. 代码元素部分：
  - 记录所有函数/方法及其完整签名：
    - 函数名称、参数（含类型）、返回类型
    - 每个函数的功能说明
    - 位置（文件路径和行号）
    - 依赖项（此函数依赖的内容）
  - 记录所有类/模块：
    - 类名、描述、位置
    - 方法及其签名
    - 依赖项
3. 依赖项部分：
  - 内部依赖项（此仓库中的其他代码）
  - 外部依赖项（库、框架、服务）
4. 关系部分：
  - 如果关系较复杂，可选用 Mermaid 图表
将输出保存为：C4-Documentation/c4-code-[directory-name].md 文件名使用经过清理的目录名称（将 / 替换为 -，删除特殊字符）。

确保文档包含：
- 完整的函数签名，包含所有参数及其类型
- 指向实际源代码位置的链接
- 所有依赖项（内部和外部）
- 清晰、描述性强的名称和说明
预期输出：C4-Documentation/ 中的 c4-code-.md 文件
上下文：目录及其子目录中的所有文件

对每个子目录重复此操作，直到所有目录都有对应的 c4-code-*.md 文件。

阶段 2：组件级综合

2.1 分析所有代码级文档

收集阶段 1 创建的所有 c4-code-*.md 文件
分析代码结构、依赖项和关系
根据以下边界识别逻辑组件边界：
- 领域边界（相关业务功能）
- 技术边界（共享框架、库）
- 组织边界（如有迹象，则考虑团队归属）

2.2 创建组件文档

对于每个已识别的组件：

使用 Task 工具，设置 subagent_type="c4-architecture::c4-component"
提示词：| 将以下 C4 代码级文档文件综合为一个逻辑组件：

要分析的代码文件： [列出 c4-code-*.md 文件路径]

按照以下结构创建全面的 C4 组件级文档：
1. 概览部分：
  - 名称：[组件名称——描述性且含义明确]
  - 描述：[简要说明组件的用途]
  - 类型：[应用程序、服务、库等]
  - 技术：[使用的主要技术]
2. 用途部分：
  - 详细说明该组件的功能
  - 说明它解决的问题
  - 说明它在系统中的作用
3. 软件功能部分：
  - 列出该组件提供的所有软件功能
  - 简要描述每项功能
4. 代码元素部分：
  - 列出此组件包含的所有 c4-code-*.md 文件
  - 为每个文件添加链接和简要描述
5. 接口部分：
  - 记录所有组件接口：
    - 接口名称
    - 协议（REST、GraphQL、gRPC、Events 等）
    - 描述
    - 操作（函数签名、端点等）
6. 依赖项部分：
  - 使用的组件（此组件依赖的其他组件）
  - 外部系统（数据库、API、服务）
7. 组件图：
  - 使用 Mermaid 图展示此组件及其关系
将输出保存为：C4-Documentation/c4-component-[component-name].md 文件名中使用经过清理的组件名称。
预期输出：每个组件对应一个 c4-component-.md 文件
上下文：此组件的所有相关 c4-code-*.md 文件

2.3 创建主组件索引

使用 Task 工具，设置 subagent_type="c4-architecture::c4-component"
提示词：| 创建一个主组件索引，列出系统中的所有组件。

根据已创建的所有 c4-component-*.md 文件，生成：
1. 系统组件部分：
  - 列出所有组件，并包含：
    - 组件名称
    - 简短描述
    - 指向组件文档的链接
2. 组件关系图：
  - 使用 Mermaid 图展示所有组件及其关系
  - 展示组件之间的依赖关系
  - 展示对外部系统的依赖
将输出保存为：C4-Documentation/c4-component.md
预期输出：主 c4-component.md 文件
上下文：所有 c4-component-*.md 文件

第 3 阶段：容器级综合

3.1 分析组件和部署定义

查看所有 c4-component-*.md 文件
搜索部署/基础设施定义：
- Dockerfile
- Kubernetes 清单（部署、服务等）
- Docker Compose 文件
- Terraform/CloudFormation 配置
- 云服务定义（AWS Lambda、Azure Functions 等）
- CI/CD 流水线定义

3.2 将组件映射到容器

使用 Task 工具，并将 subagent_type="c4-architecture::c4-container"
提示词：| 根据部署定义，将组件整合到容器中。

组件文档： [列出所有 c4-component-*.md 文件路径]

找到的部署定义： [列出部署配置文件：Dockerfile、K8s 清单等]

按照以下结构创建全面的 C4 容器级文档：
1. 容器部分（针对每个容器）：
  - 名称：[容器名称]
  - 描述：[容器用途及部署方式的简短说明]
  - 类型：[Web 应用程序、API、数据库、消息队列等]
  - 技术：[主要技术：Node.js、Python、PostgreSQL 等]
  - 部署：[Docker、Kubernetes、云服务等]
2. 用途部分（针对每个容器）：
  - 详细描述该容器的功能
  - 说明其部署方式
  - 说明其在系统中的作用
3. 组件部分（针对每个容器）：
  - 列出部署在该容器中的所有组件
  - 链接到组件文档
4. 接口部分（针对每个容器）：
  - 记录所有容器 API 和接口：
    - API/接口名称
    - 协议（REST、GraphQL、gRPC、事件等）
    - 描述
    - OpenAPI/Swagger/API 规范文件链接
    - 端点/操作列表
5. API 规范：
  - 为每个容器 API 创建 OpenAPI 3.1+ 规范
  - 保存为：C4-Documentation/apis/[container-name]-api.yaml
  - 包含：
    - 所有端点及其方法（GET、POST 等）
    - 请求/响应架构
    - 身份验证要求
    - 错误响应
6. 依赖项部分（针对每个容器）：
  - 使用的容器（该容器依赖的其他容器）
  - 外部系统（数据库、第三方 API 等）
  - 通信协议
7. 基础设施部分（针对每个容器）：
  - 部署配置链接（Dockerfile、K8s 清单等）
  - 扩缩容策略
  - 资源需求（CPU、内存、存储）
8. 容器图：
  - 使用 Mermaid 绘制展示所有容器及其关系的图
  - 展示通信协议
  - 展示外部系统依赖
将输出保存为：C4-Documentation/c4-container.md
预期输出：包含所有容器和 API 规范的 c4-container.md
上下文：所有组件文档和部署定义

第 4 阶段：上下文级文档

4.1 分析系统文档

审查容器和组件文档
搜索系统文档：
- README 文件
- 架构文档
- 需求文档
- 设计文档
- 测试文件（用于了解系统行为）
- API 文档
- 用户文档

4.2 创建上下文文档

使用 Task 工具，并将 subagent_type="c4-architecture::c4-context"
提示词：| 为系统创建全面的 C4 上下文级文档。

容器文档：C4-Documentation/c4-container.md 组件文档：C4-Documentation/c4-component.md 系统文档：[README、架构文档、需求等列表] 测试文件：[展示系统行为的测试文件列表]

按照以下结构创建全面的 C4 上下文级文档：
1. 系统概览部分：
  - 简短描述：[用一句话描述系统的功能]
  - 详细描述：[详细说明系统的用途、功能和解决的问题]
2. 角色部分：
  - 对每个角色（人类用户和程序化“用户”）：
    - 角色名称
    - 类型（人类用户 / 程序化用户 / 外部系统）
    - 描述（他们是谁、需要什么）
    - 目标（他们希望实现什么）
    - 使用的关键功能
3. 系统功能部分：
  - 对每项高级功能：
    - 功能名称
    - 描述（此功能的作用）
    - 用户（使用此功能的角色）
    - 用户旅程图链接
4. 用户旅程部分：
  - 对每项关键功能和角色：
    - 旅程名称：[功能名称] - [角色名称]旅程
    - 分步旅程：
      1. [步骤 1]：[描述]
      2. [步骤 2]：[描述] ...
    - 包含所有系统交互点
  - 对程序化用户（外部系统、API）：
    - 按步骤说明集成旅程
5. 外部系统和依赖项部分：
  - 对每个外部系统：
    - 系统名称
    - 类型（数据库、API、服务、消息队列等）
    - 描述（提供的功能）
    - 集成类型（API、事件、文件传输等）
    - 用途（系统依赖此系统的原因）
6. 系统上下文图：
  - 使用 Mermaid C4Context 图，展示：
    - 系统（居中的方框）
    - 周围的所有角色（用户）
    - 周围的所有外部系统
    - 关系和数据流
    - 使用 C4Context 表示法绘制规范的 C4 图
7. 相关文档部分：
  - 容器文档链接
  - 组件文档链接
将输出保存为：C4-Documentation/c4-context.md

确保文档：
- 非技术利益相关者也能理解
- 聚焦于系统用途、用户和外部关系
- 包含全面的用户旅程图
- 识别所有外部系统和依赖项
预期输出：包含完整系统上下文的 c4-context.md
上下文：所有容器、组件和系统文档

配置选项

target_directory：要分析的根目录（默认：当前仓库根目录）
exclude_patterns：要排除的模式（默认：node_modules、.git、build、dist 等）
output_directory：C4 文档的写入位置（默认：C4-Documentation/）
include_tests：是否分析测试文件以获取上下文（默认：true）
api_format：API 规范的格式（默认：openapi）

成功标准

✅ 每个子目录都有对应的 c4-code-*.md 文件
✅ 所有代码级文档都包含完整的函数签名
✅ 组件按逻辑分组，边界清晰
✅ 所有组件都有接口文档
✅ 创建包含关系图的主组件索引
✅ 容器映射到实际部署单元
✅ 所有容器 API 都有 OpenAPI/Swagger 规范文档
✅ 容器图展示部署架构
✅ 系统上下文包含所有角色（人工和程序化）
✅ 为所有关键功能编写用户旅程文档
✅ 识别所有外部系统和依赖项
✅ 上下文图展示系统、用户和外部系统
✅ 文档整理在 C4-Documentation/ 目录中

输出结构

C4-Documentation/
├── c4-code-*.md              # Code-level docs (one per directory)
├── c4-component-*.md          # Component-level docs (one per component)
├── c4-component.md            # Master component index
├── c4-container.md            # Container-level docs
├── c4-context.md              # Context-level docs
└── apis/                      # API specifications
    ├── [container]-api.yaml   # OpenAPI specs for each container
    └── ...

协调说明

自底向上处理：从最深层目录开始，逐层向上处理
增量式整合：每一层都基于上一层的文档构建
完整覆盖：整合前，每个目录都必须有代码级文档
链接一致性：所有文档文件都应相互建立适当链接
API 文档：容器 API 必须有 OpenAPI/Swagger 规范
便于利益相关者理解：上下文文档应让非技术利益相关者也能理解
Mermaid 图表：所有图表都使用规范的 C4 Mermaid 表示法

示例用法

/c4-architecture:c4-architecture

此操作将：

自底向上遍历所有子目录
为每个目录创建 c4-code-*.md
整合为组件
映射到容器并添加 API 文档
创建包含角色和用户旅程的系统上下文

所有文档都写入：C4-Documentation/

支持 Markdown

登录后评论

基本信息

作者: rmyndharis
仓库: rmyndharis/antigravity-skills
分类: 开发
安装次数: 43
GitHub Stars: 1,896

报告问题