Architecture Review
Analyze, audit, and improve project structure.
Key Principles
-
Measure before changing — Map structure and identify concrete issues before proposing changes
-
Clear boundaries — Layers (UI, logic, data) separated with consistent dependency direction
-
Colocation — Related code together; easy to find, change, and delete features
-
Incremental migration — Refactor in phases, validate each step with tests
Quick Assessment
-
No circular dependencies
-
Consistent directory naming and grouping (by feature or by type)
-
Single responsibility per file/module, reasonable file sizes (<500 lines)
-
External dependencies isolated, shared code properly extracted
-
New developers can navigate and find code for any feature easily
Quick Start Checklist
-
Map current structure: directory tree, dependency graph, module boundaries
-
Identify issues: circular deps, god modules, leaky abstractions, deep nesting
-
Classify severity: critical (blocks dev), high (maintenance burden), medium/low (friction)
-
Propose target structure with migration plan
-
Execute incrementally, validating with tests after each move
References
Reference Description
analysis-techniques.md Dependency graphs, complexity metrics, code analysis
refactoring-patterns.md Safe refactoring techniques, migration strategies
structural-patterns.md Directory structures for different project types
dependency-management.md Circular deps, coupling, module boundaries
cleanup-strategies.md Dead code removal, consolidation, naming conventions
anti-rationalization.md Iron Law, common rationalizations, red flag STOP list for architecture discipline