Skip to content

Commit c583df4

Browse files
thc1006thc1006
committed
docs: integrate TDD and MBSE principles into development workflow
- Add TDD (Test-Driven Development) mandatory workflow * Red-Green-Refactor cycle enforcement * 90% unit test coverage requirement * Test-first development process - Add MBSE (Model-Based Systems Engineering) principles * Model-first approach for system design * System modeling hierarchy (Intent → QoS → Resource → Deployment) * Traceability requirements (requirements → models → code → tests) - Create models/ directory structure * system/: System-level models (context, requirements, use cases) * component/: Component models (architecture, interfaces, state machines) * data/: Data models (schemas, state transitions, data flow) * deployment/: Deployment models (infrastructure, network topology) - Update SPARC workflow to integrate TDD + MBSE * Specification phase: Add MBSE modeling * Architecture phase: Add model validation * Refinement phase: Enforce TDD cycle * Completion phase: Verify model synchronization - Add comprehensive MBSE documentation * Model creation workflow and guidelines * Tool recommendations (PlantUML, Draw.io, Mermaid) * Model review process * TDD + MBSE integration example This ensures all future development follows industry best practices for test-driven development and model-based systems engineering.
1 parent e02d2a5 commit c583df4

2 files changed

Lines changed: 293 additions & 10 deletions

File tree

‎CLAUDE.md‎

Lines changed: 113 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,75 @@
11
# Claude Code Configuration - SPARC Development Environment
22

3+
## 🎯 CORE DEVELOPMENT PRINCIPLES
4+
5+
### Test-Driven Development (TDD)
6+
**MANDATORY: Write tests BEFORE implementation**
7+
8+
1. **Red-Green-Refactor Cycle**:
9+
- ❌ RED: Write failing test first
10+
- ✅ GREEN: Write minimal code to pass
11+
- 🔄 REFACTOR: Improve code quality
12+
13+
2. **TDD Workflow**:
14+
```bash
15+
# Step 1: Write test (it should fail)
16+
make test-unit # Expected: FAIL
17+
18+
# Step 2: Implement minimal code
19+
# Edit implementation files
20+
21+
# Step 3: Run test (it should pass)
22+
make test-unit # Expected: PASS
23+
24+
# Step 4: Refactor and verify
25+
make test-unit # Expected: PASS
26+
```
27+
28+
3. **Test Coverage Requirements**:
29+
- Unit tests: ≥90% coverage
30+
- Integration tests: All critical paths
31+
- E2E tests: All user scenarios
32+
- Never commit untested code
33+
34+
### Model-Based Systems Engineering (MBSE)
35+
**MANDATORY: Model-first approach for system design**
36+
37+
1. **System Modeling Hierarchy**:
38+
```
39+
Intent Model (Natural Language)
40+
↓
41+
QoS Model (Structured JSON Schema)
42+
↓
43+
Resource Model (Kubernetes CRDs)
44+
↓
45+
Deployment Model (Nephio Packages)
46+
↓
47+
Runtime Model (Live System State)
48+
```
49+
50+
2. **MBSE Workflow**:
51+
- Define models in `docs/models/` before coding
52+
- Use SysML/UML for architecture diagrams
53+
- Validate models against requirements
54+
- Generate code from models when possible
55+
- Maintain bidirectional traceability
56+
57+
3. **Required Models**:
58+
- System context diagrams
59+
- Component interaction diagrams
60+
- State machine diagrams
61+
- Data flow diagrams
62+
- Deployment architecture
63+
364
## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
465

566
**ABSOLUTE RULES**:
667
1. ALL operations MUST be concurrent/parallel in a single message
768
2. **NEVER save working files, text/mds and tests to the root folder**
869
3. ALWAYS organize files in appropriate subdirectories
970
4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
71+
5. **ALWAYS follow TDD**: Tests before implementation
72+
6. **ALWAYS model first**: Design models before coding
1073

1174
### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
1275

