c4-architecture-c4-architecture

Name: c4-architecture-c4-architecture
Author: sickn33

github.com/sickn33开发48.7k332 次安装今天更新

代码仓库

关于 c4-architecture-c4-architecture

c4-architecture-c4-architecture 是为现有代码仓库生成 C4 架构文档的 Agent 技能，从源码清单逐步整理组件、容器和系统上下文视图，并强调证据、受众需求与安全文档实践。

主要功能

01自底向上盘点源码目录
02记录代码与组件
03将组件映射到容器
04生成 C4 上下文文档
05保留源码证据与文档边界

适用场景

01记录现有仓库的架构
02将代码清单综合为组件
03关联组件与部署定义
04准备符合受众需求的 C4 视图

安装

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

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill c4-architecture-c4-architecture

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

详细介绍

C4 架构文档工作流

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

使用自底向上的源代码清单来支持 C4 视图，同时只选择对受众有用的级别。专用 Agent 是可选的执行辅助工具，不是捆绑工具，也不代表已审查源代码。

在以下情况下使用此技能

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

在以下情况下不要使用此技能

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

说明

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

概述

此工作流遵循官方 C4 模型，生成全面的 C4 架构文档，具体包括：

代码级：自底向上分析每个子目录，创建代码级文档
组件级：将代码文档整合为容器中的逻辑组件
容器级：将组件映射到 C4 应用／数据存储，并编写 API 文档（展示高层技术选型）
上下文级：通过角色和用户旅程创建高层系统上下文（关注人员和软件系统，而非技术）

注意：根据 C4 模型，无需使用全部 4 个级别的图表——对大多数软件开发团队来说，系统上下文图和容器图已足够。应优先选择有用的级别；代码级图表是可选的，也不是每个目录的功能目录。即使省略详细图表，也应保留源代码清单。

使用用户指定的位置；否则，建议在仓库根目录新建 C4-Documentation/ 目录。

编写文档前，记录仓库／当前 HEAD、受众、系统边界以及实际检查过的文件。保护机密和内部基础设施细节，并遵循现有文档规范。C4 容器是应用或数据存储，不等同于 Docker 容器或单个部署副本。组件属于某个容器；代码目录本身并不能确定组件边界。

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

1.1 发现所有子目录

使用代码库搜索，识别仓库中的所有子目录
按深度排序目录，先处理最深层目录
排除常见的非代码目录（node_modules、.git、build、dist 等）
创建待处理目录清单

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

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

如果存在经授权且兼容的子 Agent，则委派这项范围明确的分析；否则直接执行。c4-architecture::c4-code 是角色名称示例，并非随附工具。
提示词： | 分析目录中的代码：[directory_path]

按照以下结构创建全面的 C4 代码级文档：
1. 概览部分：
  - 名称：[此代码目录的描述性名称]
  - 描述：[简要说明此代码的功能]
  - 位置：[指向相对于仓库根目录的实际目录路径的链接]
  - 语言：[使用的主要编程语言]
  - 用途：[此代码实现的功能]
2. 代码元素部分：
  - 记录所有函数/方法及其完整签名：
    - 函数名称、参数（含类型）、返回类型
    - 各函数的功能说明
    - 位置（文件路径和行号）
    - 依赖项（此函数依赖的内容）
  - 记录所有类/模块：
    - 类名称、描述、位置
    - 方法及其签名
    - 依赖项
3. 依赖项部分：
  - 内部依赖项（此仓库中的其他代码）
  - 外部依赖项（库、框架、服务）
4. 关系部分：
  - 如果关系较复杂，可选用 Mermaid 图表
将输出保存为：C4-Documentation/c4-code-[directory-name].md 使用稳定且无冲突的路径映射：a/b 和 a-b 不得互相覆盖。优先使用对应的输出子目录或追加简短路径哈希，并记录映射。

确保文档包含：
- 完整的函数签名，包括所有参数和类型
- 指向实际源代码位置的链接
- 所有依赖项（内部和外部）
- 清晰且具有描述性的名称和说明
预期输出：C4-Documentation/ 中的 c4-code-.md 文件
上下文：仅包含此清单单元直接拥有的文件；通过链接引用已审阅的子级清单，避免重复声称包含相同文件

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

阶段 2：组件级综合

2.1 分析所有代码级文档

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

2.2 创建组件文档

对于每个已识别的组件：

使用可用且经过授权的辅助工具，或直接执行组件综合。
提示词： | 将以下 C4 代码级文档文件综合为一个逻辑组件：

要分析的代码文件： [C4 代码文件路径列表]

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

2.3 创建主组件索引

使用可用且经过授权的辅助工具，或直接执行组件综合。
提示词： | 创建列出系统中所有组件的主组件索引。

根据创建的所有 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 将组件映射到容器

使用可用的授权辅助工具，或直接进行容器综合分析。
提示词： | 根据部署定义，将组件综合为容器。

组件文档： [所有 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 规范：
  - 对于每个已验证的 HTTP API，链接到其现有的权威规范；仅在提出请求且实际路由/架构支持时，才创建 OpenAPI 3.1+ 草案文档。非 HTTP 协议需要使用相应的契约，不要伪造 OpenAPI
  - 保存为：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 创建上下文文档

使用可用的授权辅助工具，或直接进行此上下文综合分析。
提示词：| 为系统创建全面的 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）

不要仅凭名称推断用户、旅程、扩展能力或 CPU / 内存需求；应链接到来源证据，或将其标注为假设 / 待确认问题。根据代码和部署负责人提供的信息审查图表，检查链接和 ID，并区分对静态源代码的解读与实际运行时拓扑。

成功标准

✅ 每个子目录都有对应的 c4-code-*.md 文件
✅ 所有代码级文档都包含完整的函数签名
✅ 组件按逻辑分组，边界清晰
✅ 所有组件都有接口文档
✅ 创建主组件索引，并附上关系图
✅ 容器映射到实际部署单元
✅ 已验证的 HTTP API 链接到实际规范，或明确标注为未完成的草稿；非 HTTP 接口使用适当的契约
✅ 容器图展示部署架构
✅ 系统上下文涵盖所有角色（人工和程序化角色）
✅ 记录所有关键功能的用户旅程
✅ 识别所有外部系统和依赖项
✅ 上下文图展示系统、用户和外部系统
✅ 文档整理在 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 模板而编造请求、响应或身份验证细节
便于利益相关者理解：上下文文档应让非技术利益相关者也能看懂
Mermaid 图表：使用目标渲染器支持的图表语法；C4 Mermaid 支持取决于版本。请验证图表渲染效果和关系，或提供明确标注的流程图替代方案

使用示例

Document this repository’s context and containers at the specified commit.
Include source links and open questions; omit detailed code views unless they add value.

此操作将：

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

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

限制

仅当任务明确符合上述范围时，才使用此技能。
不要将输出视为针对特定环境进行验证、测试或专家审查的替代方案。
如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。

支持 Markdown

登录后评论

基本信息

作者: sickn33
仓库: sickn33/agentic-awesome-skills
分类: 开发
安装次数: 332
GitHub Stars: 48,675

报告问题