# Safe Refactoring

> Refactor code safely through behavior preservation, protective tests, incremental change sequencing, and risk-aware migration planning.

- **Type:** Skill
- **Install:** `agentstack add skill-caiaffa-claude-code-ultimate-engineering-system-safe-refactoring`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [caiaffa](https://agentstack.voostack.com/s/caiaffa)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [caiaffa](https://github.com/caiaffa)
- **Source:** https://github.com/caiaffa/claude-code-ultimate-engineering-system/tree/main/skills/safe-refactoring

## Install

```sh
agentstack add skill-caiaffa-claude-code-ultimate-engineering-system-safe-refactoring
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Mission
Improve code structure without silently changing system behavior or increasing delivery risk.

# When to use
- Cleaning up legacy code.
- Extracting modules or services.
- Reducing coupling.
- Introducing clearer abstractions.
- Reorganizing domain boundaries.

# Handoff
- **Receives from:** code-reviewer (identified tech debt) or backend-platform-engineer (planned improvement).
- **Hands off to:** test-strategy (protective tests), code-reviewer (review the refactor), release-commander (if affects production behavior).

# The safe refactoring method
```
1. CHARACTERIZE → Write tests that capture current behavior (before changing anything)
2. IDENTIFY → What exactly needs to change? What must stay the same?
3. PLAN → Break the refactor into small, independently-mergeable steps
4. EXECUTE → One step at a time. Each step: green tests → change → green tests
5. VALIDATE → Run full test suite. Check no behavioral regression.
6. DEPLOY → Ship incrementally. Monitor for unexpected changes.
```

# Refactor vs rewrite decision
| Choose refactor when | Choose rewrite when |
|---|---|
| Core behavior is correct, structure is bad | Core behavior is wrong |
| Tests exist or can be written | System is so tangled tests can't be written |
| Team needs to maintain it during refactor | Clean break is possible (new service, new module) |
| Incremental delivery is possible | All-or-nothing is the only realistic path |

**Default to refactor.** Rewrites are almost always more expensive than estimated.

# Common refactoring pitfalls
- Changing behavior accidentally while restructuring.
- Removing "unused" code that's actually called via reflection or config.
- Breaking error semantics (different exception types, different HTTP codes).
- Changing timing that affects distributed flows.
- Losing observability (spans, metrics, log lines removed).

# Red flags — stop and reassess if
- You can't write a characterization test for the current behavior.
- The refactor touches more than 3 modules simultaneously.
- The refactor requires coordinated changes across services.
- There's no way to deploy the refactor incrementally.
- You find yourself saying "while we're at it, let's also..."

# Output format
1. **Current problems** (what's wrong with the current structure)
2. **Preserved behavior** (what must not change)
3. **Refactor strategy** (numbered steps, each independently mergeable)
4. **Protective tests** (what to write before starting)
5. **Risk assessment** (what could go wrong, how to detect it)
6. **Migration plan** (if contracts or APIs change)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [caiaffa](https://github.com/caiaffa)
- **Source:** [caiaffa/claude-code-ultimate-engineering-system](https://github.com/caiaffa/claude-code-ultimate-engineering-system)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-caiaffa-claude-code-ultimate-engineering-system-safe-refactoring
- Seller: https://agentstack.voostack.com/s/caiaffa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.