Code Refactoring Prompt Template — Structured Approach

Refactoring is the most dangerous AI coding task because it's behavior-preserving by definition — every change must produce the same outputs for the same inputs. When AI refactors code without explicit scope constraints, it frequently changes behavior while improving structure. It extracts a method and accidentally changes a side effect. It renames a variable and misses one reference. The sinc refactoring template's job is to encode behavior preservation as hard constraints so the model improves structure without touching semantics.

The Refactoring Sinc Prompt Template

This template targets a Python function that has grown to 150 lines and needs structural improvement — a common refactoring scenario with specific risk of accidental behavior change:

{
  "formula": "x(t) = Σ x(nT) · sinc((t - nT) / T)",
  "T": "specification-axis",
  "fragments": [
    {
      "n": 0,
      "t": "PERSONA",
      "x": "You are a refactoring specialist who operates under the discipline of behavior-preserving transformation. You change structure, never semantics. You add no new features. You remove no existing behaviors."
    },
    {
      "n": 1,
      "t": "CONTEXT",
      "x": "A 150-line Python function needs to be broken into smaller, testable units. The function handles Stripe webhook processing: signature verification, event routing, idempotency checking, and database writes. It's been working correctly for 2 years. The refactor goal is testability, not feature changes."
    },
    {
      "n": 2,
      "t": "DATA",
      "x": "[paste the 150-line function here]\n\nExisting tests: 12 integration tests in test_webhooks.py that all pass. These tests are the behavior contract — the refactored code must pass all 12 without modification to the test code."
    },
    {
      "n": 3,
      "t": "CONSTRAINTS",
      "x": "Do NOT change any external interface — function signature, return values, raised exceptions must be identical. Do NOT add new imports not already present. Do NOT fix any bugs you notice — document them as comments but do not change behavior. Do NOT rename any public function. Do NOT change error handling behavior. The refactored code must pass test_webhooks.py without modifying any test. Extract to private functions (underscore prefix) only."
    },
    {
      "n": 4,
      "t": "FORMAT",
      "x": "Refactored Python code only — no explanation prose. Add a single comment above each extracted private function explaining its invariant. Do not add any other comments. Show the complete refactored file."
    },
    {
      "n": 5,
      "t": "TASK",
      "x": "Refactor the function into smaller, testable units while preserving all existing behavior, interfaces, and test compatibility."
    }
  ]
}

The Behavior Contract Pattern

The most effective constraint in a refactoring prompt is a reference to existing tests: "The refactored code must pass test_webhooks.py without modifying any test." This gives the model a concrete, verifiable behavior contract. It's not just "preserve behavior" (abstract) — it's "pass these 12 specific tests without changing them" (concrete).

When existing tests don't exist, create the behavioral anchor another way: "The function must return the same result as the original for the same inputs." Then provide 2-3 example input/output pairs in DATA. The model will validate its refactoring against those pairs implicitly.

Raw Prompt vs. Sinc-Structured

The raw prompt produces cleaner code that silently changes two error handling behaviors and renames a public function that's called from 6 other files. The structured prompt produces a clean refactor that passes all 12 tests unchanged.

Try AI Transform — Structure Your Refactoring Prompt Free