138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# Lightweight Design Analysis
|
|
|
|
> A Claude Code skill for rigorous, evidence-based code design analysis across 8 quality dimensions
|
|
|
|
## What It Does
|
|
|
|
Analyzes code at the class or module level to identify design improvement opportunities across:
|
|
|
|
1. **Naming** - Intention-revealing names, domain terminology, avoiding generic words
|
|
2. **Object Calisthenics** - Especially indentation levels, small methods, single responsibility
|
|
3. **Coupling & Cohesion** - Feature envy, inappropriate intimacy, grouping related concepts
|
|
4. **Immutability** - Const by default, readonly properties, pure functions
|
|
5. **Domain Integrity** - Rich domain models, avoiding anemic entities, encapsulation
|
|
6. **Type System** - Making illegal states unrepresentable, avoiding `any`/`as`
|
|
7. **Simplicity** - Removing duplication, dead code, over-engineering
|
|
8. **Performance** - Algorithmic efficiency (only evidence-based, not premature optimization)
|
|
|
|
## When to Use
|
|
|
|
Invoke this skill when you want to:
|
|
|
|
- **Analyze code quality** before or after implementation
|
|
- **Find refactoring opportunities** in existing code
|
|
- **Review design** of a class or module
|
|
- **Identify anti-patterns** like anemic domain models or feature envy
|
|
- **Assess type safety** and domain modeling
|
|
|
|
**Perfect for:** The 🔵 REFACTOR phase of TDD workflow
|
|
|
|
## How It Works
|
|
|
|
1. **Understands First** - Auto-invokes `lightweight-implementation-analysis-protocol` to comprehend code flow
|
|
2. **Systematic Evaluation** - Analyzes all 8 dimensions with specific, evidence-based criteria
|
|
3. **Structured Report** - Provides findings with severity levels (🔴 Critical, 🟡 Suggestion)
|
|
4. **Actionable Recommendations** - Shows before/after code examples with file:line references
|
|
|
|
## Philosophy
|
|
|
|
This skill embodies principles from:
|
|
|
|
- **Type-Driven Development** (Scott Wlaschin) - Use types to express domain concepts
|
|
- **Domain-Driven Design** (Eric Evans) - Rich domain models with encapsulated behavior
|
|
- **Object Calisthenics** (Jeff Bay) - Strict coding constraints that enforce good design
|
|
- **Clean Code** (Robert C. Martin) - Intention-revealing names, single responsibility
|
|
- **Working Effectively with Legacy Code** (Michael Feathers) - Identifying improvement opportunities
|
|
|
|
## Example Usage
|
|
|
|
```
|
|
User: "Analyze the Order class for design improvements"
|
|
|
|
Claude: [Auto-invokes implementation-analysis to understand Order.ts]
|
|
|
|
Claude: [Generates design analysis report]
|
|
|
|
# Design Analysis Report
|
|
|
|
**Analyzed:** Order.ts
|
|
**Lines Reviewed:** 1-85
|
|
|
|
## Summary
|
|
- Anemic domain model detected: Order has no business logic
|
|
- Feature envy: OrderService accesses many Order properties
|
|
|
|
## 🔴 Critical Issues
|
|
|
|
### Domain Integrity - Anemic Domain Model
|
|
**Location:** Order.ts:1-30
|
|
**Issue:** Order class only stores data, no business behavior
|
|
**Impact:** Business logic scattered across services, hard to maintain
|
|
**Recommendation:** Move calculateTotal() and validateItems() into Order
|
|
|
|
[Code examples...]
|
|
|
|
## 🟡 Suggestions
|
|
|
|
### Object Calisthenics - Indentation
|
|
**Location:** Order.ts:42-58
|
|
**Issue:** Method has 3 levels of nesting
|
|
**Recommendation:** Extract nested logic to separate methods
|
|
|
|
[Code examples...]
|
|
|
|
## Metrics
|
|
- Dimensions Evaluated: 8/8
|
|
- Critical Issues: 1
|
|
- Suggestions: 2
|
|
```
|
|
|
|
## Output Format
|
|
|
|
Every finding includes:
|
|
|
|
- **Severity Level:** 🔴 Critical | 🟡 Suggestion
|
|
- **Dimension:** Which of the 8 dimensions
|
|
- **Location:** Exact file:line reference
|
|
- **Issue:** What's wrong (evidence-based)
|
|
- **Impact:** Why it matters
|
|
- **Recommendation:** Specific, actionable fix
|
|
- **Code Example:** Before/after snippets
|
|
|
|
## Integration
|
|
|
|
- **Auto-invokes** `lightweight-implementation-analysis-protocol` to understand code first
|
|
- **Complements** your TDD workflow during refactoring phases
|
|
- **Iterative** - Run again after applying improvements to measure progress
|
|
|
|
## Key Principles
|
|
|
|
✅ **Evidence-Based** - Every finding has file:line reference and code example
|
|
✅ **Specific, Not Generic** - Explicit detection criteria (2.54x more effective)
|
|
✅ **Systematic** - Evaluates all 8 dimensions, nothing missed
|
|
✅ **Actionable** - Shows exact code improvements, not abstract suggestions
|
|
✅ **Rigorous** - No speculation ("probably", "maybe"), only verified findings
|
|
✅ **Focused** - Only highlights issues and improvements, no noise
|
|
|
|
❌ **Never Guesses** - Understands code flow first via implementation-analysis
|
|
❌ **Not Execution** - Provides analysis and recommendations, doesn't implement
|
|
❌ **Not Nitpicky** - Skips trivial style preferences, focuses on design
|
|
❌ **Not Premature** - Only flags performance issues with evidence of inefficiency
|
|
|
|
## Version History
|
|
|
|
- **v1.0.0** - Initial release with 8 core dimensions
|
|
|
|
## Contributing
|
|
|
|
This is a living skill that evolves based on what works. After using it, consider:
|
|
|
|
- Adding new dimensions if gaps are discovered
|
|
- Refining criteria if false positives occur
|
|
- Updating examples with real-world findings
|
|
- Adjusting severity thresholds based on experience
|
|
|
|
## Author
|
|
|
|
Created for iterative, evidence-based code design improvement.
|