342 lines
12 KiB
Markdown
342 lines
12 KiB
Markdown
---
|
||
name: c4model-c4
|
||
description: Expert methodology for C4 Model Level 4 (Code) analysis - identifying classes, functions, methods, interfaces, and types within components. Use when analyzing code-level structure, mapping signatures, detecting complexity, identifying code patterns, or documenting code elements after C3 component identification. Essential for c4-abstractor agent during code element identification phase.
|
||
---
|
||
|
||
# C4 Model - Level 4: Code Methodology
|
||
|
||
## Overview
|
||
|
||
You are an expert in the C4 Model's Level 4 (Code) methodology. This skill provides comprehensive knowledge for identifying and documenting code elements at the most granular level of architectural abstraction.
|
||
|
||
**Your Mission:** Help identify WHAT code elements exist within components, WHAT they do, and HOW they interact - focusing on classes, functions, methods, interfaces, and types.
|
||
|
||
### C4 Level Definition
|
||
|
||
The Code level shows the **internal implementation** of components - the actual code building blocks:
|
||
|
||
- **Classes** - Object-oriented class definitions with inheritance and interfaces
|
||
- **Functions** - Standalone functions and async functions
|
||
- **Methods** - Class methods with visibility modifiers
|
||
- **Interfaces** - Type contracts and interface definitions
|
||
- **Types** - Type aliases, generics, and type definitions
|
||
- **Constants/Enums** - Constant values and enumerations
|
||
|
||
**At C4, we focus on:** Class structure, function signatures, method implementations, type definitions, code metrics, inheritance hierarchies, interface implementations, parameter types, return types, decorators/annotations.
|
||
|
||
**At C4, we do NOT focus on:** System boundaries (C1), container technologies (C2), component organization (C3), infrastructure configuration.
|
||
|
||
**Important Note (per C4 Model methodology):** The Code level is often skipped or auto-generated because:
|
||
- IDEs can generate this automatically
|
||
- UML class diagrams serve this purpose
|
||
- It's too detailed to maintain manually
|
||
- Code is the source of truth
|
||
|
||
Focus on **significant code elements** only - public APIs, complex functions, key classes.
|
||
|
||
---
|
||
|
||
## Detailed References
|
||
|
||
For comprehensive guidance on specific aspects of C4 code analysis, see:
|
||
|
||
- **[Code Element Identification](./code-element-identification.md)** - Element types, detection rules, significance criteria, naming conventions
|
||
- **[Signature Analysis](./signature-analysis.md)** - Parameter extraction, return types, generics, decorators
|
||
- **[Complexity Metrics](./complexity-metrics.md)** - Cyclomatic complexity, cognitive complexity, nesting depth, LOC
|
||
- **[Observation Guide](./observation-guide-c4.md)** - 10 observation categories, severity levels, evidence collection
|
||
- **[Relation Types](./relation-types-c4.md)** - calls, returns, imports, inherits, implements, and more
|
||
|
||
These references are loaded progressively when needed for detailed analysis.
|
||
|
||
---
|
||
|
||
## Code Element Identification Summary
|
||
|
||
A **code element** at C4 level is a discrete unit of code with clear purpose - such as a class definition, function declaration, interface contract, or type alias.
|
||
|
||
### Element Types
|
||
|
||
1. **class** - Object-oriented class definition
|
||
2. **function** - Standalone function (sync)
|
||
3. **async-function** - Async function returning Promise
|
||
4. **method** - Class or object method
|
||
5. **interface** - TypeScript/Java interface
|
||
6. **type** - Type alias or type definition
|
||
7. **constant** - Exported constant value
|
||
8. **variable** - Module-level variable
|
||
9. **enum** - Enumeration definition
|
||
10. **decorator** - Decorator/annotation definition
|
||
11. **generator** - Generator function
|
||
12. **module** - Module or namespace export
|
||
13. **namespace** - Namespace declaration
|
||
|
||
### Significance Criteria
|
||
|
||
Document a code element if **ANY** apply:
|
||
- Public API (exported from module)
|
||
- Lines of code > 20
|
||
- Cyclomatic complexity > 4
|
||
- Multiple callers or dependencies
|
||
- Implements design pattern
|
||
- Contains critical business logic
|
||
- Has security implications
|
||
- Is entry point or controller action
|
||
- Defines key data structure
|
||
|
||
**Key principles:** Focus on significant elements, preserve original naming, document public APIs thoroughly, calculate metrics for functions/methods.
|
||
|
||
For complete methodology, see [code-element-identification.md](./code-element-identification.md).
|
||
|
||
---
|
||
|
||
## Signature Analysis Summary
|
||
|
||
Extract signature information for functions, methods, and interfaces:
|
||
|
||
### Parameters
|
||
- Name (original case)
|
||
- Type (full type including generics)
|
||
- Optional flag
|
||
- Default value (if any)
|
||
|
||
### Return Type
|
||
- Full return type
|
||
- Promise type for async functions
|
||
- Void for procedures
|
||
|
||
### Modifiers
|
||
- async (true/false)
|
||
- generic_params (type parameters)
|
||
- visibility (public/private/protected)
|
||
|
||
For complete methodology, see [signature-analysis.md](./signature-analysis.md).
|
||
|
||
---
|
||
|
||
## Complexity Metrics Summary
|
||
|
||
Calculate and document these metrics:
|
||
|
||
1. **Lines of Code (LOC)** - Actual code lines excluding comments
|
||
2. **Cyclomatic Complexity** - Number of independent paths through code
|
||
3. **Cognitive Complexity** - Mental effort to understand code
|
||
4. **Parameter Count** - Number of function/method parameters
|
||
5. **Nesting Depth** - Maximum depth of nested structures
|
||
|
||
### Thresholds
|
||
|
||
| Metric | Good | Warning | Critical |
|
||
|--------|------|---------|----------|
|
||
| Cyclomatic | 1-6 | 7-10 | >10 |
|
||
| Cognitive | 0-10 | 11-20 | >20 |
|
||
| Parameters | 0-3 | 4-5 | >5 |
|
||
| Nesting | 0-3 | 4-5 | >5 |
|
||
| LOC | 1-30 | 31-50 | >50 |
|
||
|
||
For complete methodology, see [complexity-metrics.md](./complexity-metrics.md).
|
||
|
||
---
|
||
|
||
## Observation Categories
|
||
|
||
Document findings using these 10 categories:
|
||
|
||
1. **implementation** - Code patterns, algorithms, logic flow
|
||
2. **error-handling** - Exception handling, error propagation
|
||
3. **type-safety** - Type definitions, generics, type guards
|
||
4. **documentation** - JSDoc, docstrings, inline comments
|
||
5. **testing** - Test coverage, testability, mocking
|
||
6. **complexity** - Cyclomatic/cognitive complexity metrics
|
||
7. **performance** - Algorithm efficiency, memory, async patterns
|
||
8. **security** - Input validation, sanitization, auth
|
||
9. **concurrency** - Async/await, promises, race conditions
|
||
10. **patterns** - Design patterns, code patterns, anti-patterns
|
||
|
||
**Severity levels:**
|
||
- ℹ️ info (informational)
|
||
- ⚠️ warning (potential issue)
|
||
- 🔴 critical (requires immediate action)
|
||
|
||
For complete guide, see [observation-guide-c4.md](./observation-guide-c4.md).
|
||
|
||
---
|
||
|
||
## Relation Types
|
||
|
||
Document relationships between code elements:
|
||
|
||
### Code Flow Relations
|
||
- **calls** - Invokes another function/method
|
||
- **awaits** - Awaits an async function
|
||
- **returns** - Returns a specific type
|
||
- **throws** - Throws an exception type
|
||
|
||
### Structural Relations
|
||
- **inherits** - Extends another class
|
||
- **implements** - Implements an interface
|
||
- **declares** - Declares a type or interface
|
||
- **uses-type** - Uses a type in signature/body
|
||
|
||
### Data Relations
|
||
- **creates** - Instantiates a class
|
||
- **mutates** - Modifies state or data
|
||
- **reads** - Reads from data source
|
||
|
||
### Dependency Relations
|
||
- **imports** - Imports from module
|
||
- **depends-on** - General dependency
|
||
- **overrides** - Overrides parent method
|
||
|
||
For complete guide, see [relation-types-c4.md](./relation-types-c4.md).
|
||
|
||
---
|
||
|
||
## Integration with Melly Workflow
|
||
|
||
### When This Skill is Used
|
||
|
||
This skill is activated during **Phase 4: C4 Code Identification** (`/melly-c4-code`) for code element identification, signature analysis, metrics calculation, and pattern detection. Also used in **Phase 5: Documentation** (`/melly-doc-c4model`) for markdown generation.
|
||
|
||
### Input Expectations
|
||
|
||
Expects data from `c3-components.json` with component details including id, name, type, container_id, structure (path, language, files, exports).
|
||
|
||
### Output Format
|
||
|
||
Generates `c4-code.json` with metadata, code_elements array, and summary.
|
||
|
||
### Validation
|
||
|
||
Generated output must pass: Schema validation, timestamp ordering (c4 > c3), referential integrity (all component_ids exist), required fields, ID format (kebab-case).
|
||
|
||
Validation script:
|
||
```bash
|
||
python3 ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c4-code.py c4-code.json
|
||
```
|
||
|
||
---
|
||
|
||
## Step-by-Step Workflow
|
||
|
||
### Systematic Approach for c4-abstractor Agent
|
||
|
||
**Step 1: Load Input Data**
|
||
```bash
|
||
cat c3-components.json | jq '.components'
|
||
```
|
||
|
||
**Step 2: Analyze Each Component**
|
||
Navigate to component path, understand file structure, identify source files.
|
||
|
||
**Step 3: Identify Code Elements**
|
||
For each source file:
|
||
- Parse class definitions
|
||
- Extract function declarations
|
||
- Identify interfaces and types
|
||
- Find constants and enums
|
||
|
||
**Step 4: Extract Signatures**
|
||
For functions/methods:
|
||
- Parameter names and types
|
||
- Return type
|
||
- Async modifier
|
||
- Generic parameters
|
||
|
||
For classes:
|
||
- Parent class (extends)
|
||
- Implemented interfaces
|
||
- Decorators/annotations
|
||
- Abstract modifier
|
||
|
||
**Step 5: Calculate Metrics**
|
||
- Count lines of code
|
||
- Calculate cyclomatic complexity
|
||
- Measure cognitive complexity
|
||
- Determine nesting depth
|
||
|
||
**Step 6: Map Relationships**
|
||
- Find function calls
|
||
- Identify imports
|
||
- Track inheritance
|
||
- Document interface implementations
|
||
|
||
**Step 7: Generate Observations**
|
||
Document findings across 10 categories with evidence.
|
||
|
||
**Step 8: Validate Output**
|
||
Check element IDs, component references, timestamps, run validation script.
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
### ✅ DO:
|
||
|
||
1. **Focus on significant elements** - Public APIs, complex functions, key classes
|
||
2. **Preserve original names** - Use original case in name field
|
||
3. **Use kebab-case IDs** - Convert PascalCase/camelCase to kebab-case for IDs
|
||
4. **Document signatures thoroughly** - Parameters, types, return values
|
||
5. **Calculate metrics** - LOC, complexity for all functions/methods
|
||
6. **Track inheritance** - Document extends and implements
|
||
7. **Note decorators** - Record applied decorators/annotations
|
||
8. **Provide evidence** - File paths, line numbers, code snippets
|
||
9. **Document relationships** - calls, imports, inherits, implements
|
||
10. **Validate output** - Always run validation script
|
||
|
||
### ❌ DON'T:
|
||
|
||
1. **Don't document every element** - Skip trivial getters/setters, private helpers
|
||
2. **Don't use file names as IDs** - Use meaningful descriptive IDs
|
||
3. **Don't skip signatures** - Always extract parameter and return types
|
||
4. **Don't ignore complexity** - High complexity deserves observations
|
||
5. **Don't miss inheritance** - Always document class hierarchies
|
||
6. **Don't skip validation** - Always validate generated JSON
|
||
7. **Don't forget async** - Mark async functions appropriately
|
||
8. **Don't miss generics** - Document type parameters
|
||
9. **Don't ignore decorators** - They indicate patterns and behaviors
|
||
10. **Don't mix abstraction levels** - Keep C4 focused on code, not components
|
||
|
||
---
|
||
|
||
## Quick Reference
|
||
|
||
### Element Types
|
||
class, function, async-function, method, interface, type, constant, variable, enum, decorator, generator, module, namespace
|
||
|
||
### Visibility Levels
|
||
public, private, protected, internal, unknown
|
||
|
||
### Observation Categories
|
||
implementation, error-handling, type-safety, documentation, testing, complexity, performance, security, concurrency, patterns
|
||
|
||
### Relation Types
|
||
calls, returns, imports, inherits, implements, declares, uses-type, depends-on, throws, awaits, creates, mutates, reads, overrides
|
||
|
||
### Complexity Thresholds
|
||
- Cyclomatic: 1-6 (good), 7-10 (warning), >10 (critical)
|
||
- Cognitive: 0-10 (good), 11-20 (warning), >20 (critical)
|
||
- Parameters: 0-3 (good), 4-5 (warning), >5 (critical)
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
You now have comprehensive knowledge of C4 Model Level 4 (Code) methodology. When invoked:
|
||
|
||
1. **Load input data** from `c3-components.json`
|
||
2. **Analyze each component** to understand structure
|
||
3. **Identify code elements** (classes, functions, interfaces, types)
|
||
4. **Extract signatures** (parameters, return types, modifiers)
|
||
5. **Calculate metrics** (LOC, complexity, nesting)
|
||
6. **Map relationships** (calls, inherits, implements)
|
||
7. **Generate observations** with evidence
|
||
8. **Validate output** before finalizing
|
||
|
||
Remember: **C4 is about code implementation.** Focus on WHAT code elements exist, WHAT they do, and HOW they relate - at the most granular level. But be selective - only document significant elements.
|
||
|
||
---
|
||
|
||
**Skill Version**: 1.0.0
|
||
**Last Updated**: 2025-11-26
|
||
**Compatibility**: Melly 1.0.0+
|