c4-code

C4 代码级别：[目录名称]

在以下情况下使用此技能

• 处理 C4 代码级别：[目录名称]相关任务或工作流
• 需要了解 C4 代码级别：[目录名称]的指导、最佳实践或检查清单

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

• 任务与 C4 代码级别：[目录名称]无关
• 需要此范围之外的其他领域或工具

说明

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

概览

• 名称：[此代码目录的描述性名称]
• 描述：[此代码的简要功能说明]
• 位置：[指向实际目录路径的链接]
• 语言：[主要编程语言]
• 用途：[此代码实现的功能]

代码元素

函数/方法

• functionName(param1: Type, param2: Type): ReturnType
  • 描述：[此函数的功能]
  • 位置：[文件路径：行号]
  • 依赖项：[此函数依赖的内容]

类/模块

• ClassName
  • 描述：[此类的功能]
  • 位置：[文件路径]
  • 方法：[方法列表]
  • 依赖项：[此类依赖的内容]

依赖项

内部依赖项

• [内部代码依赖项列表]

外部依赖项

• [外部库、框架、服务列表]

关系

对于复杂的代码结构，可选用 Mermaid 图。根据编程范式选择图表类型。代码图展示的是单个组件的内部结构。

面向对象代码（类、接口）

对于包含类、接口和继承关系的 OOP 代码，使用 classDiagram：

---
title: Code Diagram for [Component Name]
---
classDiagram
    namespace ComponentName {
        class Class1 {
            +attribute1 Type
            +method1() ReturnType
        }
        class Class2 {
            -privateAttr Type
            +publicMethod() void
        }
        class Interface1 {
            <<interface>>
            +requiredMethod() ReturnType
        }
    }

    Class1 ..|> Interface1 : implements
    Class1 --> Class2 : uses

函数式/过程式代码（模块、函数）

对于函数式或过程式代码，有两种选择：

选项 A：模块结构图——使用 classDiagram 展示模块及其导出的函数：

---
title: Module Structure for [Component Name]
---
classDiagram
    namespace DataProcessing {
        class validators {
            <<module>>
            +validateInput(data) Result~Data, Error~
            +validateSchema(schema, data) bool
            +sanitize(input) string
        }
        class transformers {
            <<module>>
            +parseJSON(raw) Record
            +normalize(data) NormalizedData
            +aggregate(items) Summary
        }
        class io {
            <<module>>
            +readFile(path) string
            +writeFile(path, content) void
        }
    }

    transformers --> validators : uses
    transformers --> io : reads from

选项 B：数据流图——使用 flowchart 展示函数管道和数据转换：

---
title: Data Pipeline for [Component Name]
---
flowchart LR
    subgraph Input
        A[readFile]
    end
    subgraph Transform
        B[parseJSON]
        C[validateInput]
        D[normalize]
        E[aggregate]
    end
    subgraph Output
        F[writeFile]
    end

    A -->|raw string| B
    B -->|parsed data| C
    C -->|valid data| D
    D -->|normalized| E
    E -->|summary| F

选项 C：函数依赖关系图——使用 flowchart 展示函数之间的调用关系：

---
title: Function Dependencies for [Component Name]
---
flowchart TB
    subgraph Public API
        processData[processData]
        exportReport[exportReport]
    end
    subgraph Internal Functions
        validate[validate]
        transform[transform]
        format[format]
        cache[memoize]
    end
    subgraph Pure Utilities
        compose[compose]
        pipe[pipe]
        curry[curry]
    end

    processData --> validate
    processData --> transform
    processData --> cache
    transform --> compose
    transform --> pipe
    exportReport --> format
    exportReport --> processData

选择合适的图表

代码风格	主要图表	使用场景
OOP（类、接口）	classDiagram	展示继承、组合、接口实现
FP（纯函数、管道）	flowchart	展示数据转换和函数组合
FP（含导出内容的模块）	带有 <<module>> 的 classDiagram	展示模块结构和依赖关系
过程式（结构体 + 函数）	classDiagram	展示数据结构及其关联函数
混合	组合	如有需要，可使用多个图表

注：根据 C4 模型，通常仅在复杂组件需要时才创建代码图。大多数团队认为系统上下文图和容器图已足够。无论采用何种编程范式，都应选择最能清晰表达代码结构的图表类型。

备注

[任何其他背景信息或重要信息]

交互示例

面向对象的代码库

• “分析 src/api 目录并创建 C4 代码级别文档”
• “记录服务层代码，包含完整的类层次结构和依赖关系”
• “创建 C4 代码文档，展示仓库层中的接口实现”

函数式／过程式代码库

• “记录身份验证模块中所有函数的签名和数据流”
• “为 src/pipeline 中的 ETL 转换器创建数据管道图”
• “分析 utils 目录，并记录所有纯函数及其组合模式”
• “记录 src/handlers 中的 Rust 模块，并展示函数依赖关系”
• “为 Elixir GenServer 模块创建 C4 Code 文档”

混合范式

• “记录 Go handlers 包，并展示结构体及其关联函数”
• “分析混合使用类和函数式工具的 TypeScript 代码库”

主要区别

• 与 C4-Component Agent 的区别：聚焦于单个代码元素；Component Agent 将多个代码文件整合为组件
• 与 C4-Container Agent 的区别：记录代码结构；Container Agent 将组件映射到部署单元
• 与 C4-Context Agent 的区别：提供代码级细节；Context Agent 创建高层系统图

输出示例

分析代码时，请提供：

• 完整的函数／方法签名，包括所有参数和返回类型
• 对每个代码元素用途的清晰说明
• 指向实际源代码位置的链接
• 完整的依赖项列表（内部和外部）
• 遵循 C4 代码级模板的结构化文档
• 必要时使用 Mermaid 图展示复杂的代码关系
• 在所有代码文档中保持命名和格式一致

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.