Architecture Review Instant

Perform a comprehensive architecture review of your codebase analyzing structure, dependencies, patterns, and anti-patterns with actionable improvement recommendations.

When to Use This Command

Run this command when...

• You have inherited a codebase and need a rapid assessment of its architectural quality before making changes
• A major feature or refactoring is planned and you want to identify structural risks and coupling issues upfront
• You want an objective third-party review of your project's architecture for a design document or technical debt assessment

Avoid this command when...

• You need a line-by-line code review for style and correctness (use a code review command instead)
• The project is a single-file script with no meaningful architecture to analyze

Quick Start

Copy
# No config file needed -- auto-detects project structure

Copy
claude -p "Review the architecture of this project and identify the top 5 improvement areas"

Expected output:
=== Architecture Review: myorg/myrepo ===

Project Type: Node.js/TypeScript monorepo
Frameworks: Express.js, React, Prisma ORM
Test Coverage: 67% (src/services: 42%, src/utils: 91%)

Architecture Score: B- (72/100)

Top 5 Improvement Areas:
1. [HIGH] Circular dependency: services/auth.ts <-> services/user.ts
2. [HIGH] God class: controllers/apiController.ts (847 lines, 23 methods)
3. [MEDIUM] Missing abstraction layer between controllers and database
4. [MEDIUM] 14 direct database calls in route handlers bypassing services
5. [LOW] Inconsistent error handling: 3 patterns used across 12 controllers

Dependency Graph: 4 clusters, 2 orphan modules, 1 cycle detected

Core Concepts

Concept	Description
Dependency Graph	Directed graph of module imports revealing coupling, cycles, and orphaned modules
Architecture Score	Composite metric (0-100) based on coupling, cohesion, complexity, and test coverage
Anti-Pattern Detection	Identifies god classes, circular dependencies, feature envy, and other structural smells
Layer Validation	Checks that architectural layers (controller, service, repository) are respected without bypasses
Complexity Hotspots	Files with highest cyclomatic complexity and change frequency, indicating maintenance risk

Controllers -----> Services -----> Repositories
     |                |                  |
     |     (bypass?)  |                  |
     +-------X------->|     Database     |
                       +---------------->+

X = Layer violation detected

Configuration

Parameter	Type	Default	Description	Example
depth	string	standard	Analysis depth: quick, standard, deep	deep
focus_areas	array	all	Specific areas to review	["dependencies", "layers"]
ignore_paths	array	["node_modules", "dist"]	Paths to exclude from analysis	["vendor", "generated"]
max_complexity	number	20	Cyclomatic complexity threshold for flagging	15
output_format	string	text	Output format for the review	json

Best Practices

1. Run before major refactoring efforts -- Understanding current architecture before changing it prevents introducing new anti-patterns while fixing old ones.
2. Track architecture score over time -- Export the score after each review and plot the trend. A declining score signals accumulating technical debt.
3. Focus on HIGH severity items first -- Circular dependencies and god classes have the highest blast radius; fixing them yields the most architectural improvement.
4. Share results with the team -- Architecture reviews are most valuable when the whole team understands the findings and agrees on improvement priorities.
5. Combine with test coverage data -- Low-coverage areas with high complexity are the riskiest parts of the codebase; prioritize them for both testing and refactoring.

Common Issues

1. Review takes too long on large monorepos -- Use depth: quick for an initial scan or ignore_paths to exclude generated code, vendor directories, and test fixtures.
2. False positive circular dependencies -- Type-only imports (TypeScript) may appear as cycles but have no runtime impact. The reviewer should distinguish runtime from type-only imports.
3. Architecture score seems too low -- The scoring weights coupling heavily. If your architecture intentionally has tight coupling (e.g., microkernel pattern), adjust the scoring weights or interpret the score in context.