About architecture-review
architecture-review is a skill for developers reviewing and improving project structure. It emphasizes measuring dependencies and boundaries first, then planning incremental refactoring validated with tests.
Key features
- 01Maps directory structure and dependencies
- 02Identifies circular dependencies and oversized modules
- 03Classifies architecture issues by severity
- 04Plans phased refactoring with test validation
- 05Provides structural and dependency references
Use cases
- 01Assessing an unfamiliar codebase
- 02Finding module boundary and dependency problems
- 03Planning a gradual restructuring
- 04Removing dead code and consolidating modules
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/architecture-reviewin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
references/analysis-techniques.mdanti-rationalization.mdcleanup-strategies.mddependency-management.mdrefactoring-patterns.mdstructural-patterns.mdDetails
From the project READMEArchitecture 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 |
Comments
Markdown supported