Back to Details

c4-architecture-c4-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

C4 Architecture Documentation Workflow

C4架构文档生成流程

Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
[Extended thinking: This workflow implements a complete C4 architecture documentation process following the C4 model (Context, Container, Component, Code). It uses a bottom-up approach, starting from the deepest code directories and working upward, ensuring every code element is documented before synthesizing into higher-level abstractions. The workflow coordinates four specialized C4 agents (Code, Component, Container, Context) to create a complete architectural documentation set that serves both technical and non-technical stakeholders.]
采用自底向上的分析方法，为现有代码仓库/代码库生成全面的C4架构文档。
[扩展思考：本流程遵循C4模型（Context、Container、Component、Code）实现了完整的C4架构文档生成流程。它采用自底向上的方法，从最深层的代码目录开始向上处理，确保在合成为更高层级的抽象之前，每个代码元素都已被记录。该流程协调四个专门的C4 Agent（Code、Component、Container、Context），生成一套同时服务于技术和非技术利益相关者的完整架构文档集。]

Use this skill when

适用场景

  • Working on c4 architecture documentation workflow tasks or workflows
  • Needing guidance, best practices, or checklists for c4 architecture documentation workflow
  • 处理C4架构文档生成的任务或工作流时
  • 需要C4架构文档生成工作流的指导、最佳实践或检查清单时

Do not use this skill when

不适用场景

  • The task is unrelated to c4 architecture documentation workflow
  • You need a different domain or tool outside this scope
  • 任务与C4架构文档生成工作流无关时
  • 需要该范围之外的其他领域或工具时

Instructions

操作说明

  • Clarify goals, constraints, and required inputs.
  • Apply relevant best practices and validate outcomes.
  • Provide actionable steps and verification.
  • If detailed examples are required, open 
    resources/implementation-playbook.md
    .
  • 明确目标、约束条件和所需输入。
  • 应用相关最佳实践并验证结果。
  • 提供可执行的步骤和验证方法。
  • 如果需要详细示例，请打开
    resources/implementation-playbook.md
    。

Overview

概述

This workflow creates comprehensive C4 architecture documentation following the official C4 model by:
  1. Code Level: Analyzing every subdirectory bottom-up to create code-level documentation
  2. Component Level: Synthesizing code documentation into logical components within containers
  3. Container Level: Mapping components to deployment containers with API documentation (shows high-level technology choices)
  4. Context Level: Creating high-level system context with personas and user journeys (focuses on people and software systems, not technologies)
Note: According to the C4 model, you don't need to use all 4 levels of diagram - the system context and container diagrams are sufficient for most software development teams. This workflow generates all levels for completeness, but teams can choose which levels to use.
All documentation is written to a new 
C4-Documentation/
directory in the repository root.
本流程遵循官方C4模型生成全面的C4架构文档，步骤如下：
  1. 代码层级：自底向上分析每个子目录，创建代码层级文档
  2. 组件层级：将代码文档合成为容器内的逻辑组件
  3. 容器层级：将组件映射到部署容器并生成API文档（展示高层技术选型）
  4. 上下文层级：创建包含角色和用户旅程的高层系统上下文（聚焦人员和软件系统，而非技术细节）
注意：根据C4模型，你无需使用全部4个层级的图——系统上下文图和容器图对大多数软件开发团队来说已足够。本流程为了完整性生成所有层级，但团队可按需选择使用哪些层级。
所有文档将写入仓库根目录下的新目录
C4-Documentation/
。

Phase 1: Code-Level Documentation (Bottom-Up Analysis)

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

1.1 Discover All Subdirectories

1.1 发现所有子目录

  • Use codebase search to identify all subdirectories in the repository
  • Sort directories by depth (deepest first) for bottom-up processing
  • Filter out common non-code directories (node_modules, .git, build, dist, etc.)
  • Create list of directories to process
  • 使用代码库搜索识别仓库中的所有子目录
  • 按深度排序目录（从最深到最浅）以进行自底向上处理
  • 过滤掉常见的非代码目录（node_modules、.git、build、dist等）
  • 创建待处理目录列表

1.2 Process Each Directory (Bottom-Up)

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

