The prompt
Score 10 of 10, Excellent
Use it when You need a coding agent to clean up code while tests keep passing and behavior stays the same.
- {{target_files}}
- {{problems}}
- {{public_interface}}
- {{pattern_files}}
- {{refactor_aim}}
- {{test_command}}
- {{coverage_notes}}
- {{off_limits}}
- {{max_files}}
Full prompt and why it works
Prompt
<refactor_target> Files or module: {{target_files}} What makes this code hard to work with today: {{problems}} </refactor_target> <public_interface> {{public_interface}} </public_interface> <pattern_to_follow> {{pattern_files}} </pattern_to_follow> Goal: Refactor the code in <refactor_target> so that {{refactor_aim}}, without changing what it does. Callers, tests and users should see exactly the same behavior before and after, so the change can be merged without a long manual re-test. Context: - Test command: {{test_command}} - How well tests cover this code today, as far as I know: {{coverage_notes}} - Off limits: {{off_limits}} Constraints: 1. Before editing, read the code and its tests and reply with a short plan: the steps in order, the files each touches, and anything risky. Wait for my go-ahead if it touches more than {{max_files}} files, so the change stays small enough to review. 2. Keep everything in <public_interface> unchanged, including signatures, return values, error types and messages, log output and the order of side effects, because code outside this module may depend on any of them. 3. Work in small steps and run the tests after each one, so that a failure points to a single step. 4. Do not change, skip or delete existing tests to make them pass, because a test that has to change means behavior changed. If one must change only because a private name moved, say so in your report. 5. Follow the structure and naming in <pattern_to_follow>, or the surrounding code if none is given. Do not add dependencies, fix unrelated bugs or reformat untouched code, so the diff is about one thing; note what you spot instead. 6. If test coverage of this code is thin, stop after the plan and propose characterization tests (tests that record what the code does today) to add first, because without them nothing proves behavior is unchanged. Done when: - {{test_command}} passes with the same tests as before, plus any characterization tests you added, and the linter and type check pass if the project has them. - The goal above is visibly met, for example a 300-line function is now a short sequence of named steps a reader can follow. Finish with a report in this format: the steps you took, files changed, the commands you ran with the last 20 lines of their output, and anything you noticed but deliberately left alone. If you find behavior that looks like a bug, keep it exactly as it is and list it, because fixing it is a separate change. If anything is unclear about what counts as behavior here, ask before changing it.
Variables
- {{target_files}}
- The files, folder or module to refactor, for example src/billing/invoice.ts.
- {{problems}}
- What makes it hard to work with, for example "one 300-line function" or "the same logic copied in three places".
- {{public_interface}}
- Functions, classes, endpoints or exports that other code depends on and that must keep working exactly as now.
- {{pattern_files}}
- An existing file or module structured the way you want this one to be. Write "none" if there is none.
- {{refactor_aim}}
- What the refactor should achieve, for example "each pricing rule lives in its own function with a name that says what it does".
- {{test_command}}
- The command that runs the tests, for example npm test or pytest.
- {{coverage_notes}}
- For example "good tests for the main path, none for errors" or "not sure".
- {{off_limits}}
- Files, folders or systems that must not change, for example migrations or generated code.
- {{max_files}}
- The number of files above which the agent must check with you first, for example 5.
Why it works
- What good looks like. Done means the same tests pass with none edited to fit, which is the only proof an agent can give that behavior did not change.
- What to avoid. Error messages, log output and the order of side effects count as behavior too, the details a refactor most often changes without anyone noticing.
- If unsure. Thin test coverage stops the work after the plan, so characterization tests come first and bugs are listed rather than quietly fixed.