skills.rest
barrydobson
barrydobsonCOMMUNITY
Explore all skills by this author →
GitHub

Refactoring Safely

Enforce tests-first atomic refactoring changes across codebases with existing tests.

Updated Nov 27, 2025
Search Tags:#code quality#testing#refactoring#git workflow#bug prevention#clean code#software maintenance
One-click install
npx skills add https://github.com/barrydobson/dotfiles_extra --skill refactoring-safely
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Refactoring Safely
Source: https://github.com/barrydobson/dotfiles_extra/tree/main/packages/claude/dot-claude/skills/coding/refactoring-safely
Command: npx skills add https://github.com/barrydobson/dotfiles_extra --skill refactoring-safely

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents accidental introduction of bugs during code improvements by enforcing strict rules: tests first, one change at a time, and never mixing refactoring with bug fixes or new features. It ensures structural changes don't alter behavior, making refactoring a low-risk activity.

Core Features & Use Cases

  • Tests-First Mandate: Requires passing automated tests before any refactoring begins, guaranteeing behavior preservation.
  • Atomic Changes: Enforces making only one structural change (e.g., extract one method, rename one variable) per test-and-commit cycle.
  • Separation of Concerns: Strictly forbids combining refactoring (changing HOW) with bug fixes or feature additions (changing WHAT) in the same commit.
  • Use Case: When you find a bug while extracting a method from a large function, this skill guides you to git stash your refactoring, fix the bug in a separate commit with its own test, then git stash pop and continue refactoring.

Quick Start

I need to refactor a complex Python function. Guide me through the safe refactoring process, ensuring I have tests, make one change at a time, and know what to do if I discover a bug.

Frequently Asked Questions about Refactoring Safely

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor code safely without breaking existing functionality?▼

Safe refactoring requires three rules: ensure tests pass before you start, make one structural change at a time, and never mix refactoring with bug fixes or new features in the same commit. This preserves behavior while you improve code structure.

What should I do if I discover a bug while refactoring?▼

Stop refactoring immediately and stash your changes using git stash. Fix the bug in a separate commit with its own test, then resume refactoring by restoring your stashed work. This keeps bug fixes isolated from structural improvements.

Can I refactor and add new features in the same commit?▼

No. Refactoring changes HOW code works; features and bug fixes change WHAT it does. Mixing them makes it impossible to identify which change broke tests. Always separate concerns into distinct commits.

Do I need automated tests before refactoring my codebase?▼

Yes. Automated tests that pass before refactoring begins are mandatory. They guarantee your structural changes don't alter behavior, making refactoring a low-risk, verifiable activity across all languages.

What counts as one atomic change during refactoring?▼

One atomic change is a single structural improvement: extract one method, rename one variable, or consolidate one code block. Each change gets its own test-and-commit cycle to isolate its effect and catch regressions immediately.

Does this approach work for large architecture changes?▼

Yes. This skill covers architecture refactors, method extractions, and naming improvements across all languages. Break large changes into incremental steps—each passing tests—so regressions surface early.

Related Skills

Explore More Software Engineering Skills→
trevin-jtrevin-j
6

git-basics

Run tests, linters, and static analysis before committing with Conventional Commits.

Community
Intermediate
CANTAGESTUDIOCANTAGESTUDIO
3

refactor-test-safety-net

Identify missing tests and establish a minimal safety net before refactoring.

Community
Advanced
nguyenthienthanhnguyenthienthanh
24

refactor-expert

Generate analysis and implementation plans for safe, incremental code refactoring.

Community
Basic
windyskywindysky

moai-workflow-ddd

Automate domain-driven refactoring with the ANALYZE-PRESERVE-IMPROVE cycle.

Community
Advanced