@@ -68,21 +131,61 @@ This project uses SPARC (Specification, Pseudocode, Architecture, Refinement, Co
68131
- `npm run lint` - Linting
69132
- `npm run typecheck` - Type checking
70133

71-
## SPARC Workflow Phases
72-
73-
1. **Specification** - Requirements analysis (`sparc run spec-pseudocode`)
74-
2. **Pseudocode** - Algorithm design (`sparc run spec-pseudocode`)
75-
3. **Architecture** - System design (`sparc run architect`)
76-
4. **Refinement** - TDD implementation (`sparc tdd`)
77-
5. **Completion** - Integration (`sparc run integration`)
134+
## SPARC Workflow Phases (TDD + MBSE Integrated)
135+
136+
1. **Specification** - Requirements analysis + MBSE modeling
137+
- Define system requirements
138+
- Create SysML/UML models
139+
- Validate requirements against models
140+
- Command: `sparc run spec-pseudocode`
141+
142+
2. **Pseudocode** - Algorithm design + test scenarios
143+
- Design algorithms with pseudocode
144+
- Define test cases for each algorithm
145+
- Create test data fixtures
146+
- Command: `sparc run spec-pseudocode`
147+
148+
3. **Architecture** - System design + model validation
149+
- Design component architecture
150+
- Create architecture models (C4, UML)
151+
- Define interfaces and contracts
152+
- Validate against MBSE models
153+
- Command: `sparc run architect`
154+
155+
4. **Refinement** - TDD implementation (RED-GREEN-REFACTOR)
156+
- Write failing tests first (RED)
157+
- Implement minimal code (GREEN)
158+
- Refactor for quality (REFACTOR)
159+
- Command: `sparc tdd`
160+
161+
5. **Completion** - Integration + model synchronization
162+
- Integration tests
163+
- Update models to reflect implementation
164+
- Verify traceability
165+
- Command: `sparc run integration`
78166

79167
## Code Style & Best Practices
80168

169+
### TDD-Driven Development
170+
- **Test-First**: ALWAYS write tests before implementation
171+
- **Red-Green-Refactor**: Follow strict TDD cycle
172+
- **Table-Driven Tests**: Use Go table-driven test pattern
173+
- **Mock External Dependencies**: Use interfaces for testability
174+
- **CI/CD Integration**: All tests must pass before merge
175+
176+
### MBSE-Driven Design
177+
- **Model-First**: Design system models before coding
178+
- **Traceability**: Maintain requirement → model → code links
179+
- **Validation**: Validate models against requirements
180+
- **Documentation**: Auto-generate docs from models
181+
- **Version Control**: Track model changes in Git
182+
183+
### General Best Practices
81184
- **Modular Design**: Files under 500 lines
82185
- **Environment Safety**: Never hardcode secrets
83-
- **Test-First**: Write tests before implementation
84-
- **Clean Architecture**: Separate concerns
85-
- **Documentation**: Keep updated
186+
- **Clean Architecture**: Separate concerns (Domain, Use Cases, Infrastructure)
187+
- **SOLID Principles**: Follow object-oriented design principles
188+
- **Documentation**: Keep models and docs synchronized
86189

87190
## 🚀 Available Agents (54 Total)
88191

‎docs/models/README.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# MBSE Models - O-RAN Intent-Based MANO
2+
3+
## Model-Based Systems Engineering (MBSE) Artifacts
4+
5+
This directory contains all system models following MBSE principles for the O-RAN Intent-Based MANO project.
6+
7+
## Directory Structure
8+
9+
```
10+
models/
11+
├── system/ # System-level models (context, requirements)
12+
├── component/ # Component-level models (architecture, interfaces)
13+
├── data/ # Data models (schemas, state machines)
14+
└── deployment/ # Deployment models (infrastructure, configuration)
15+
```
16+
17+
## Model Types
18+
19+
### 1. System Models (`system/`)
20+
- **System Context Diagram**: External interfaces and actors
21+
- **Requirements Model**: Functional and non-functional requirements
22+
- **Use Case Diagrams**: User interactions and scenarios
23+
- **Sequence Diagrams**: Cross-component interactions
24+
25+
### 2. Component Models (`component/`)
26+
- **Component Diagrams**: Internal architecture (Orchestrator, VNF Operator, TN Manager, etc.)
27+
- **Class Diagrams**: Object-oriented design
28+
- **Interface Contracts**: API specifications and protocols
29+
- **State Machine Diagrams**: Component lifecycle and states
30+
31+
### 3. Data Models (`data/`)
32+
- **QoS Schema Models**: Intent → QoS transformation models
33+
- **Resource Models**: Kubernetes CRD definitions
34+
- **State Models**: System and slice state transitions
35+
- **Data Flow Diagrams**: Information flow between components
36+
37+
### 4. Deployment Models (`deployment/`)
38+
- **Infrastructure Models**: Kubernetes cluster topology
39+
- **Network Models**: RAN, TN, CN deployment architecture
40+
- **Configuration Models**: GitOps package structures
41+
- **Multi-site Models**: Regional/edge distribution
42+
43+
## Modeling Guidelines
44+
45+
### Model Creation Workflow
46+
1. **Requirements First**: Start with requirements traceability matrix
47+
2. **Context Before Detail**: System context → component → implementation
48+
3. **Validation**: Validate models against requirements
49+
4. **Synchronization**: Keep models updated with code changes
50+
51+
### Model Formats
52+
- **Primary**: PlantUML (`.puml`) - version-controllable text-based diagrams
53+
- **Alternative**: Draw.io (`.drawio`) - for complex visual models
54+
- **Export**: SVG/PNG for documentation
55+
56+
### Traceability
57+
Each model must link to:
58+
- Requirements (in `docs/specifications/`)
59+
- Implementation (source code references)
60+
- Tests (test case IDs)
61+
- Documentation (architecture docs)
62+
63+
## Model Review Process
64+
65+
### Before Implementation
66+
1. ✅ Model reviewed by architect
67+
2. ✅ Validated against requirements
68+
3. ✅ Test scenarios derived from model
69+
4. ✅ Model checked into version control
70+
71+
### After Implementation
72+
1. ✅ Code matches model design
73+
2. ✅ Tests verify model behavior
74+
3. ✅ Model updated if design evolved
75+
4. ✅ Traceability links maintained
76+
77+
## Tools
78+
79+
### Recommended Modeling Tools
80+
- **PlantUML**: Text-based UML diagrams (preferred)
81+
- **Draw.io**: Visual diagram editor
82+
- **Mermaid**: Markdown-embedded diagrams
83+
- **SysML**: For complex system engineering models
84+
85+
### Installation
86+
```bash
87+
# PlantUML (requires Java)
88+
sudo apt-get install -y plantuml
89+
90+
# Generate diagrams from .puml files
91+
plantuml models/**/*.puml
92+
93+
# VSCode extension
94+
code --install-extension jebbs.plantuml
95+
```
96+
97+
## Example: TDD + MBSE Workflow
98+
99+
### Step 1: Create Component Model
100+
```plantuml
101+
@startuml orchestrator_component
102+
component "Orchestrator" {
103+
[Intent Parser]
104+
[QoS Mapper]
105+
[Resource Allocator]
106+
[State Manager]
107+
}
108+
@enduml
109+
```
110+
111+
### Step 2: Define Interface Contract
112+
```yaml
113+
# component/orchestrator-api.yaml
114+
IntentAPI:
115+
POST /intents:
116+
request: IntentSpec
117+
response: IntentStatus
118+
errors: [ValidationError, ResourceError]
119+
```
120+
121+
### Step 3: Write Tests (TDD)
122+
```go
123+
// orchestrator/pkg/intent/parser_test.go
124+
func TestParseIntent(t *testing.T) {
125+
// RED: Test fails (parser not implemented)
126+
tests := []struct{
127+
name string
128+
input IntentSpec
129+
want QoSProfile
130+
}{
131+
// Test cases from model
132+
}
133+
}
134+
```
135+
136+
### Step 4: Implement to Pass Tests
137+
```go
138+
// orchestrator/pkg/intent/parser.go
139+
func ParseIntent(spec IntentSpec) (QoSProfile, error) {
140+
// GREEN: Minimal implementation to pass test
141+
}
142+
```
143+
144+
### Step 5: Update Model with Implementation Details
145+
- Document actual implementation decisions
146+
- Update sequence diagrams with real call flows
147+
- Add notes on deviations from original design
148+
149+
## Current Models Status
150+
151+
| Model Type | Status | Last Updated | Reviewer |
152+
|------------|--------|--------------|----------|
153+
| System Context | 🟡 Draft | 2025-09-26 | - |
154+
| Component Architecture | 🟡 Draft | 2025-09-26 | - |
155+
| QoS Data Model | 🟢 Complete | 2025-09-26 | - |
156+
| Deployment Model | 🟡 Draft | 2025-09-26 | - |
157+
158+
**Status Legend**:
159+
- 🔴 Not Started
160+
- 🟡 Draft / In Progress
161+
- 🟢 Complete
162+
- ✅ Validated & Implemented
163+
164+
## Next Steps
165+
166+
### Priority Models to Create
167+
1. **System Context Diagram**: Define all external interfaces
168+
2. **Intent Processing Sequence**: End-to-end flow from intent to deployment
169+
3. **State Machine Models**: Slice lifecycle, VNF lifecycle
170+
4. **Network Topology Models**: RAN/TN/CN interconnection
171+
172+
### Model-Driven Code Generation
173+
Future enhancement: Generate code skeletons from models
174+
- API interfaces from component models
175+
- State machines from state diagrams
176+
- Data structures from data models
177+
178+
---
179+
180+
**Note**: All models must be reviewed and validated before implementation begins. Follow TDD principles: test scenarios are derived from models before coding starts.

0 commit comments

Comments
 (0)