| name | codebase-refactor |
| description | Systematic codebase refactoring and reorganization following SOLID principles, strict naming conventions (with banned patterns), DRY consolidation, defensive programming, mirrored frontend/backend structure, async error handling, and a phased refactoring process with deliverables checklist. |
| user-invokable | true |
| args | [{"name":"target","description":"The project or codebase area to refactor (optional)","required":false}] |
Follow every principle below rigorously. Do not skip steps, do not guess—research, verify, and validate before making changes.
1. Guiding Principles
SOLID Principles
- SRP: Every module has exactly one reason to change.
- OCP: Open for extension, closed for modification.
- LSP: Subtypes substitutable without breaking behavior.
- ISP: No module forced to depend on methods it doesn't use.
- DIP: High-level logic depends on abstractions, not implementations.
Core Philosophies
- KISS: Simplest correct solution wins.
- YAGNI: Don't build for hypothetical futures.
- DRY: Single authoritative representation (but don't couple unrelated things).
- Separation of Concerns: Each layer addresses one concern.
- Composition Over Inheritance: Combine simple pieces over deep hierarchies.
- Principle of Least Surprise: Code behaves as the name suggests.
- Fail Fast, Fail Loud: Detect errors at earliest point, surface immediately.
Defensive Programming
- Validate at boundaries. Trust nothing from outside your system.
- Use type systems aggressively. Avoid
any, untyped signatures.
- Make illegal states unrepresentable (discriminated unions, enums).
- Prefer immutability. Mutate only with clear justification.
2. Naming & Nomenclature Standards
Banned Naming Patterns
| Banned Pattern | Why Harmful | What to Do Instead |
|---|
| EnhancedWidget / ImprovedWidget | Implies non-enhanced version exists | Name for what it does: WidgetWithValidation |
| NewUserService / OldUserService | "New" is only new today | UserService. Period. |
| BetterParser / FastParser | Subjective, unverifiable | Name the mechanism: StreamingParser |
| utils2.js / helpers_new.py | Versioned filenames signal fear | One file. One name. Delete the old one. |
| temp_, test_, my_, foo, bar | Non-descriptive placeholders | Name for what it does |
| data, info, item, thing, stuff | Semantically empty | Name the domain concept |
| _backup, _copy, _orig, _fixed | Narrates changelog in the name | Strip the suffix. Git provides history. |
Positive Naming Principles
- Describe behavior, not history.
- Describe what, not how (public APIs). How, not what (private helpers).
- Use domain language (ubiquitous language).
- Booleans read as true/false questions:
isAuthenticated, hasPermission.
- Collections are plural. Single items singular.
- Constants:
UPPER_SNAKE_CASE with meaningful names.
3. Directory Structure
project-root/
├── frontend/
├── backend/
├── shared/ # Types, constants, utilities shared between FE & BE
├── scripts/
├── docs/
│ ├── decisions/ # Architecture Decision Records
│ └── glossary.md # Domain term → code name mapping
├── .github/
├── docker/
└── README.md
4. Mirrored Naming
| Concept | Frontend Path | Backend Path |
|---|
| Auth | frontend/src/features/auth/ | backend/src/features/auth/ |
| API client / route | frontend/src/api/users.ts | backend/src/routes/users.py |
| Types / Schemas | frontend/src/types/user.ts | backend/src/schemas/user.py |
Same domain noun across both sides. Group by feature, not by technical role.
5. Eliminating Code Duplication
- Identify — Flag every duplicated function, component, type.
- Consolidate — Extract to single module in appropriate location.
- Re-export — Update all consumers.
- Validate — Confirm no orphaned copies remain.
6. Modularity & Extensibility
- No function exceeds ~50 lines. No file exceeds ~300 lines.
- Frontend: separate presentational from container components.
- Backend: Routes → Services → Repositories layered architecture.
- Every public function has documentation.
7. Async & Error Handling
- Never use bare try/catch that swallows errors silently.
- Never use
catch (e) {}.
- All Promises must be handled.
- Timeouts mandatory on all external calls.
- Structured logging with timestamp, operation, correlation ID, stack trace.
- Prefer
Result<T, E> for expected failures; exceptions for unexpected.
8. Commenting Standards
- Section headers with clear comment blocks.
- Comments explain why, not what.
- TODO/FIXME tags with name and date.
- Architecture Decision Records for significant choices.
9. Refactoring Process
- Audit — Map current structure, identify violations.
- Test baseline — Ensure existing tests pass.
- Establish glossary — Create
docs/glossary.md.
- Restructure directories — Move files, update imports, verify.
- Rename for consistency — Eliminate banned patterns.
- Extract shared code — Consolidate duplicates.
- Refactor internals — Apply modularity patterns.
- Add documentation — Fill in docstrings, ADRs.
- Final validation — Full test suite, lint, type check, smoke test.
10. Deliverables Checklist
