c4-modeling

name	c4-modeling
description	C4模型架构建图工具。USE WHEN C4, architecture diagram, system context, container diagram, component diagram, C4模型, 架构图, 系统上下文图, 容器图, 组件图, architecture visualization, 架构可视化. 提供C4模型的Mermaid/PlantUML生成、文档化、代码即架构能力。
implements	Architect
context	fork

Customization

Before executing, check for user customizations at: ~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/c4-modeling/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If this directory does not exist, proceed with skill defaults.

🚨 MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

You MUST send this notification BEFORE doing anything else when this skill is invoked.

1. Send voice notification:

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running C4 modeling workflow"}' \
     > /dev/null 2>&1 &
   

2. Output text notification:

   📐 Running the **c4-modeling** skill for [purpose]...
   

This is not optional. Execute this curl command immediately upon skill invocation.

c4-modeling Skill

C4模型架构建图工具，用于创建标准化的软件架构可视化。

什么是C4模型？

C4模型是一种开发者友好的架构可视化方法，由Simon Brown创建。

C4 = Context (系统上下文)
     + Container (容器)
     + Component (组件)
     + Code (代码)

四层抽象

层级	名称	描述	观众
Level 1	Context	系统全景图	所有人
Level 2	Container	技术选型与进程	架构师/开发者
Level 3	Component	组件关系	开发者
Level 4	Code	类图/ER图	开发者

Workflow Routing

Route to the appropriate workflow based on the request.

场景路由

场景	工作流	说明
新系统设计	Workflows/NewSystemC4.md	从Context到Component
现有系统文档化	Workflows/DocumentSystem.md	逆向建模
组件详细设计	Workflows/ComponentDetail.md	Level 3详细图
代码即架构	Workflows/CodeAsC4.md	从代码生成C4
架构演进	Workflows/EvolutionaryC4.md	版本对比

输出格式选择

格式	工具	适用
Mermaid	内置	快速文档
PlantUML	外部工具	复杂图
Structurizr	外部工具	代码即架构

C4 图语法

Level 1: System Context (系统上下文)

C4Context
    title System Context Diagram for SharedBrain

    Person(Prime, "@Prime", "User/Owner - 人类用户")
    Person(Avatar, "@Avatar", "Digital Avatar - 数字分身")

    System_Boundary(SharedBrain, "SharedBrain") {
        System(Protocol, "Protocol Engine", "状态机管理R/A/B/C/D/H协议")
        System(Roles, "B.D.S.K. Roles", "四角色系统")
        System(Memories, "Memory System", "记忆持久化")
        System(Tools, "Tool Layer", "脚本和MCP集成")
    }

    System_Ext(iCloud, "iCloud", "跨设备同步")
    System_Ext(AI, "AI Service", "Claude/Gemini API")

    Rel(Prime, Avatar, "指令")
    Rel(Avatar, SharedBrain, "交互")
    Rel(SharedBrain, iCloud, "同步")
    Rel(SharedBrain, AI, "调用")

Level 2: Container (容器)

C4Container
    title Container Diagram for SharedBrain

    Person(Prime, "@Prime", "User")

    ContainerDb(Filesystem, "File System", "Markdown Files", "存储所有数据")
    Container(ProtocolEngine, "Protocol Engine", "Shell/Bash", "执行R/A/B/C/D/H协议")
    Container(RoleSystem, "Role System", "Markdown", "B.D.S.K.角色定义")
    Container(MemoryManager, "Memory Manager", "Shell", "记忆读写")
    Container(ToolLayer, "Tool Layer", "Shell/MCP", "工具集成")

    System_Ext(AI, "AI Service", "Claude/Gemini")

    Rel(Prime, ProtocolEngine, "输入")
    Rel(ProtocolEngine, RoleSystem, "查询")
    Rel(ProtocolEngine, MemoryManager, "读写记忆")
    Rel(ProtocolEngine, ToolLayer, "调用工具")
    Rel(ProtocolEngine, AI, "API调用")
    Rel(MemoryManager, Filesystem, "持久化")

Level 3: Component (组件)

C4Component
    title Component Diagram for Protocol Engine

    Container(ProtocolEngine, "Protocol Engine", "Shell")

    Component(Router, "Protocol Router", "Bash", "路由到正确协议")
    Component(RExecutor, "R Executor", "Bash", "执行调研协议")
    Component(AExecutor, "A Executor", "Bash", "执行深度决策")
    Component(BExecutor, "B Executor", "Bash", "执行Sprint")
    Component(CExecutor, "C Executor", "Bash", "执行复盘")
    Component(StateMachine, "State Machine", "Bash", "状态管理")

    Rel(Router, StateMachine, "状态更新")
    Rel(Router, RExecutor, "调用")
    Rel(Router, AExecutor, "调用")
    Rel(Router, BExecutor, "调用")
    Rel(Router, CExecutor, "调用")

