# Legacy Module Characterization Test Planner

Public URL: https://amo.ng/prompts/legacy-module-characterization-test-planner

Summary: Guide Codex to inspect legacy code, map current behavior, and plan characterization tests before refactoring risky modules.

Use this for: Use this to make Codex protect existing behavior before touching a legacy module.

Category: Codex & Coding
Tool: Codex
Difficulty: Expert
Prompt type: testing

## Best Use Cases

1. Legacy Code Refactoring
2. Characterization Test Planning
3. Regression Test Design
4. Behavior Preservation
5. Risky Module Review
6. Refactor Safety Planning
7. Codebase Inspection
8. Verification Planning

## Prompt Body

You are a senior engineer specializing in safe legacy refactors, characterization testing, and regression risk reduction.

## Task
Inspect the target legacy module, map its current observable behavior, and design characterization tests that protect existing behavior before any refactor is attempted.

## Context Placeholders
Use the context below. If an important placeholder is missing, name it and make a conservative assumption before continuing.

- [Repository context]
- [Legacy module path]
- [Known behavior]
- [Risky dependencies]
- [Existing tests]
- [Bug history]
- [Refactor goal]
- [Test command]
- [Allowed files]
- [Out-of-scope areas]

## Important Constraints
- Inspect before editing.
- Do not refactor the module until the characterization test plan is clear.
- Do not invent behavior. Base conclusions on code, tests, routes, configuration, fixtures, database usage, logs, or caller behavior.
- Separate confirmed behavior from inferred behavior.
- Respect [Allowed files] and [Out-of-scope areas].
- Identify risky dependencies such as database writes, external APIs, queues, caches, time/date logic, payments, permissions, file storage, background jobs, or framework lifecycle hooks.
- Prefer the smallest useful test set that protects important behavior without freezing unnecessary implementation details.
- Explain what each proposed test protects and why it matters.
- If existing tests are weak, missing, or hard to run, recommend the safest way to add coverage.
- Include exact verification commands and explain what failure would mean.

## Step-by-Step Task Instructions

1. Read the target module and nearby context:
   - Direct callers
   - Public methods or entry points
   - Routes, controllers, jobs, commands, listeners, or services that use it
   - Existing tests
   - Configuration and environment assumptions
   - Data models, database tables, fixtures, factories, or seeders involved

2. Build a behavior inventory:
   - Inputs
   - Outputs
   - Side effects
   - Validation rules
   - Error handling
   - Edge cases
   - Permission or security assumptions
   - External dependencies
   - Known bugs or legacy quirks that may be intentional

3. Identify refactor risks:
   - Behaviors likely to break
   - Hidden coupling
   - Missing tests
   - Ambiguous requirements
   - Data or state assumptions
   - High-impact paths that require human review

4. Design a characterization test plan:
   - Start with the smallest set of high-value tests
   - Map every test to a protected behavior
   - Include setup data or fixtures needed
   - Identify whether each test should be unit, feature, integration, or snapshot-style
   - Avoid testing private implementation details unless there is no safer public behavior to test

5. Recommend a refactor safety sequence:
   - Add characterization tests first
   - Run baseline tests
   - Make the smallest refactor step
   - Run tests again
   - Repeat in small steps
   - Stop and review if behavior changes unexpectedly

6. Provide verification commands:
   - Existing test command
   - Targeted test command
   - Full test command if needed
   - Static analysis or lint command if available
   - Any manual verification needed

## Output Format

### Codebase Reading Plan
List the files, commands, and relationships to inspect before edits.

### Behavior Inventory
Use a table with these columns:
- Behavior
- Evidence
- Input or trigger
- Expected output
- Side effect
- Risk level
- Notes

### Risk Map
List the highest-risk dependencies, edge cases, and unclear behavior.

### Characterization Test Plan
Use a table with these columns:
- Test name
- Behavior protected
- Test type
- Setup needed
- Expected assertion
- Risk covered
- Priority

### Refactor Safety Sequence
Give a step-by-step sequence for adding tests and safely refactoring.

### Verification Commands
List exact commands to run and what each result means.

### Human Review Notes
List assumptions, missing inputs, risky areas, and decisions that need human confirmation.

## Verification
Before finalizing, check that:
- Tests protect current behavior before implementation edits.
- Every proposed test maps to an observed or clearly inferred behavior.
- Risky dependencies are identified.
- Allowed files and out-of-scope areas are respected.
- Verification commands are exact.
- Assumptions and missing inputs are clearly listed.

## Final Instruction to Begin
Begin now. If key context is missing, ask for it first. Otherwise, inspect the codebase first and produce the full characterization test plan in the requested markdown format before making any implementation edits.

## Variables to Replace

1. Repository context
2. Legacy module path
3. Known behavior
4. Risky dependencies
5. Existing tests
6. Bug history
7. Refactor goal
8. Test command
9. Allowed files
10. Out-of-scope areas

## How to Use

Paste this into Codex with the legacy module path, refactor goal, allowed files, out-of-scope areas, and test command. Ask Codex to inspect the codebase and return the characterization test plan before making implementation edits.

## Example Use Case

A team wants to refactor a fragile billing calculation class but needs Codex to first map current behavior, identify edge cases, and design characterization tests that protect legacy payment and discount logic.

## Tags

1. characterization-tests
2. legacy-code
3. codex
4. regression-testing
5. refactor-safety
6. test-planning
7. behavior-preservation
8. code-inspection
9. verification
10. software-engineering

## Dates

Published: 2026-07-02
Updated: 2026-07-02