refactoring
This refactoring skill provides a structured methodology for safely transforming code structure while preserving behavior through test-driven verification. Use it when improving code readability, reducing duplication, or preparing messy codebases for new features, but never while simultaneously adding functionality. The approach mandates establishing test coverage first, making micro-changes individually, running tests after each step, and maintaining strict separation of refactoring types across commits to ensure zero behavioral change.
git clone --depth 1 https://github.com/DevelopersGlobal/ai-agent-skills /tmp/refactoring && cp -r /tmp/refactoring/skills/refactoring ~/.claude/skills/refactoringSKILL.md
## Overview Refactoring changes the internal structure of code without changing its external behavior. The keyword is "without" — if behavior changes, it's not refactoring, it's modification. This skill enforces safe refactoring with tests as the safety net. ## When to Use - When code is hard to understand or extend - When duplication makes maintenance risky - Before adding a feature to a messy area of code - Never: "while also adding feature X" — refactor separately ## Process ### Step 1: Establish a Safety Net 1. Before touching a single line: ensure there are tests covering the code to be refactored. 2. If tests are missing: add characterization tests first. These capture current behavior, not desired behavior. 3. Run the tests. They should all pass. This is your baseline. **Verify:** Tests pass. They cover the code being refactored. ### Step 2: Refactor in Micro-Steps 4. Make the smallest meaningful change. 5. Run tests after EVERY change — not after 10 changes. 6. If tests break: revert immediately and take a smaller step. 7. Never batch multiple refactoring changes together. **Verify:** Tests pass after every individual change. ### Step 3: One Thing at a Time 8. Refactoring types cannot be mixed in one step: - Extract method → separate commit - Rename → separate commit - Move → separate commit 9. "Refactor and also fix this" is not refactoring — it's two PRs. **Verify:** This commit does exactly one type of refactoring. ### Step 4: Verify No Behavior Change 10. Run the full test suite. 11. If integration/E2E tests exist: run them too. 12. Compare external API responses before and after (if applicable). **Verify:** All tests pass. No observable behavior change. ## Common Rationalizations (and Rebuttals) | Excuse | Rebuttal | |--------|----------| | "I'll add tests after refactoring" | You can't verify a behavior-preserving refactor without tests before the refactor. | | "This change is obviously safe" | Obvious safety is how production incidents happen. Run the tests. | | "I'll just do a quick cleanup" | "Quick cleanup" that changes behavior is a bug, not a refactor. | ## Verification - [ ] Tests existed before any code was changed - [ ] Tests run after every individual change - [ ] Only one type of refactoring per commit - [ ] Full test suite passes at the end - [ ] No behavior change observable externally ## References - [test-driven-development skill](../test-driven-development/SKILL.md) - [simplicity-first skill](../simplicity-first/SKILL.md) - Martin Fowler, "Refactoring"
Validates, parses, and sanitizes AI-generated outputs before they reach end users or downstream systems. Structured output enforcement, schema validation, and fallback handling.
Design stable, versioned, self-documenting APIs. Easy to use correctly, hard to use incorrectly. Apply Hyrum's Law from day one.
Automated quality gates from commit to production. Every merge to main is potentially shippable. No manual steps in the deployment path.
Get layered, context-aware explanations of unfamiliar code. Understand what it does, why it was written that way, and how to work with it safely.
Structured code review focusing on correctness, security, and maintainability. Correctness before style. Every reviewer comment must be actionable.