Refactoring Safely

Refactor with tests first, one change at a time, never mix refactoring with bug fixes or new features

43 stars 26 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add obra/clank --skill Refactoring Safely
Manual install
git clone --depth 1 https://github.com/obra/clank.git /tmp/clank
mkdir -p ~/.claude/skills
cp -r /tmp/clank/skills/coding/refactoring-safely ~/.claude/skills/Refactoring-Safely

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Refactoring Safely

## Overview

Refactoring means changing code structure without changing behavior. Safe refactoring requires tests first, one change at a time, and NEVER mixing refactoring with bug fixes or features.

**Core principle:** Refactoring changes HOW code works internally. Bug fixes change WHAT code does. Never mix HOW and WHAT changes.

**Violating the letter of this rule is violating the spirit of safe refactoring.**

## When to Use

**Use before any refactoring:**
- Improving names
- Extracting methods/classes
- Reducing complexity
- Improving structure
- Code review feedback

**Critical moments:**
- When you discover a bug during refactoring
- When tempted to "add this feature while I'm here"
- When making multiple structural changes
- When refactoring without tests

## The Iron Laws of Safe Refactoring

```
LAW 1: TESTS BEFORE REFACTORING (NO EXCEPTIONS)
LAW 2: ONE CHANGE AT A TIME
LAW 3: NEVER MIX REFACTORING WITH BUG FIXES OR FEATURES
```

Violating any law makes refactoring unsafe.

## Law 1: Tests Before Refactoring

**Before refactoring ANY code, you MUST have passing tests.**

**No exceptions:**
- Don't refactor "and add tests after"
- Don't "manually verify" instead of automated tests
- Don't "trust that it works"
- Don't refactor untested code without adding tests first

**Process:**

1. **If tests exist and pass:** Proceed with refactoring
2. **If tests exist but fail:** Fix tests first, THEN refactor
Read the full skill on GitHub

Details

Skill name
Refactoring Safely
Repository
obra/clank
Path
skills/coding/refactoring-safely/SKILL.md
Repo updated
9 October 2025

FAQ

What does the Refactoring Safely skill do?

Refactor with tests first, one change at a time, never mix refactoring with bug fixes or new features

How do I install the Refactoring Safely skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add obra/clank --skill Refactoring Safely. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Refactoring Safely popular?

It lives in obra/clank, which has 43 GitHub stars and 26 forks.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.