Refactoring Prompt

把「行为不得改变」变成可执行的约束：先建测试安全网，再指出具体问题，然后一次只做一小步可回退的改动。

把重构变成每一步都有通过/失败判定的有界操作。动手前必须跑通既有测试作为基线，并为未覆盖的关键行为补测试；必须指出具体问题而非模糊感受（若指不出就直说不需要重构）；计划中每一步只能是单一类型的改动——改名、抽取、内联、移动——且每步之后测试保持绿；结束时逐项证明公开接口未变。过程中发现的 bug 只记录不修复，避免藏进无人评审的大 diff。另附大文件、以及「让它更干净」这类无停止条件请求的变体，还有一份重构坏味道词表。

# Refactoring

**Use when:** you want code improved without behaviour changing.
**Pairs with:** [test_engineering.md](test_engineering.md), [senior_engineer.md](senior_engineer.md)

Refactoring means changing structure while keeping behaviour identical. Agents blur this. They "clean up" a file and quietly change what it does. This prompt makes that impossible to do by accident.

---

## The prompt

```text
This is a refactor. Behaviour must not change. Not the output, not the
error messages, not the order of side effects, not the performance
profile in any way a user would notice.

If you believe behaviour should change, stop and tell me. That is a
separate change and it does not go in this one.

STEP 1: BUILD THE SAFETY NET FIRST
Before changing anything:
- What tests cover this code today? Run them. Show the output. That is
  your baseline.
- What behaviour is not covered? List it.
- Write tests for the uncovered behaviour that matters, against the code
  as it is now. They must pass on the current code. Show that they pass.
If there are no tests and you cannot write any, say so and stop. A
refactor without a safety net is a rewrite with extra confidence.

STEP 2: SAY WHAT IS WRONG WITH IT NOW
Name the specific problem, not a feeling.
- What is hard to change here, and what change would be hard?
- What is easy to misuse, and how would someone misuse it?
- What is duplicated, and where exactly?
- What does a reader have to hold in their head at once?
If you cannot name a concrete problem, the code does not need refactoring.
Say that instead of finding something to do.

STEP 3: PLAN IN SMALL STEPS
Each step must:
- Be a single kind of change: rename, extract, inline, move, reorder,
  change signature. Not several at once.
- Leave the code working and the tests green.
- Be describable in one line.
Give me the ordered list before you start.

STEP 4: EXECUTE
One step at a time. After each step, run the tests and show the result.
If a test fails, you changed behaviour. Undo that step and rethink.
Do not batch steps to save time. The whole value is in the small steps.

STEP 5: PROVE BEHAVIOUR IS UNCHANGED
- All baseline tests pass, unchanged. Show it.
- If you changed a test, explain why. Changing a test during a refactor
  is a red flag and needs a reason.
- Walk the public surface: same names, same signatures, same return
  shapes, same errors, same side effects in the same order.
- Anything you could not verify: say so plainly.

DISCIPLINE
- No new features. No fixed bugs. If you find a bug, write it down and
  leave it. Fixing it hides it inside a refactor where nobody reviews it.
- No new dependencies.
- No renaming things outside the scope of the refactor just because you
  prefer other names.
- Fewer lines is not the goal. Clearer is the goal. If your version is
  shorter and harder to follow, it is worse.
- Do not add an abstraction for one caller. Wait for the third.

REPORT
- The concrete problem you fixed.
- The steps you took, one line each.
- Test output before and after.
- Any bug you found and deliberately did not fix.
```

---

## For a large messy file

```text
Do not refactor this whole file. Pick the one change that removes the
most confusion for the least risk. Do only that. Then stop and show me.

Before picking, list the three candidates and say what each would cost
and what it would buy. Choose the highest ratio, not the biggest job.
```

Large refactors from agents look impressive and are unreviewable. Forcing one change at a time keeps the diff readable.

---

## For "make this cleaner"

This request has no stop condition, so the agent will keep going until it has rewritten everything. Add one:

```text
"Cleaner" needs a definition. Before touching anything, tell me which of
these you are optimising for and why that one: fewer concepts to hold in
mind, easier to test, easier to change in a specific expected direction,
easier to read top to bottom, or smaller public surface.
Optimise for exactly one. Say what it costs.
```

---

## Refactor smells to name

Give the agent a vocabulary so it names real problems instead of vague ones.

- A function whose name needs "and" in it
- A parameter that changes what the function does rather than what it operates on
- The same three lines in four places, where all four must change together
- A conditional on a type, repeated in more than one place
- State that can be in an impossible combination
- A function you cannot test without setting up half the system
- A comment explaining what the next line does
- Nesting deeper than three levels
- A name that lies, which is worse than a name that is vague

---

## Why it works

The two lines that carry this prompt are "behaviour must not change" as an absolute, and "build the safety net before touching anything". Together they turn an open ended cleanup into a bounded operation with a pass or fail check after every step.

The instruction to leave found bugs alone is counterintuitive but correct. A bug fix buried in a 400 line refactor gets no review at all.