工作流详情

NewSystemC4 工作流

用于新系统的C4建模

步骤1: 识别系统边界
    └── 什么是系统？用户是谁？外部系统有哪些？

步骤2: Level 1 - Context
    └── 绘制系统与用户、外部系统的关系

步骤3: Level 2 - Container
    └── 识别技术容器（进程/服务/数据库）

步骤4: Level 3 - Component
    └── 每个Container内的主要组件

步骤5: 文档化
    └── 生成Markdown文档

CodeAsC4 工作流

从代码生成C4图

步骤1: 代码分析
    └── 分析项目结构

步骤2: 识别Containers
    └── 识别进程、服务、数据库

步骤3: 识别Components
    └── 识别主要类和模块

步骤4: 生成C4
    └── 生成Mermaid代码

输出格式

C4 文档模板

# C4 架构文档: [系统名称]

## 版本
v1.0 - [日期]

## 1. 系统概述
[一句话描述系统]

## 2. 外部依赖
| 系统 | 描述 | 接口 |
|------|------|------|
|      |      |      |

## 3. Level 1: System Context
\`\`\`mermaid
C4Context
    [图代码]
\`\`\`

## 4. Level 2: Containers
### 4.1 技术选型
| 容器 | 技术 | 职责 |
|------|------|------|
|      |      |      |

### 4.2 Container Diagram
\`\`\`mermaid
C4Container
    [图代码]
\`\`\`

## 5. Level 3: Components
### 5.1 [容器名] Components
\`\`\`mermaid
C4Component
    [图代码]
\`\`\`

## 6. 部署视图
[如有]

PlantUML 备选

如果需要更复杂的图，可以使用PlantUML:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_WITH_LEGEND()

title Container Diagram for SharedBrain

Person(Prime, "@Prime", "User")
System_Boundary(SharedBrain, "SharedBrain") {
    Container(ProtocolEngine, "Protocol Engine", "Bash", "Protocol execution")
    Container(RoleSystem, "Role System", "Markdown", "B.D.S.K. roles")
    ContainerDb(Filesystem, "File System", "Markdown", "Data storage")
}

System_Ext(AI, "AI Service", "Claude/Gemini")

Rel(Prime, ProtocolEngine, "Commands")
Rel(ProtocolEngine, RoleSystem, "Reads")
Rel(ProtocolEngine, Filesystem, "Persists")
Rel(ProtocolEngine, AI, "API calls")
@enduml

集成模式

与architecture-design协作

## C4建模流程

1. **架构设计**
   → architecture-design skill 完成概念设计

2. **C4建模**
   → 本skill生成4层架构图

3. **形式化验证** (关键系统)
   → formal-methods skill 验证核心逻辑

4. **ADR记录**
   → adr-management skill 记录决策

使用示例

示例: SharedBrain C4

C4Context
    title SharedBrain System Context

    Person(Prime, "@Prime", "User - SharedBrain所有者")
    Person_Ext(AI, "AI Service", "Claude/Gemini")

    System_Boundary(SharedBrain, "SharedBrain") {
        System(Protocols, "Protocol Engine", "R/A/B/C/D/H状态机")
        System(Roles, "B.D.S.K. Roles", "四角色系统")
        System(Memories, "Memory System", "记忆持久化")
        System(L0, "L0 天道层", "公理/元规则/世界观")
        System(Tools, "Tool Layer", "执行脚本")
    }

    Rel(Prime, Protocols, "指令")
    Rel(Protocols, Roles, "调用")
    Rel(Protocols, Memories, "读写")
    Rel(Protocols, L0, "约束检查")
    Rel(Protocols, Tools, "执行")
    Rel(Protocols, AI, "API")

质量标准

• 每个系统必须有4层C4
• 图必须与代码保持同步
• 外部系统必须标注接口
• 关系必须有描述

资源

• C4官网: https://c4model.com/
• C4工具: https://c4model.com/tooling
• Structurizr: https://structurizr.com/
• PlantUML C4: https://github.com/plantuml-stdlib/C4-PlantUML

---

工具: Mermaid, PlantUML, Structurizr