Skip to content
Hidden Logic Lab

Gate a risky refactor with a characterization-test skill

Claude Code writes a SKILL.md that locks behavior with characterization tests before an agent refactors production paths.

Claude Code, Cursor
·Coding·40 min·Deep

A skill that demands tests-first, a green baseline commit, and a stop rule if behavior snapshots fail mid-refactor.

  1. 1

    Name the behavior you are protecting

    List user-visible outcomes and error messages before anyone writes tests. Vague goals produce vague snapshots.

  2. 2

    Land the baseline commit

    Merge characterization tests alone while behavior still matches production. Refactor only after that commit is green on CI.

  3. 3

    Invoke the skill on the refactor PR

    Point the agent at the skill path and the module scope. Reject diffs that edit tests and production in one commit without explanation.

The prompt to paste

Write a characterization-test skill (SKILL.md) for this refactor. The agent must not change production behavior without tests that describe what we ship today.

Refactor target:
[module or service, why we are touching it, what must not change for users]

Test stack:
[language, test runner, where tests live, command to run one file]

SKILL.md must include:
1. Purpose: capture current behavior before structural edits.
2. When to use / when not to use (include "stop if no test command works").
3. Required inputs: diff scope, risk areas, and the characterization test file name to create or extend.
4. Steps in order:
   - Read the module and list observable behaviors (inputs → outputs, side effects, error shapes).
   - Add or extend characterization tests that fail if behavior changes; no mocking away the code under refactor unless already standard here.
   - Run tests and commit the green baseline before any refactor commit.
   - Refactor in small commits; re-run the same tests after each commit.
   - If a test fails, revert or fix behavior — do not delete the test to green CI.
5. Two example prompts that invoke this skill correctly.
6. Pitfalls: testing implementation details, flaky timing, deleting tests under pressure, refactoring before baseline is committed.
7. Done means: checklist including "characterization tests merged" and "refactor PR shows no behavior change except listed exceptions."

Rules:
- Use our real test command placeholders; write [confirm command] if unknown.
- Do not disable lint or coverage gates in the skill.
- Output only SKILL.md markdown.

Characterization tests document today's quirks, including bugs you might fix on purpose. Mark intentional behavior changes in the PR, not by quietly rewriting tests.

Sample case written by Hidden Logic Lab. Not affiliated with Claude Code or Cursor.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.