expert-code-refactoring

Refactoring Skill

This skill guides the agent in refactoring codebases by identifying technical debt and applying industry-standard patterns tailored to the specific technology stack.

General Refactoring Workflow

1. Analyze Context: Read the file and its associated tests. Identify dependencies and usage patterns.
2. Verify Tests: Before any changes, run existing tests to ensure a stable baseline.
3. Identify Smells: Look for long methods, deep nesting, duplicate code, or tight coupling.
4. Incremental Changes: Apply transformations in small, verifiable steps.
5. Re-verify: Run tests after each significant change.

Architecture & Clean Code (Global)

• Naming: Rename variables, functions, and classes to be descriptive and reveal intent. Avoid abbreviations.
• AHA Programming: Avoid Hasty Abstractions. Only abstract code when the duplication is clear and the abstraction doesn't make the code harder to follow.
• Functions: Keep functions small. Aim for a low number of parameters (prefer objects/records for many parameters).
• Cognitive Load: Reduce nesting levels (aim for max 2-3 deep). Use early returns to keep the "happy path" aligned to the left.

Refactoring for Testability

• Dependency Injection (DI): Replace hardcoded instances or static calls with injected dependencies (via constructor or parameters).
• Interface Segregation: If a class depends on a large interface but only uses one method, extract a smaller interface.
• Pure Functions: Extract business logic into pure functions that don't depend on external state or side effects, making them trivial to unit test.
• Mocking Boundaries: Identify "seams" where you can inject mocks (e.g., Database, Network, System Clock).

Legacy Code Techniques (Safe Changes)

• Characterization Tests: If tests are missing, write "Golden Master" tests that record the current behavior before changing it.
• Sprout Method: When adding a feature to a messy method, write the new logic in a new, clean method and call it from the old one.
• Wrap Method: Add new behavior by creating a new method with the same signature that calls the old method and then adds the new logic.
• Break Dependencies: Use the "Extract and Override" pattern to isolate untestable static calls or constructors in a protected method that can be overridden in a test subclass.