Architecture Review Skill

Step 1: Gather Architecture Context

Understand the current architecture by:

1. Read project structure: Use Glob to map directory structure
2. Identify key components: Find entry points, services, data layers
3. Review dependencies: Check package.json, imports, module graph
4. Understand data flow: Trace requests through the system

Step 2: Evaluate Design Principles

Check adherence to fundamental principles:

SOLID Principles:

• Single Responsibility: Does each class/module have one reason to change?
• Open/Closed: Can behavior be extended without modification?
• Liskov Substitution: Are subtypes substitutable for base types?
• Interface Segregation: Are interfaces focused and minimal?
• Dependency Inversion: Do high-level modules depend on abstractions?

Other Principles:

• DRY: Is logic duplicated unnecessarily?
• YAGNI: Are there unused or speculative features?
• Separation of Concerns: Are responsibilities properly divided?

Step 3: Check for Anti-Patterns

Identify common anti-patterns:

• God Class/Module: Classes doing too much
• Spaghetti Code: Tangled, hard-to-follow logic
• Circular Dependencies: Modules that reference each other
• Feature Envy: Classes that use other classes’ data excessively
• Shotgun Surgery: Changes that require touching many files
• Leaky Abstractions: Implementation details exposed to consumers

Step 4: Assess Non-Functional Requirements

Evaluate against NFRs:

• Scalability: Can the system handle increased load?
• Maintainability: How easy is it to modify and extend?
• Testability: Can components be tested in isolation?
• Security: Are there potential vulnerabilities?
• Performance: Are there obvious bottlenecks?
• Observability: Can the system be monitored effectively?

Step 5: Generate Review Report

Create a structured report with:

1. Summary: Overall assessment and key findings
2. Strengths: What the architecture does well
3. Concerns: Issues requiring attention (prioritized)
4. Recommendations: Specific improvements with rationale
5. Trade-offs: Acknowledge valid design trade-offs

</execution_process>

<best_practices>

1. Be Constructive: Focus on improvements, not criticism
2. Prioritize Issues: Not all problems are equally important
3. Consider Context: Understand constraints and trade-offs
4. Suggest Alternatives: Don’t just identify problems
5. Reference Patterns: Cite established patterns when relevant

</best_practices>

Review the architecture of src/services/ for scalability and maintainability

Example Response Structure:

## Architecture Review: src/services/

### Summary

The service layer follows a reasonable structure but has some coupling issues...

### Strengths

- Clear separation between API handlers and business logic
- Good use of dependency injection

### Concerns

1. **High Priority**: UserService has 15 methods (God Class)
2. **Medium Priority**: Circular dependency between OrderService and InventoryService
3. **Low Priority**: Some magic numbers in validation logic

### Recommendations

1. Split UserService into UserAuthService and UserProfileService
2. Introduce EventBus to decouple Order and Inventory
3. Extract validation constants to configuration

</usage_example>

Rules

• Always provide constructive feedback with actionable recommendations
• Prioritize issues by impact and effort to fix
• Consider existing constraints and trade-offs

Related Workflow

This skill has a corresponding workflow for complex multi-agent scenarios:

• Workflow: .claude/workflows/architecture-review-skill-workflow.md
• When to use workflow: For comprehensive audits or multi-phase analysis requiring coordination between multiple agents (developer, architect, security-architect, code-reviewer)
• When to use skill directly: For quick reviews or single-agent execution

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it’s not in memory, it didn’t happen.