Architecture Review Skill
Step 1: Gather Architecture Context
Understand the current architecture by:
- Read project structure: Use Glob to map directory structure
- Identify key components: Find entry points, services, data layers
- Review dependencies: Check package.json, imports, module graph
- 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:
- Summary: Overall assessment and key findings
- Strengths: What the architecture does well
- Concerns: Issues requiring attention (prioritized)
- Recommendations: Specific improvements with rationale
- Trade-offs: Acknowledge valid design trade-offs
- Be Constructive: Focus on improvements, not criticism
- Prioritize Issues: Not all problems are equally important
- Consider Context: Understand constraints and trade-offs
- Suggest Alternatives: Don't just identify problems
- Reference Patterns: Cite established patterns when relevant
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
Iron Laws
- ALWAYS review architecture before COMPLEX or EPIC implementation starts — architectural problems discovered after implementation cost 10-100x more to fix; review in the design phase.
- NEVER approve an architecture with undocumented single points of failure — every SPOF must be explicitly identified and have a documented mitigation plan.
- ALWAYS evaluate against non-functional requirements — performance, security, scalability, maintainability, and observability are non-optional; functional correctness without NFR compliance is incomplete.
- NEVER treat architectural trade-offs as implicit — every trade-off must be explicitly documented with rationale; hidden trade-offs become future surprises and unowned technical debt.
- ALWAYS check for circular dependencies before approving a design — circular module dependencies make testing, refactoring, and deployment order unpredictable and progressively harder to resolve.
Anti-Patterns
| Anti-Pattern |
Why It Fails |
Correct Approach |
| No NFR evaluation |
Design may pass functional tests but fail at scale or under attack |
Always evaluate performance, security, scalability, observability |
| Reviewing only the happy path |
Systems fail at error boundaries, not in the happy path |
Review failure modes, retry behavior, and circuit breakers |
| Approving without trade-off documentation |
Hidden trade-offs become future surprises |
Explicitly document all trade-offs with rationale |
| Single point of failure left undocumented |
System has silent fragility that surfaces under load |
Map all SPOFs; require mitigation plans for each |
| Checking SOLID without anti-pattern catalog |
Principle adherence doesn't guarantee absence of anti-patterns |
Check both principles AND concrete anti-patterns (God Class, Shotgun Surgery, etc.) |
| Architecture review after implementation starts |
Too late to fix structural issues without major rework |
Review in design phase, before any code is written |
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.
1---2name: architecture-review3description: Architecture review and design validation. Evaluates system designs against best practices, identifies anti-patterns, and ensures architectural decisions align with non-functional requirements.4version: 1.1.05model: sonnet6invoked_by: both7user_invocable: true8tools: [Read, Write, Edit, Glob, Grep]9best_practices:10 - Evaluate designs against SOLID principles11 - Check for anti-patterns and code smells12 - Verify non-functional requirements13 - Document architectural decisions14 - Always document trade-offs explicitly15error_handling: graceful16streaming: supported17verified: true18lastVerifiedAt: 2026-02-22T00:00:00.000Z19source: builtin20trust_score: 10021provenance_sha: 0417ac48c5242cbc22metadata:23 source: https://skillmd.com/skills/oimiragieo/architecture-review24---2526# Architecture Review Skill2728<identity>29Architecture Review Skill - Evaluates system designs against best practices, identifies anti-patterns, and ensures architectural decisions align with non-functional requirements (scalability, maintainability, security, performance).30</identity>3132<capabilities>33- Reviewing system architecture designs34- Identifying anti-patterns and architectural smells35- Validating against SOLID, DRY, YAGNI principles36- Assessing non-functional requirements37- Recommending architectural improvements38</capabilities>3940<instructions>41<execution_process>4243### Step 1: Gather Architecture Context4445Understand the current architecture by:46471. **Read project structure**: Use Glob to map directory structure482. **Identify key components**: Find entry points, services, data layers493. **Review dependencies**: Check package.json, imports, module graph504. **Understand data flow**: Trace requests through the system5152### Step 2: Evaluate Design Principles5354Check adherence to fundamental principles:5556**SOLID Principles**:5758- **S**ingle Responsibility: Does each class/module have one reason to change?59- **O**pen/Closed: Can behavior be extended without modification?60- **L**iskov Substitution: Are subtypes substitutable for base types?61- **I**nterface Segregation: Are interfaces focused and minimal?62- **D**ependency Inversion: Do high-level modules depend on abstractions?6364**Other Principles**:6566- **DRY**: Is logic duplicated unnecessarily?67- **YAGNI**: Are there unused or speculative features?68- **Separation of Concerns**: Are responsibilities properly divided?6970### Step 3: Check for Anti-Patterns7172Identify common anti-patterns:7374- **God Class/Module**: Classes doing too much75- **Spaghetti Code**: Tangled, hard-to-follow logic76- **Circular Dependencies**: Modules that reference each other77- **Feature Envy**: Classes that use other classes' data excessively78- **Shotgun Surgery**: Changes that require touching many files79- **Leaky Abstractions**: Implementation details exposed to consumers8081### Step 4: Assess Non-Functional Requirements8283Evaluate against NFRs:8485- **Scalability**: Can the system handle increased load?86- **Maintainability**: How easy is it to modify and extend?87- **Testability**: Can components be tested in isolation?88- **Security**: Are there potential vulnerabilities?89- **Performance**: Are there obvious bottlenecks?90- **Observability**: Can the system be monitored effectively?9192### Step 5: Generate Review Report9394Create a structured report with:95961. **Summary**: Overall assessment and key findings972. **Strengths**: What the architecture does well983. **Concerns**: Issues requiring attention (prioritized)994. **Recommendations**: Specific improvements with rationale1005. **Trade-offs**: Acknowledge valid design trade-offs101102</execution_process>103104<best_practices>1051061. **Be Constructive**: Focus on improvements, not criticism1072. **Prioritize Issues**: Not all problems are equally important1083. **Consider Context**: Understand constraints and trade-offs1094. **Suggest Alternatives**: Don't just identify problems1105. **Reference Patterns**: Cite established patterns when relevant111112</best_practices>113</instructions>114115<examples>116<usage_example>117**Example Review Request**:118119```120Review the architecture of src/services/ for scalability and maintainability121```122123**Example Response Structure**:124125```markdown126## Architecture Review: src/services/127128### Summary129130The service layer follows a reasonable structure but has some coupling issues...131132### Strengths133134- Clear separation between API handlers and business logic135- Good use of dependency injection136137### Concerns1381391. **High Priority**: UserService has 15 methods (God Class)1402. **Medium Priority**: Circular dependency between OrderService and InventoryService1413. **Low Priority**: Some magic numbers in validation logic142143### Recommendations1441451. Split UserService into UserAuthService and UserProfileService1462. Introduce EventBus to decouple Order and Inventory1473. Extract validation constants to configuration148```149150</usage_example>151</examples>152153## Iron Laws1541551. **ALWAYS review architecture before COMPLEX or EPIC implementation starts** — architectural problems discovered after implementation cost 10-100x more to fix; review in the design phase.1562. **NEVER approve an architecture with undocumented single points of failure** — every SPOF must be explicitly identified and have a documented mitigation plan.1573. **ALWAYS evaluate against non-functional requirements** — performance, security, scalability, maintainability, and observability are non-optional; functional correctness without NFR compliance is incomplete.1584. **NEVER treat architectural trade-offs as implicit** — every trade-off must be explicitly documented with rationale; hidden trade-offs become future surprises and unowned technical debt.1595. **ALWAYS check for circular dependencies before approving a design** — circular module dependencies make testing, refactoring, and deployment order unpredictable and progressively harder to resolve.160161## Anti-Patterns162163| Anti-Pattern | Why It Fails | Correct Approach |164| ----------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |165| No NFR evaluation | Design may pass functional tests but fail at scale or under attack | Always evaluate performance, security, scalability, observability |166| Reviewing only the happy path | Systems fail at error boundaries, not in the happy path | Review failure modes, retry behavior, and circuit breakers |167| Approving without trade-off documentation | Hidden trade-offs become future surprises | Explicitly document all trade-offs with rationale |168| Single point of failure left undocumented | System has silent fragility that surfaces under load | Map all SPOFs; require mitigation plans for each |169| Checking SOLID without anti-pattern catalog | Principle adherence doesn't guarantee absence of anti-patterns | Check both principles AND concrete anti-patterns (God Class, Shotgun Surgery, etc.) |170| Architecture review after implementation starts | Too late to fix structural issues without major rework | Review in design phase, before any code is written |171172## Rules173174- Always provide constructive feedback with actionable recommendations175- Prioritize issues by impact and effort to fix176- Consider existing constraints and trade-offs177178## Related Workflow179180This skill has a corresponding workflow for complex multi-agent scenarios:181182- **Workflow**: `.claude/workflows/architecture-review-skill-workflow.md`183- **When to use workflow**: For comprehensive audits or multi-phase analysis requiring coordination between multiple agents (developer, architect, security-architect, code-reviewer)184- **When to use skill directly**: For quick reviews or single-agent execution185186## Memory Protocol (MANDATORY)187188**Before starting:**189190```bash191cat .claude/context/memory/learnings.md192```193194**After completing:**195196- New pattern -> `.claude/context/memory/learnings.md`197- Issue found -> `.claude/context/memory/issues.md`198- Decision made -> `.claude/context/memory/decisions.md`199200> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.