Prompt template
A refactoring prompt built around behavior preservation.
This template replaces “clean up this code” with a bounded refactoring task. It names the behavior contract, affected scope, tests, and interfaces that must stay stable before an agent changes implementation structure.
Reviewed September 22, 2026 · Templates and examples use fictitious data.
When to use this refactoring prompt
Use it when the desired outcome is structural: extract responsibilities, reduce duplication, isolate a dependency, simplify branching, or make a component easier to test. If the task changes visible behavior, fixes a bug, or replaces an API, describe that as a separate implementation task.
A safe refactor needs a boundary and a behavioral anchor. Existing tests are useful evidence, but they are not automatically complete. Add characterization checks for behavior that matters and is not already covered.
Reusable template
Safe code refactoring prompt
# Refactor {{component}}
## Goal
Improve {{component}} in project {{project}} to {{refactoring_goal}}.
## Behavior contract
{{behavior_contract}}
## Scope and constraints
- Files or boundary in scope: {{scope}}
- Existing tests and validation: {{tests}}
- Interfaces, behavior, and dependencies that must not change: {{constraints}}
<instructions>
Inspect the current responsibilities and affected callers before changing code. Keep the refactor narrow and preserve the stated behavior contract. Do not combine unrelated bug fixes, public API changes, dependency upgrades, or formatting churn with the refactor.
If the available evidence cannot prove behavior preservation, stop and identify the missing characterization test or check. Prefer small, reviewable steps with a reversible validation point after each step.
</instructions>
<output_format>
1. Current responsibilities and coupling
2. Proposed refactoring steps
3. Behavior-preservation risks
4. Required characterization and regression tests
5. Implementation or patch, followed by validation results
</output_format>Define the contract before the change
{{refactoring_goal}}
The structural improvement: extract, separate, deduplicate, simplify, or isolate.
{{behavior_contract}}
Observable outputs, errors, side effects, events, accessibility, timing, or compatibility that must remain stable.
{{scope}}
The smallest useful set of files, components, or call paths the agent may change.
{{tests}}
Existing checks and the exact commands used to validate the current behavior.
Filled example: isolate session persistence
Component: Authentication middleware and its inline database queries.
Goal: Extract session persistence behind a repository interface.
Behavior contract: Preserve authorization decisions, public error codes, cookie renewal, and revoked-session behavior.
Scope: Middleware, new repository module, and related unit tests. No schema or dependency changes.
Validation: Authentication integration suite plus new characterization tests for expiration and revocation.
The agent can now evaluate callers, propose small steps, and stop if revocation behavior is not covered. It should not silently redesign authentication while extracting the persistence layer.
A reviewable refactoring sequence
- Map current responsibilities. Identify callers, side effects, and public contracts.
- Establish the behavioral anchor. Run existing checks and add missing characterization tests.
- Change one boundary. Keep each step small enough to review and reverse.
- Validate after every step. Compare behavior, not only types and compilation.
- Review the diff for scope drift. Move bug fixes and upgrades into separate changes.
What this prompt cannot guarantee
An agent cannot preserve behavior it cannot observe or infer. Hidden consumers, incomplete tests, runtime configuration, and undocumented side effects remain risks. State them explicitly and use integration or end-to-end checks where unit tests cannot prove the contract.