For each directory, starting from the deepest:
  • Use Task tool with subagent_type="c4-architecture::c4-code"
  • Prompt: | Analyze the code in directory: [directory_path]
    Create comprehensive C4 Code-level documentation following this structure:
    1. Overview Section:
      • Name: [Descriptive name for this code directory]
      • Description: [Short description of what this code does]
      • Location: [Link to actual directory path relative to repo root]
      • Language: [Primary programming language(s) used]
      • Purpose: [What this code accomplishes]
    2. Code Elements Section:
      • Document all functions/methods with complete signatures:
        • Function name, parameters (with types), return type
        • Description of what each function does
        • Location (file path and line numbers)
        • Dependencies (what this function depends on)
      • Document all classes/modules:
        • Class name, description, location
        • Methods and their signatures
        • Dependencies
    3. Dependencies Section:
      • Internal dependencies (other code in this repo)
      • External dependencies (libraries, frameworks, services)
    4. Relationships Section:
      • Optional Mermaid diagram if relationships are complex
    Save the output as: C4-Documentation/c4-code-[directory-name].md Use a sanitized directory name (replace / with -, remove special chars) for the filename.
    Ensure the documentation includes:
    • Complete function signatures with all parameters and types
    • Links to actual source code locations
    • All dependencies (internal and external)
    • Clear, descriptive names and descriptions
  • Expected output: c4-code-<directory-name>.md file in C4-Documentation/
  • Context: All files in the directory and its subdirectories
Repeat for every subdirectory until all directories have corresponding c4-code-*.md files.
从最深层目录开始，逐个处理每个目录：
  • 使用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-<directory-name>.md文件
  • 上下文：该目录及其子目录中的所有文件
重复处理每个子目录，直到所有目录都有对应的c4-code-*.md文件。

Phase 2: Component-Level Synthesis

第二阶段：组件层级合成

2.1 Analyze All Code-Level Documentation

2.1 分析所有代码层级文档

  • Collect all c4-code-*.md files created in Phase 1
  • Analyze code structure, dependencies, and relationships
  • Identify logical component boundaries based on:
    • Domain boundaries (related business functionality)
    • Technical boundaries (shared frameworks, libraries)
    • Organizational boundaries (team ownership, if evident)
  • 收集第一阶段创建的所有c4-code-*.md文件
  • 分析代码结构、依赖项和关系
  • 根据以下标准识别逻辑组件边界：
    • 领域边界（相关业务功能）
    • 技术边界（共享框架、库）
    • 组织边界（团队归属，如果可识别）

2.2 Create Component Documentation

2.2 创建组件文档

For each identified component:
  • Use Task tool with subagent_type="c4-architecture::c4-component"
  • Prompt: | Synthesize the following C4 Code-level documentation files into a logical component:
    Code files to analyze: [List of c4-code-*.md file paths]
    Create comprehensive C4 Component-level documentation following this structure:
    1. Overview Section:
      • Name: [Component name - descriptive and meaningful]
      • Description: [Short description of component purpose]
      • Type: [Application, Service, Library, etc.]
      • Technology: [Primary technologies used]
    2. Purpose Section:
      • Detailed description of what this component does
      • What problems it solves
      • Its role in the system
    3. Software Features Section:
      • List all software features provided by this component
      • Each feature with a brief description
    4. Code Elements Section:
      • List all c4-code-*.md files contained in this component
      • Link to each file with a brief description
    5. Interfaces Section:
      • Document all component interfaces:
        • Interface name
        • Protocol (REST, GraphQL, gRPC, Events, etc.)
        • Description
        • Operations (function signatures, endpoints, etc.)
    6. Dependencies Section:
      • Components used (other components this depends on)
      • External systems (databases, APIs, services)
    7. Component Diagram:
      • Mermaid diagram showing this component and its relationships
    Save the output as: C4-Documentation/c4-component-[component-name].md Use a sanitized component name for the filename.
  • Expected output: c4-component-<name>.md file for each component
  • Context: All relevant c4-code-*.md files for this component
针对每个识别出的组件：
  • 使用Task工具，设置subagent_type="c4-architecture::c4-component"
  • 提示语：| 将以下C4代码层级文档合成为一个逻辑组件：
    待分析的代码文件： [c4-code-*.md文件路径列表]
    按照以下结构创建全面的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-<name>.md文件
  • 上下文：该组件的所有相关c4-code-*.md文件

2.3 Create Master Component Index

2.3 创建组件总索引

  • Use Task tool with subagent_type="c4-architecture::c4-component"
  • Prompt: | Create a master component index that lists all components in the system.
    Based on all c4-component-*.md files created, generate:
    1. System Components Section:
      • List all components with:
        • Component name
        • Short description
        • Link to component documentation
    2. Component Relationships Diagram:
      • Mermaid diagram showing all components and their relationships
      • Show dependencies between components
      • Show external system dependencies
    Save the output as: C4-Documentation/c4-component.md
  • Expected output: Master c4-component.md file
  • Context: All c4-component-*.md files
  • 使用Task工具，设置subagent_type="c4-architecture::c4-component"
  • 提示语：| 创建一个列出系统中所有组件的总索引。
    基于已创建的所有c4-component-*.md文件，生成：
    1. 系统组件部分:
      • 列出所有组件，包含：
        • 组件名称
        • 简短描述
        • 组件文档链接
    2. 组件关系图:
      • 展示所有组件及其关系的Mermaid图
      • 显示组件之间的依赖
      • 显示外部系统依赖
    将输出保存为：C4-Documentation/c4-component.md
  • 预期输出：总索引文件c4-component.md
  • 上下文：所有c4-component-*.md文件

