| name | architecture-evolution-tracking |
| description | Track architectural decisions and detect drift from ADRs (Architecture Decision Records). Calculate alignment score (0.00-1.00) showing code-to-design conformance. Auto-detect architectural violations and suggest refactoring. Integrate with Serena for architectural health monitoring. Use when: maintaining architectural integrity, reviewing large changes, documenting decisions, detecting drift, enforcing standards.
|
| skill-type | STRUCTURAL |
| shannon-version | >=5.6.0 |
| mcp-requirements | {"recommended":[{"name":"serena","purpose":"Architecture compliance tracking, alerting, metrics"},{"name":"structure101","purpose":"Dependency analysis and architecture visualization"},{"name":"sonargraph","purpose":"Architecture quality metrics"},{"name":"qmstool","purpose":"Dependency structure matrix"}]} |
| allowed-tools | All |
Architecture Evolution Tracking - Quantified Design Alignment
Purpose
Maintain alignment between code and architectural decisions. Calculate alignment score (0.00-1.00) showing conformance to ADRs. Auto-detect violations like circular dependencies, layer violations, and unauthorized coupling. Track architecture health via Serena MCP.
When to Use
- Reviewing large architectural changes
- Detecting unauthorized couplings between modules
- Monitoring compliance with ADRs
- Preventing architectural drift
- Planning refactoring work
- Measuring architecture quality evolution
Core Metrics
Alignment Score Calculation:
Score = 1.0 - (Violations / Total Dependencies) × 1.0
Range: 0.00 (complete chaos) to 1.00 (perfect alignment)
Violations: Unauthorized dependencies, circular refs, layer violations
Total Dependencies: All module-to-module connections
Example: 5 violations in 200 dependencies = 0.975 score
Violation Types & Impact:
- Circular dependencies: -0.15 per cycle
- Layer violations: -0.10 per violation
- Unauthorized coupling: -0.05 per edge
- Missing abstraction: -0.05 per case
Architecture Scoring:
Component: User Authentication Service
├─ Allowed dependencies: Core, Utils
├─ Actual dependencies: Core, Utils, Payment (VIOLATION)
├─ Violations: 1 (unauthorized Payment coupling)
├─ Alignment: 0.90 (1 violation in 10 deps)
└─ Status: ⚠️ Review needed
Component: Payment Processing
├─ Allowed: Core, Database, Logging
├─ Actual: Core → Auth (CIRCULAR), Database, Logging
├─ Violations: 2 (circular + missing abstraction)
├─ Alignment: 0.80
└─ Status: ❌ Critical refactoring needed
Workflow
Phase 1: ADR Definition
- Document decisions: Create ADRs for major design choices
- Define boundaries: Specify allowed module dependencies
- Set rules: Layer separation, coupling limits
- Establish baseline: Calculate initial alignment
ADR Format Example:
ADR-001: Layered Architecture
Decision:
Implement 4-layer architecture:
├─ Presentation (API, UI)
├─ Business Logic (Services)
├─ Data Access (Repositories)
└─ Infrastructure (Database, Cache)
Rules:
✓ Presentation → Business Logic
✓ Business Logic → Data Access
✓ Data Access → Infrastructure
✗ Backwards dependencies forbidden
✗ No cross-layer skipping
Phase 2: Drift Detection
- Analyze dependencies: Map actual code connections
- Compare to ADRs: Identify deviations
- Classify violations: Circular, layer breach, unauthorized
- Calculate score: Quantify alignment
- Generate report: Violations with locations
Drift Detection Report:
Architecture Alignment Score: 0.82
Status: ⚠️ Acceptable but drifting
Violations (5 total):
1. [CRITICAL] Circular: Auth ← → Payment (bidirectional)
Files: src/auth/service.ts, src/payment/processor.ts
Recommendation: Extract shared logic to Core module
2. [HIGH] Layer violation: UI imports Payment (skips Logic)
Files: src/ui/checkout.tsx imports src/payment/api.ts
Recommendation: Route through Service layer
3. [MEDIUM] Unauthorized: Logging imports Caching
Files: src/logging/logger.ts imports src/cache/redis.ts
Recommendation: Move redis to Infrastructure, use interface
Trend: Score dropped 0.05 over 2 weeks (drifting)
Phase 3: Refactoring Guidance
- Suggest refactors: Extract abstractions, break cycles
- Rank by impact: Highest score improvement first
- Provide examples: Show architecture-preserving patterns
- Estimate effort: Complexity of each refactor
Auto-Generated Refactoring Plan:
Option A (Impact: +0.08, Effort: Medium):
Extract PaymentInterface from Payment service
├─ Create: src/core/interfaces/payment.ts
├─ Define: interface IPaymentProcessor
├─ Auth uses interface, not concrete Payment
└─ Breaks circular dependency
Option B (Impact: +0.05, Effort: Low):
Move caching utilities to Infrastructure
├─ Move: src/cache → src/infrastructure/caching
├─ Update imports in 3 files
├─ Preserves layer separation
Phase 4: Serena Integration
- Track alignment: Store score by commit, date
- Alert on drift: Notify if score drops >0.05
- Correlate commits: Identify who introduced violations
- Forecast trend: Predict alignment in 30 days
- Schedule refactoring: Plan when to fix violations
Serena Push Format:
{
"metric_type": "architecture_alignment",
"project": "task-app",
"alignment_score": 0.82,
"violations": {
"circular": 1,
"layer_breach": 2,
"unauthorized": 2
},
"violating_modules": [
"auth",
"payment",
"ui"
],
"refactoring_priority": "HIGH",
"estimated_effort_hours": 16,
"timestamp": "2025-11-20T14:00:00Z"
}
Real-World Impact
Enterprise CRM System:
- Alignment score started: 0.65 (heavy circular dependencies)
- Serena tracked violations: 8 circular, 12 layer breaches
- Systematic refactoring over 6 sprints
- Final score: 0.94 (improved +0.29)
- Benefits: 40% reduction in integration bugs, easier testing
Microservices Migration:
- Initial: 0.88 (monolith had clean layers)
- Split into 5 services: 0.72 (interdependencies created drift)
- Serena alerted on 15 cross-service violations
- Implemented saga pattern + event bus
- Restored to 0.91 (services truly independent)
Success Criteria
✅ Alignment score ≥0.90 maintained
✅ No circular dependencies
✅ All layers properly separated
✅ Violations tracked in Serena with remediation plans
✅ New code reviewed against ADRs
✅ Refactoring priorities data-driven by alignment impact
