C4 Code

1---
2name: c4-code
3description: Expert C4 Code-level documentation specialist. Analyzes code
4  directories to create comprehensive C4 code-level documentation including
5  function signatures, arguments, dependencies, and code structure. Use when
6  documenting code at the lowest C4 level for individual directories and code
7  modules.
8metadata:
9  model: haiku
10---
11 
12# C4 Code Level: [Directory Name]
13 
14## Use this skill when
15 
16- Working on c4 code level: [directory name] tasks or workflows
17- Needing guidance, best practices, or checklists for c4 code level: [directory name]
18 
19## Do not use this skill when
20 
21- The task is unrelated to c4 code level: [directory name]
22- You need a different domain or tool outside this scope
23 
24## Instructions
25 
26- Clarify goals, constraints, and required inputs.
27- Apply relevant best practices and validate outcomes.
28- Provide actionable steps and verification.
29- If detailed examples are required, open `resources/implementation-playbook.md`.
30 
31## Overview
32 
33- **Name**: [Descriptive name for this code directory]
34- **Description**: [Short description of what this code does]
35- **Location**: [Link to actual directory path]
36- **Language**: [Primary programming language(s)]
37- **Purpose**: [What this code accomplishes]
38 
39## Code Elements
40 
41### Functions/Methods
42 
43- `functionName(param1: Type, param2: Type): ReturnType`
44  - Description: [What this function does]
45  - Location: [file path:line number]
46  - Dependencies: [what this function depends on]
47 
48### Classes/Modules
49 
50- `ClassName`
51  - Description: [What this class does]
52  - Location: [file path]
53  - Methods: [list of methods]
54  - Dependencies: [what this class depends on]
55 
56## Dependencies
57 
58### Internal Dependencies
59 
60- [List of internal code dependencies]
61 
62### External Dependencies
63 
64- [List of external libraries, frameworks, services]
65 
66## Relationships
67 
68Optional Mermaid diagrams for complex code structures. Choose the diagram type based on the programming paradigm. Code diagrams show the **internal structure of a single component**.
69 
70### Object-Oriented Code (Classes, Interfaces)
71 
72Use `classDiagram` for OOP code with classes, interfaces, and inheritance:
73 
74```mermaid
75---
76title: Code Diagram for [Component Name]
77---
78classDiagram
79    namespace ComponentName {
80        class Class1 {
81            +attribute1 Type
82            +method1() ReturnType
83        }
84        class Class2 {
85            -privateAttr Type
86            +publicMethod() void
87        }
88        class Interface1 {
89            <<interface>>
90            +requiredMethod() ReturnType
91        }
92    }
93 
94    Class1 ..|> Interface1 : implements
95    Class1 --> Class2 : uses
96```
97````
98 
99### Functional/Procedural Code (Modules, Functions)
100 
101For functional or procedural code, you have two options:
102 
103**Option A: Module Structure Diagram** - Use `classDiagram` to show modules and their exported functions:
104 
105```mermaid
106---
107title: Module Structure for [Component Name]
108---
109classDiagram
110    namespace DataProcessing {
111        class validators {
112            <<module>>
113            +validateInput(data) Result~Data, Error~
114            +validateSchema(schema, data) bool
115            +sanitize(input) string
116        }
117        class transformers {
118            <<module>>
119            +parseJSON(raw) Record
120            +normalize(data) NormalizedData
121            +aggregate(items) Summary
122        }
123        class io {
124            <<module>>
125            +readFile(path) string
126            +writeFile(path, content) void
127        }
128    }
129 
130    transformers --> validators : uses
131    transformers --> io : reads from
132```
133 
134**Option B: Data Flow Diagram** - Use `flowchart` to show function pipelines and data transformations:
135 
136```mermaid
137---
138title: Data Pipeline for [Component Name]
139---
140flowchart LR
141    subgraph Input
142        A[readFile]
143    end
144    subgraph Transform
145        B[parseJSON]
146        C[validateInput]
147        D[normalize]
148        E[aggregate]
149    end
150    subgraph Output
151        F[writeFile]
152    end
153 
154    A -->|raw string| B
155    B -->|parsed data| C
156    C -->|valid data| D
157    D -->|normalized| E
158    E -->|summary| F
159```
160 
161**Option C: Function Dependency Graph** - Use `flowchart` to show which functions call which:
162 
163```mermaid
164---
165title: Function Dependencies for [Component Name]
166---
167flowchart TB
168    subgraph Public API
169        processData[processData]
170        exportReport[exportReport]
171    end
172    subgraph Internal Functions
173        validate[validate]
174        transform[transform]
175        format[format]
176        cache[memoize]
177    end
178    subgraph Pure Utilities
179        compose[compose]
180        pipe[pipe]
181        curry[curry]
182    end
183 
184    processData --> validate
185    processData --> transform
186    processData --> cache
187    transform --> compose
188    transform --> pipe
189    exportReport --> format
190    exportReport --> processData
191```
192 
193### Choosing the Right Diagram
194 
195| Code Style                       | Primary Diagram                  | When to Use                                             |
196| -------------------------------- | -------------------------------- | ------------------------------------------------------- |
197| OOP (classes, interfaces)        | `classDiagram`                   | Show inheritance, composition, interface implementation |
198| FP (pure functions, pipelines)   | `flowchart`                      | Show data transformations and function composition      |
199| FP (modules with exports)        | `classDiagram` with `<<module>>` | Show module structure and dependencies                  |
200| Procedural (structs + functions) | `classDiagram`                   | Show data structures and associated functions           |
201| Mixed                            | Combination                      | Use multiple diagrams if needed                         |
202 
203**Note**: According to the [C4 model](https://c4model.com/diagrams), code diagrams are typically only created when needed for complex components. Most teams find system context and container diagrams sufficient. Choose the diagram type that best communicates the code structure regardless of paradigm.
204 
205## Notes
206 
207[Any additional context or important information]
208 
209```
210 
211## Example Interactions
212 
213### Object-Oriented Codebases
214- "Analyze the src/api directory and create C4 Code-level documentation"
215- "Document the service layer code with complete class hierarchies and dependencies"
216- "Create C4 Code documentation showing interface implementations in the repository layer"
217 
218### Functional/Procedural Codebases
219- "Document all functions in the authentication module with their signatures and data flow"
220- "Create a data pipeline diagram for the ETL transformers in src/pipeline"
221- "Analyze the utils directory and document all pure functions and their composition patterns"
222- "Document the Rust modules in src/handlers showing function dependencies"
223- "Create C4 Code documentation for the Elixir GenServer modules"
224 
225### Mixed Paradigm
226- "Document the Go handlers package showing structs and their associated functions"
227- "Analyze the TypeScript codebase that mixes classes with functional utilities"
228 
229## Key Distinctions
230- **vs C4-Component agent**: Focuses on individual code elements; Component agent synthesizes multiple code files into components
231- **vs C4-Container agent**: Documents code structure; Container agent maps components to deployment units
232- **vs C4-Context agent**: Provides code-level detail; Context agent creates high-level system diagrams
233 
234## Output Examples
235When analyzing code, provide:
236- Complete function/method signatures with all parameters and return types
237- Clear descriptions of what each code element does
238- Links to actual source code locations
239- Complete dependency lists (internal and external)
240- Structured documentation following C4 Code-level template
241- Mermaid diagrams for complex code relationships when needed
242- Consistent naming and formatting across all code documentation
243 
244```
245