Phase 3: Container-Level Synthesis

第三阶段：容器层级合成

3.1 Analyze Components and Deployment Definitions

3.1 分析组件和部署定义

  • Review all c4-component-*.md files
  • Search for deployment/infrastructure definitions:
    • Dockerfiles
    • Kubernetes manifests (deployments, services, etc.)
    • Docker Compose files
    • Terraform/CloudFormation configs
    • Cloud service definitions (AWS Lambda, Azure Functions, etc.)
    • CI/CD pipeline definitions
  • 查看所有c4-component-*.md文件
  • 搜索部署/基础设施定义：
    • Dockerfile
    • Kubernetes清单（deployment、service等）
    • Docker Compose文件
    • Terraform/CloudFormation配置
    • 云服务定义（AWS Lambda、Azure Functions等）
    • CI/CD流水线定义

3.2 Map Components to Containers

3.2 将组件映射到容器

  • Use Task tool with subagent_type="c4-architecture::c4-container"
  • Prompt: | Synthesize components into containers based on deployment definitions.
    Component documentation: [List of all c4-component-*.md file paths]
    Deployment definitions found: [List of deployment config files: Dockerfiles, K8s manifests, etc.]
    Create comprehensive C4 Container-level documentation following this structure:
    1. Containers Section (for each container):
      • Name: [Container name]
      • Description: [Short description of container purpose and deployment]
      • Type: [Web Application, API, Database, Message Queue, etc.]
      • Technology: [Primary technologies: Node.js, Python, PostgreSQL, etc.]
      • Deployment: [Docker, Kubernetes, Cloud Service, etc.]
    2. Purpose Section (for each container):
      • Detailed description of what this container does
      • How it's deployed
      • Its role in the system
    3. Components Section (for each container):
      • List all components deployed in this container
      • Link to component documentation
    4. Interfaces Section (for each container):
      • Document all container APIs and interfaces:
        • API/Interface name
        • Protocol (REST, GraphQL, gRPC, Events, etc.)
        • Description
        • Link to OpenAPI/Swagger/API Spec file
        • List of endpoints/operations
    5. API Specifications:
      • For each container API, create an OpenAPI 3.1+ specification
      • Save as: C4-Documentation/apis/[container-name]-api.yaml
      • Include:
        • All endpoints with methods (GET, POST, etc.)
        • Request/response schemas
        • Authentication requirements
        • Error responses
    6. Dependencies Section (for each container):
      • Containers used (other containers this depends on)
      • External systems (databases, third-party APIs, etc.)
      • Communication protocols
    7. Infrastructure Section (for each container):
      • Link to deployment config (Dockerfile, K8s manifest, etc.)
      • Scaling strategy
      • Resource requirements (CPU, memory, storage)
    8. Container Diagram:
      • Mermaid diagram showing all containers and their relationships
      • Show communication protocols
      • Show external system dependencies
    Save the output as: C4-Documentation/c4-container.md
  • Expected output: c4-container.md with all containers and API specifications
  • Context: All component documentation and deployment definitions
  • 使用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等）
        • 请求/响应 schema
        • 认证要求
        • 错误响应
    6. 依赖项部分（每个容器）:
      • 使用的容器（该容器依赖的其他容器）
      • 外部系统（数据库、第三方API等）
      • 通信协议
    7. 基础设施部分（每个容器）:
      • 指向部署配置的链接（Dockerfile、K8s清单等）
      • 扩容策略
      • 资源需求（CPU、内存、存储）
    8. 容器图:
      • 展示所有容器及其关系的Mermaid图
      • 显示通信协议
      • 显示外部系统依赖
    将输出保存为：C4-Documentation/c4-container.md
  • 预期输出：包含所有容器和API规范的c4-container.md
  • 上下文：所有组件文档和部署定义

Phase 4: Context-Level Documentation

第四阶段：上下文层级文档

4.1 Analyze System Documentation

