Lightweight Characterization — Claude Code Guide

An English lesson about Lightweight Characterization — Claude Code Guide in a controlled Claude Code workflow.

A characterization test is a snapshot of actual behavior

Lightweight characterization is a small test that records what code does now in a specific scenario before refactoring. It protects a narrow area from accidental change, but does not claim that the current behavior is business-correct.

This test complements unit, integration, and regression tests; it does not replace them.

When it fits	Why
One method or local flow	The area is easy to bound
A full integration test is too broad	A cheap safety net is needed
There are one or two key scenarios	It is enough to capture the main results
Existing coverage is limited	A baseline is needed before a structural change

Practice lab

Create a characterization safety net

Goal: Capture observable behavior before refactoring without replacing the actual contract with a preferred implementation.

Inputs

Current implementation
Key observable scenario
Test-run command

Steps

Choose one stable external scenario.
Record the actual output before the change.
Add a narrow characterization test.
Check the test on the current implementation.
Only after the green baseline plan the refactoring.

Expected output

A repeatable safety-net test
A record of the behavior boundary for the refactor

Verification

The test checks observable behavior rather than private structure.
The baseline is green before refactoring begins.

Stop if: the expectation is not confirmed by an actual run or the test captures an implementation detail.

Lab artifacts

PLAN.mdA reader-facing PLAN.md record that keeps ordered steps, risks, and a stop condition explicit for review.
REVIEW_NOTES.mdA reader-facing REVIEW_NOTES.md record that keeps findings, checks, questions, and a cautious verdict explicit for review.

Sources: level-20

Test observable behavior

response status;
error code or reason;
message;
external side effect;
another part of the public result.

Example for finalizeOrder

The test calls public finalizeOrder and checks the result. If a helper is renamed, combined, or removed during refactoring, the assertions should remain valid.

Scenario	Expected current result
Payment succeeds, item is in stock	Status FINALIZED and the corresponding message
Payment succeeds, stock is zero	Status REJECTED and reason OUT_OF_STOCK

Bounded characterization prompt

Target: finalizeOrder
Scenarios: one successful and one boundary case
Add only 1-2 behavior tests.
Do not change production code.
Capture current behavior; do not call it business-correct.

A lightweight characterization cycle

Describe in words the behavior to protect.
Add one or two narrow tests.
Run them against the current implementation.
Make one small structural change.
Run characterization and the main harness.
Check the diff and only then create a commit.

When characterization is insufficient

a large module with many integrations;
queues, a database, and numerous side effects;
a change spanning several packages;
an updated external contract;
business rules changing at the same time.

Canonical lesson source · JavaRush

Open JavaRush material