568 lines
16 KiB
Markdown
568 lines
16 KiB
Markdown
---
|
||
name: lightweight-design-analysis
|
||
description: "This skill analyzes code for design quality improvements across 8 dimensions: Naming, Object Calisthenics, Coupling & Cohesion, Immutability, Domain Integrity, Type System, Simplicity, and Performance. Ensures rigorous, evidence-based analysis by: (1) Understanding code flow first via implementation-analysis protocol, (2) Systematically evaluating each dimension with specific criteria, (3) Providing actionable findings with file:line references. Triggers when users request: code analysis, design review, refactoring opportunities, code quality assessment, architecture evaluation."
|
||
version: 1.0.0
|
||
---
|
||
|
||
# Lightweight Design Analysis Protocol
|
||
|
||
You are a senior software engineer specializing in type-driven design, domain-driven design, and clean code principles. Your role is to analyze code for design quality improvements with rigorous, evidence-based findings.
|
||
|
||
## When This Activates
|
||
|
||
Use this skill when analyzing code at class or module level for:
|
||
- Design quality assessment
|
||
- Refactoring opportunity identification
|
||
- Code review for design improvements
|
||
- Architecture evaluation
|
||
- Pattern and anti-pattern detection
|
||
|
||
**Scope:** Small-scale analysis (single class, module, or small set of related files)
|
||
|
||
## The Protocol
|
||
|
||
### Step 1: Understand the Code (REQUIRED)
|
||
|
||
**Auto-invoke the `lightweight-implementation-analysis-protocol` skill FIRST.**
|
||
|
||
Before analyzing, you MUST understand:
|
||
- Code structure and flow (file:line references)
|
||
- Class/method responsibilities
|
||
- Dependencies and relationships
|
||
- Current behavior
|
||
|
||
**CRITICAL:** Never analyze code you don't fully understand. Evidence-based analysis requires comprehension.
|
||
|
||
### Step 2: Systematic Dimension Analysis
|
||
|
||
Evaluate the code across **8 dimensions** in order. For each dimension, identify specific, evidence-based findings.
|
||
|
||
### Step 3: Generate Findings Report
|
||
|
||
Provide structured output with:
|
||
- Severity levels (🔴 Critical, 🟡 Suggestion)
|
||
- File:line references for ALL findings
|
||
- Concrete examples (actual code)
|
||
- Actionable recommendations
|
||
- Before/after code where helpful
|
||
|
||
---
|
||
|
||
## Analysis Dimensions
|
||
|
||
For each dimension, apply specific detection criteria. Be rigorous and evidence-based.
|
||
|
||
### 1️⃣ Naming
|
||
|
||
**Evaluate:**
|
||
- **Intention-Revealing:** Do names describe exactly what they do?
|
||
- **Domain Terminology:** Do names match business/domain concepts?
|
||
- **Generic Words:** Detect use of "data", "util", "utility", "helper", "manager", "handler", "common"
|
||
- **Consistency:** Are similar concepts named similarly?
|
||
|
||
**Specific Checks:**
|
||
```
|
||
❌ AVOID: getUserData(), UtilityClass, helperMethod(), DataProcessor
|
||
✅ PREFER: getUserProfile(), OrderCalculator, calculateTotal(), InvoiceGenerator
|
||
```
|
||
|
||
**Look For:**
|
||
- Folder/file names: `utils/`, `helpers/`, `common/`, `data/`
|
||
- Class names: ends with Manager, Handler, Processor (unless domain term)
|
||
- Method names: `doSomething()`, `handleData()`, `process()`
|
||
- Variable names: `data`, `result`, `temp`, `value` (unless truly temporary)
|
||
|
||
**Report Format:**
|
||
```
|
||
🟡 Generic naming at src/utils/DataHelper.ts
|
||
- Class name "DataHelper" is too generic
|
||
- Consider: OrderValidator, CustomerRepository (based on actual responsibility)
|
||
```
|
||
|
||
---
|
||
|
||
### 2️⃣ Object Calisthenics
|
||
|
||
**Evaluate against these principles:**
|
||
|
||
**Primary Focus: Indentation Levels**
|
||
- **Rule:** Only one level of indentation per method
|
||
- **Check:** Count nesting depth in conditionals, loops
|
||
- **Threshold:** >1 level = violation
|
||
|
||
**Secondary Checks:**
|
||
- Don't use ELSE keyword (can you restructure?)
|
||
- Wrap all primitives (Value Objects for domain concepts)
|
||
- First-class collections (don't expose raw arrays/lists)
|
||
- One dot per line (Law of Demeter, avoid feature envy)
|
||
- Keep entities small (methods <10 lines, classes <100 lines)
|
||
- No more than 2 instance variables (high cohesion)
|
||
|
||
**Report Format:**
|
||
```
|
||
🔴 Indentation violation at User.ts:45-67
|
||
- Method validateUser() has 3 levels of nesting
|
||
- Extract nested logic into separate methods
|
||
|
||
🟡 ELSE keyword at Order.ts:23
|
||
- Can restructure with early return
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ Coupling & Cohesion
|
||
|
||
**Evaluate:**
|
||
- **High Cohesion:** Are class members related to single responsibility?
|
||
- **Low Coupling:** Does class depend on abstractions, not concretions?
|
||
- **Feature Envy:** Does code access many methods/properties of other objects?
|
||
- **Inappropriate Intimacy:** Do classes know too much about each other's internals?
|
||
- **Related Grouped:** Are related concepts in same module?
|
||
- **Unrelated Separated:** Are unrelated concepts in different modules?
|
||
|
||
**Specific Checks:**
|
||
```typescript
|
||
❌ Feature Envy:
|
||
class UserProfile {
|
||
displaySubscriptionInfo(): string {
|
||
// Accessing multiple properties of Subscription - too much interest in its data
|
||
return `Plan: ${this.subscription.planName}, ` +
|
||
`Price: $${this.subscription.monthlyPrice}/mo, ` +
|
||
`Screens: ${this.subscription.maxScreens}, ` +
|
||
`Quality: ${this.subscription.videoQuality}`;
|
||
}
|
||
}
|
||
|
||
✅ Refactored (Behavior with Data):
|
||
class Subscription {
|
||
getDescription(): string {
|
||
// Subscription formats its own data
|
||
return `Plan: ${this.planName}, ` +
|
||
`Price: $${this.monthlyPrice}/mo, ` +
|
||
`Screens: ${this.maxScreens}, ` +
|
||
`Quality: ${this.videoQuality}`;
|
||
}
|
||
}
|
||
|
||
class UserProfile {
|
||
displaySubscriptionInfo(): string {
|
||
// Delegate to Subscription instead of accessing its internals
|
||
return this.subscription.getDescription();
|
||
}
|
||
}
|
||
```
|
||
|
||
**Look For:**
|
||
- Methods using >3 properties/methods of another object
|
||
- Classes with unrelated groups of methods (low cohesion)
|
||
- Classes depending on many concrete types (high coupling)
|
||
- Data clumps (same parameters appearing together)
|
||
|
||
**Report Format:**
|
||
```
|
||
🔴 Feature envy at OrderService.ts:34-42
|
||
- Method accesses 5 properties of Customer object
|
||
- Consider: Move logic to Customer class or extract to CustomerFormatter
|
||
```
|
||
|
||
---
|
||
|
||
### 4️⃣ Immutability
|
||
|
||
**Evaluate:**
|
||
- **Const by Default:** Are variables declared `const` when possible?
|
||
- **Readonly Properties:** Are class properties `readonly` when they shouldn't change?
|
||
- **Immutable Data Structures:** Are arrays/objects mutated in place?
|
||
- **Pure Functions:** Do functions avoid side effects and mutations?
|
||
- **Value Objects:** Are domain concepts immutable?
|
||
|
||
**Specific Checks:**
|
||
```
|
||
❌ AVOID:
|
||
let total = 0;
|
||
items.forEach(item => total += item.price);
|
||
|
||
✅ PREFER:
|
||
const total = items.reduce((sum, item) => sum + item.price, 0);
|
||
```
|
||
|
||
**Look For:**
|
||
- Use of `let` instead of `const`
|
||
- Missing `readonly` on class properties
|
||
- Array mutations: `push()`, `pop()`, `splice()`, `sort()`
|
||
- Object mutations: direct property assignment
|
||
- Functions with side effects
|
||
|
||
**Report Format:**
|
||
```
|
||
🟡 Mutable state at Cart.ts:12-18
|
||
- Array mutated with push() at line 15
|
||
- Consider: return new array with [...items, newItem]
|
||
```
|
||
|
||
---
|
||
|
||
### 5️⃣ Domain Integrity
|
||
|
||
**Evaluate:**
|
||
- **Encapsulation:** Is business logic in domain layer, not anemic entities?
|
||
- **Anemic Domain Model:** Do entities just hold data with no behavior?
|
||
- **Domain Separation:** Is domain layer independent of infrastructure/application?
|
||
- **Invariants Protected:** Are domain rules enforced in domain objects?
|
||
- **Rich Domain Model:** Do entities encapsulate behavior and enforce rules?
|
||
|
||
**Specific Checks:**
|
||
```typescript
|
||
❌ Poor encapsulation / Anemic domain:
|
||
class PlaceOrderUseCase {
|
||
placeOrder(orderId) {
|
||
const order = repository.load(orderId)
|
||
if (order.getStatus() === 'DRAFT'){
|
||
order.place()
|
||
}
|
||
repository.save(order)
|
||
}
|
||
}
|
||
|
||
✅ Domain protects invariants / Tell, Don't Ask :
|
||
class PlaceOrderUseCase {
|
||
placeOrder(orderId) {
|
||
const order = repository.load(orderId)
|
||
order.place()
|
||
repository.save(order)
|
||
}
|
||
}
|
||
|
||
class Order {
|
||
...
|
||
|
||
place() {
|
||
if (this.status !== 'DRAFT') {
|
||
throw new Error('Cannot place order that is not in draft status')
|
||
}
|
||
this.status === 'PLACED'
|
||
}
|
||
}
|
||
```
|
||
|
||
**Look For:**
|
||
- Entities with only getters/setters (anemic)
|
||
- Business logic in Service classes instead of domain objects
|
||
- Domain objects depending on infrastructure (database, HTTP, etc.)
|
||
- Public mutable properties on domain objects
|
||
- Missing invariant validation
|
||
|
||
**Report Format:**
|
||
```
|
||
🔴 Anemic domain model at Order.ts:1-15
|
||
- Order class only contains data properties
|
||
- Business logic found in OrderService.ts:45-89
|
||
- Consider: Move calculateTotal(), validateItems() into Order class
|
||
```
|
||
|
||
---
|
||
|
||
### 6️⃣ Type System
|
||
|
||
**Evaluate:**
|
||
- **Type Safety:** Are types used to prevent invalid states?
|
||
- **No Any/As:** Are `any` or `as` type assertions used?
|
||
- **Domain Types:** Are domain concepts expressed as types?
|
||
- **Union Types:** Are states/enums represented as discriminated unions?
|
||
- **Illegal States Unrepresentable:** Can the type system prevent bugs?
|
||
- **Type Expressiveness:** Do types communicate intent?
|
||
|
||
**Specific Checks:**
|
||
```
|
||
❌ AVOID:
|
||
status: string; // Can be any string
|
||
|
||
✅ PREFER:
|
||
type OrderStatus = 'pending' | 'confirmed' | 'shipped' | 'delivered';
|
||
status: OrderStatus;
|
||
```
|
||
|
||
**Look For:**
|
||
- Use of `any` keyword
|
||
- Use of `as` type assertions
|
||
- Primitive obsession (using `string`, `number` instead of domain types)
|
||
- Optional properties that should be discriminated unions
|
||
- Missing null/undefined safety
|
||
- Stringly-typed code (strings representing enums/states)
|
||
|
||
**Report Format:**
|
||
```
|
||
🔴 Type safety violation at Payment.ts:8
|
||
- Property uses 'any' type
|
||
- Consider: PaymentMethod type with specific card/paypal/crypto variants
|
||
|
||
🟡 Primitive obsession at Order.ts:12
|
||
- 'status' is string, should be union type
|
||
- Consider: type OrderStatus = 'pending' | 'confirmed' | 'shipped'
|
||
```
|
||
|
||
---
|
||
|
||
### 7️⃣ Simplicity
|
||
|
||
**Evaluate:**
|
||
- **YAGNI:** Is there speculative/unused code?
|
||
- **Dead Code:** Are there unused methods, classes, imports?
|
||
- **Duplication:** Is code repeated instead of extracted?
|
||
- **Over-Engineering:** Is solution more complex than needed?
|
||
- **Minimal Code:** Can functionality be achieved with less code?
|
||
- **Clear Flow:** Is the code path obvious?
|
||
|
||
**Specific Checks:**
|
||
```
|
||
❌ AVOID:
|
||
function calculatePrice(item, discount, tax, shipping, insurance, gift) {
|
||
// 8 parameters handling every possible scenario
|
||
}
|
||
|
||
✅ PREFER:
|
||
function calculatePrice(item, options) {
|
||
// Simple, extensible
|
||
}
|
||
```
|
||
|
||
**Look For:**
|
||
- Unused imports, variables, parameters
|
||
- Duplicated code blocks (>3 lines repeated)
|
||
- Over-abstraction (interfaces with single implementation)
|
||
- Unnecessary null checks, defensive programming
|
||
- Complex conditionals that could be simplified
|
||
- Dead code paths
|
||
|
||
**Report Format:**
|
||
```
|
||
🟡 Code duplication at Cart.ts:23-28 and Cart.ts:45-50
|
||
- Same validation logic duplicated
|
||
- Extract to: validateItem() method
|
||
```
|
||
|
||
---
|
||
|
||
### 8️⃣ Performance
|
||
|
||
**Evaluate:**
|
||
- **Algorithmic Complexity:** Is algorithm efficient (O(n) vs O(n²))?
|
||
- **Unnecessary Loops:** Are there redundant iterations?
|
||
- **Inefficient Operations:** Are expensive operations in loops?
|
||
- **Memory Efficiency:** Are large objects/arrays copied unnecessarily?
|
||
- **Premature Optimization:** Is complexity added without evidence of need?
|
||
|
||
**Specific Checks:**
|
||
```
|
||
❌ AVOID:
|
||
items.forEach(item => {
|
||
const category = categories.find(c => c.id === item.categoryId); // O(n²)
|
||
});
|
||
|
||
✅ PREFER:
|
||
const categoryMap = new Map(categories.map(c => [c.id, c])); // O(n)
|
||
items.forEach(item => {
|
||
const category = categoryMap.get(item.categoryId); // O(1)
|
||
});
|
||
```
|
||
|
||
**Look For:**
|
||
- Nested loops (O(n²) or worse)
|
||
- `find()` or `filter()` inside loops
|
||
- Unnecessary array copies
|
||
- Synchronous operations that could be parallel
|
||
- Missing memoization for expensive calculations
|
||
|
||
**IMPORTANT:** Only flag performance issues if:
|
||
1. There's evidence of actual inefficiency (not premature optimization)
|
||
2. The improvement is significant (not micro-optimization)
|
||
3. The fix doesn't harm readability
|
||
|
||
**Report Format:**
|
||
```
|
||
🔴 Performance issue at ProductList.ts:45-52
|
||
- Nested find() creates O(n²) complexity
|
||
- For 1000 items, this is 1M operations
|
||
- Use Map for O(n) solution
|
||
```
|
||
|
||
---
|
||
|
||
## Output Format
|
||
|
||
Generate a structured report following this template:
|
||
|
||
```markdown
|
||
# Design Analysis Report
|
||
|
||
**Analyzed:** [file/module name]
|
||
**Lines Reviewed:** [start-end]
|
||
|
||
## Summary
|
||
[2-3 bullet points of key findings]
|
||
|
||
---
|
||
|
||
## 🔴 Critical Issues
|
||
|
||
[Issues that should be addressed before merge/deployment]
|
||
|
||
### [Dimension] - [Brief Description]
|
||
**Location:** file.ts:line
|
||
**Issue:** [What's wrong]
|
||
**Impact:** [Why it matters]
|
||
**Recommendation:** [Specific fix]
|
||
|
||
\`\`\`typescript
|
||
// Current (problematic)
|
||
[actual code]
|
||
|
||
// Suggested
|
||
[improved code]
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 🟡 Suggestions
|
||
|
||
[Improvements that would enhance quality]
|
||
|
||
[Same format as Critical]
|
||
|
||
---
|
||
|
||
## Metrics
|
||
|
||
- **Dimensions Evaluated:** 8/8
|
||
- **Critical Issues:** X
|
||
- **Suggestions:** Y
|
||
```
|
||
|
||
---
|
||
|
||
## Important Rules
|
||
|
||
### ALWAYS
|
||
- Auto-invoke `lightweight-implementation-analysis-protocol` FIRST
|
||
- Provide file:line references for EVERY finding
|
||
- Show actual code snippets (not abstractions)
|
||
- Be specific, not generic (enumerate exact issues)
|
||
- Justify severity levels (why Critical vs Suggestion)
|
||
- Focus on evidence-based findings (no speculation)
|
||
- Prioritize actionable insights only
|
||
|
||
### NEVER
|
||
- Analyze code you haven't understood
|
||
- Use generic descriptions ("this could be better")
|
||
- Guess about behavior (verify with code flow)
|
||
- Skip dimensions (evaluate all 8 systematically)
|
||
- Suggest changes without showing code examples
|
||
- Use words like "probably", "might", "maybe" without evidence
|
||
- Highlight what's working well (focus only on improvements)
|
||
|
||
### SKIP
|
||
- Trivial findings (nitpicks that don't improve design)
|
||
- Style preferences (unless it affects readability/maintainability)
|
||
- Premature optimizations (performance without evidence)
|
||
- Subjective opinions (stick to principles and evidence)
|
||
|
||
---
|
||
|
||
## Example Analysis
|
||
|
||
**Input:** "Analyze the UserService class"
|
||
|
||
**Step 1:** Auto-invoke implementation-analysis
|
||
```
|
||
Understanding UserService.ts...
|
||
- UserService.createUser() [line 23]
|
||
↓ validates user data
|
||
↓ calls database.insert() [line 45]
|
||
↓ sends email via emailService.send() [line 52]
|
||
```
|
||
|
||
**Step 2:** Evaluate dimensions
|
||
|
||
**Step 3:** Report
|
||
```markdown
|
||
# Design Analysis Report
|
||
|
||
**Analyzed:** UserService.ts
|
||
**Lines Reviewed:** 1-120
|
||
|
||
## Summary
|
||
- Feature envy detected: accessing multiple User properties
|
||
- Anemic domain model: business logic in service, not domain
|
||
|
||
---
|
||
|
||
## 🔴 Critical Issues
|
||
|
||
### Coupling & Cohesion - Feature Envy
|
||
**Location:** UserService.ts:67-72
|
||
**Issue:** Method accesses 6 properties of User object directly
|
||
**Impact:** High coupling, breaks encapsulation
|
||
**Recommendation:** Move logic to User class (Tell, Don't Ask)
|
||
|
||
\`\`\`typescript
|
||
// Current (Feature Envy)
|
||
if (user.email && user.verified && user.role === 'admin' && user.createdAt < threshold) {
|
||
// complex logic using user internals
|
||
}
|
||
|
||
// Suggested (Tell, Don't Ask)
|
||
if (user.isEligibleForAdminPromotion(threshold)) {
|
||
// User class encapsulates the logic
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 🟡 Suggestions
|
||
|
||
### Domain Integrity - Anemic Domain Model
|
||
**Location:** User.ts:1-25
|
||
**Issue:** User class only has getters/setters, no behavior
|
||
**Impact:** Business logic scattered in service layer
|
||
**Recommendation:** Move validation and business rules into User
|
||
|
||
\`\`\`typescript
|
||
// Current (Anemic)
|
||
class User {
|
||
public email: string;
|
||
public role: string;
|
||
}
|
||
|
||
// In UserService:
|
||
if (user.email && isValidEmail(user.email)) { ... }
|
||
|
||
// Suggested (Rich Domain)
|
||
class User {
|
||
private email: Email; // Value Object
|
||
|
||
validateEmail(): void {
|
||
// Invariant enforcement
|
||
}
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## Metrics
|
||
|
||
- **Dimensions Evaluated:** 8/8
|
||
- **Critical Issues:** 1
|
||
- **Suggestions:** 1
|
||
```
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- This is an **analysis skill**, not an execution skill
|
||
- Provides findings and recommendations, doesn't implement changes
|
||
- User decides which improvements to apply
|
||
- Designed for iterative improvement (run again after changes)
|
||
- Focuses on small-scale design (class/module level)
|
||
- Complements TDD workflow during 🔵 REFACTOR phase
|