4.1 分析系统文档

  • Review container and component documentation
  • Search for system documentation:
    • README files
    • Architecture documentation
    • Requirements documents
    • Design documents
    • Test files (to understand system behavior)
    • API documentation
    • User documentation
  • 查看容器和组件文档
  • 搜索系统文档：
    • README文件
    • 架构文档
    • 需求文档
    • 设计文档
    • 测试文件（用于理解系统行为）
    • API文档
    • 用户文档

4.2 Create Context Documentation

4.2 创建上下文文档

  • Use Task tool with subagent_type="c4-architecture::c4-context"
  • Prompt: | Create comprehensive C4 Context-level documentation for the system.
    Container documentation: C4-Documentation/c4-container.md Component documentation: C4-Documentation/c4-component.md System documentation: [List of README, architecture docs, requirements, etc.] Test files: [List of test files that show system behavior]
    Create comprehensive C4 Context-level documentation following this structure:
    1. System Overview Section:
      • Short Description: [One-sentence description of what the system does]
      • Long Description: [Detailed description of system purpose, capabilities, problems solved]
    2. Personas Section:
      • For each persona (human users and programmatic "users"):
        • Persona name
        • Type (Human User / Programmatic User / External System)
        • Description (who they are, what they need)
        • Goals (what they want to achieve)
        • Key features used
    3. System Features Section:
      • For each high-level feature:
        • Feature name
        • Description (what this feature does)
        • Users (which personas use this feature)
        • Link to user journey map
    4. User Journeys Section:
      • For each key feature and persona:
        • Journey name: [Feature Name] - [Persona Name] Journey
        • Step-by-step journey:
          2. ...
        • Include all system touchpoints
      • For programmatic users (external systems, APIs):
        • Integration journey with step-by-step process
    5. External Systems and Dependencies Section:
      • For each external system:
        • System name
        • Type (Database, API, Service, Message Queue, etc.)
        • Description (what it provides)
        • Integration type (API, Events, File Transfer, etc.)
        • Purpose (why the system depends on this)
    6. System Context Diagram:
      • Mermaid C4Context diagram showing:
        • The system (as a box in the center)
        • All personas (users) around it
        • All external systems around it
        • Relationships and data flows
        • Use C4Context notation for proper C4 diagram
    7. Related Documentation Section:
      • Links to container documentation
      • Links to component documentation
    Save the output as: C4-Documentation/c4-context.md
    Ensure the documentation is:
    • Understandable by non-technical stakeholders
    • Focuses on system purpose, users, and external relationships
    • Includes comprehensive user journey maps
    • Identifies all external systems and dependencies
  • Expected output: c4-context.md with complete system context
  • Context: All container, component, and system documentation
  • 使用Task工具，设置subagent_type="c4-architecture::c4-context"
  • 提示语：| 为系统创建全面的C4上下文层级文档。
    容器文档：C4-Documentation/c4-container.md 组件文档：C4-Documentation/c4-component.md 系统文档：[README、架构文档、需求文档等列表] 测试文件：[展示系统行为的测试文件列表]
    按照以下结构创建全面的C4上下文层级文档：
    1. 系统概述部分:
      • 简短描述: [一句话说明系统功能]
      • 详细描述: [系统用途、能力、解决问题的详细说明]
    2. 角色部分:
      • 针对每个角色（人类用户和程序化“用户”）：
        • 角色名称
        • 类型（人类用户/程序化用户/外部系统）
        • 描述（他们是谁，需求是什么）
        • 目标（他们想要实现什么）
        • 使用的关键功能
    3. 系统功能部分:
      • 针对每个高层功能：
        • 功能名称
        • 描述（该功能的作用）
        • 用户（使用该功能的角色）
        • 指向用户旅程图的链接
    4. 用户旅程部分:
      • 针对每个关键功能和角色：
        • 旅程名称: [功能名称] - [角色名称] 旅程
        • 分步旅程：
          2. ...
        • 包含所有系统接触点
      • 针对程序化用户（外部系统、API）：
        • 包含分步流程的集成旅程
    5. 外部系统和依赖项部分:
      • 针对每个外部系统：
        • 系统名称
        • 类型（数据库、API、服务、消息队列等）
        • 描述（它提供的功能）
        • 集成类型（API、事件、文件传输等）
        • 用途（系统依赖它的原因）
    6. 系统上下文图:
      • Mermaid C4Context图，展示：
        • 系统（中心方框）
        • 周围的所有角色（用户）
        • 周围的所有外部系统
        • 关系和数据流
        • 使用C4Context符号绘制标准C4图
    7. 相关文档部分:
      • 指向容器文档的链接
      • 指向组件文档的链接
    将输出保存为：C4-Documentation/c4-context.md
    确保文档：
    • 非技术利益相关者可理解
    • 聚焦系统用途、用户和外部关系
    • 包含全面的用户旅程图
    • 识别所有外部系统和依赖项
  • 预期输出：包含完整系统上下文的c4-context.md
  • 上下文：所有容器、组件和系统文档

