A Claude Code skill that enforces single-responsibility, LOC limits, and decomposition standards across your codebase. Keeps functions small, components focused, and files manageable.
- Enforces LOC thresholds across functions, components, and files
- Detects SRP violations using heuristics (name test, change test, reuse test)
- Framework-aware decomposition — understands React, Vue, Svelte, Angular, Node, Python, Go
- Generates
docs/architecture.md— a living map of how your codebase connects, updated on every run - Integrates with
/prepush-check— catches maintainability issues before code leaves your machine
| Scope | Green (Good) | Yellow (Watch) | Red (Refactor) |
|---|---|---|---|
| Function | < 20 LOC | 20–100 LOC | > 100 LOC |
| Component | < 200 LOC | 200–500 LOC | > 500–600 LOC |
| File | < 400 LOC | 400–1000 LOC | > 1000–2000 LOC |
Copy the SKILL.md file into your Claude Code skills directory:
mkdir -p ~/.claude/skills/maintainable
cp SKILL.md ~/.claude/skills/maintainable/SKILL.md/maintainable src/components/Dashboard.tsx
Analyzes the target, reports violations, suggests decomposition, and offers to refactor.
Automatically runs as part of /prepush-check on changed files. Red violations block the push, Yellow violations produce warnings.
| Mode | Scope | Behavior |
|---|---|---|
| Standalone | Whatever you point it at | Full analysis + refactor offer + architecture update |
| Prepush-check | Changed/new files only | Report violations, flag connections, update architecture |
On every run, the skill generates or updates docs/architecture.md in your project root. This file maps:
- Directory structure and purpose
- Module responsibilities (one line per component/function)
- Dependency graph between features
- Decomposition log (what was split and when)
This map is designed for both humans and AI agents to quickly understand how the codebase connects.
- Name test — Can't name it without "and"/"or"? It does too much.
- Change test — Would change for more than one reason? Multiple responsibilities.
- Reuse test — Need to copy-paste part of it? That part should be extracted.
- Test test — Mocking 3+ dependencies? Doing too much.
- Scroll test — Can't see it all on one screen? Consider splitting.
MIT