Configuration Options

配置选项

  • target_directory
    : Root directory to analyze (default: current repository root)
  • exclude_patterns
    : Patterns to exclude (default: node_modules, .git, build, dist, etc.)
  • output_directory
    : Where to write C4 documentation (default: C4-Documentation/)
  • include_tests
    : Whether to analyze test files for context (default: true)
  • api_format
    : Format for API specs (default: openapi)
  • target_directory
    : 待分析的根目录（默认：当前仓库根目录）
  • exclude_patterns
    : 要排除的模式（默认：node_modules、.git、build、dist等）
  • output_directory
    : C4文档的写入位置（默认：C4-Documentation/）
  • include_tests
    : 是否分析测试文件以获取上下文（默认：true）
  • api_format
    : API规范的格式（默认：openapi）

Success Criteria

成功标准

  • ✅ Every subdirectory has a corresponding c4-code-*.md file
  • ✅ All code-level documentation includes complete function signatures
  • ✅ Components are logically grouped with clear boundaries
  • ✅ All components have interface documentation
  • ✅ Master component index created with relationship diagram
  • ✅ Containers map to actual deployment units
  • ✅ All container APIs documented with OpenAPI/Swagger specs
  • ✅ Container diagram shows deployment architecture
  • ✅ System context includes all personas (human and programmatic)
  • ✅ User journeys documented for all key features
  • ✅ All external systems and dependencies identified
  • ✅ Context diagram shows system, users, and external systems
  • ✅ Documentation is organized in C4-Documentation/ directory
  • ✅ 每个子目录都有对应的c4-code-*.md文件
  • ✅ 所有代码层级文档包含完整的函数签名
  • ✅ 组件按逻辑分组，边界清晰
  • ✅ 所有组件都有接口文档
  • ✅ 创建了包含关系图的组件总索引
  • ✅ 容器映射到实际部署单元
  • ✅ 所有容器API都有OpenAPI/Swagger规范文档
  • ✅ 容器图展示部署架构
  • ✅ 系统上下文包含所有角色（人类和程序化）
  • ✅ 所有关键功能的用户旅程已记录
  • ✅ 所有外部系统和依赖项已识别
  • ✅ 上下文图展示系统、用户和外部系统
  • ✅ 文档组织在C4-Documentation/目录中

Output Structure

输出结构

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
    └── ...
C4-Documentation/
├── c4-code-*.md              # 代码层级文档（每个目录一个）
├── c4-component-*.md          # 组件层级文档（每个组件一个）
├── c4-component.md            # 组件总索引
├── c4-container.md            # 容器层级文档
├── c4-context.md              # 上下文层级文档
└── apis/                      # API规范
    ├── [container]-api.yaml   # 每个容器的OpenAPI规范
    └── ...

Coordination Notes

协调说明

  • Bottom-up processing: Process directories from deepest to shallowest
  • Incremental synthesis: Each level builds on the previous level's documentation
  • Complete coverage: Every directory must have code-level documentation before synthesis
  • Link consistency: All documentation files link to each other appropriately
  • API documentation: Container APIs must have OpenAPI/Swagger specifications
  • Stakeholder-friendly: Context documentation should be understandable by non-technical stakeholders
  • Mermaid diagrams: Use proper C4 Mermaid notation for all diagrams
  • 自底向上处理：从最深层到最浅层处理目录
  • 增量合成：每个层级基于上一层级的文档构建
  • 完整覆盖：在合成前，每个目录必须有代码层级文档
  • 链接一致性：所有文档文件之间的链接需恰当
  • API文档：容器API必须有OpenAPI/Swagger规范
  • 利益相关者友好：上下文文档需非技术利益相关者可理解
  • Mermaid图：所有图使用标准C4 Mermaid符号

Example Usage

示例用法

bash
/c4-architecture:c4-architecture
This will:
  1. Walk through all subdirectories bottom-up
  2. Create c4-code-*.md for each directory
  3. Synthesize into components
  4. Map to containers with API docs
  5. Create system context with personas and journeys
All documentation written to: C4-Documentation/
bash
/c4-architecture:c4-architecture
这将：
  1. 自底向上遍历所有子目录
  2. 为每个目录创建c4-code-*.md文件
  3. 合成为组件
  4. 映射到容器并生成API文档
  5. 创建包含角色和旅程的系统上下文
所有文档将写入：C4-Documentation/