跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

legacy-code-change

Use when changing code with no trusted tests (characterize, cut the smallest seam, red then green). Trusted tests -> refactoring-catalog. New code -> tdd. Unknown cause -> diagnosing-bugs.

coding-agent · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rafaelob/pragmatic-agent-skills --skill legacy-code-change

技能说明


name: legacy-code-change description: "Use when changing code with no trusted tests (characterize, cut the smallest seam, red then green). Trusted tests -> refactoring-catalog. New code -> tdd. Unknown cause -> diagnosing-bugs." license: Apache-2.0 metadata: author: coding-agent version: 1.0.9 category: code-quality subcategory: quality-validation vendor: universal lifecycle: active coding_agent: true audience: developer output_format: markdown modality: text tags:

  • legacy
  • characterization-testing
  • seam
  • sprout
  • wrap
  • golden-master
  • approval-testing
  • refactoring
  • safety-net

Legacy Code Change

Legacy code is code without tests you trust. Cleaning it up first would refactor without a net, judging correctness against what you think it does: pin the behavior first, then change it.

Workflow

1. Characterize the observed behavior — quirks included

At the real seam, pin only the behavior being changed and what it can reach. Start with one deliberately wrong assertion and run it to reveal the observed value; then cover reachable branches, boundaries and error paths. Mark deliberate quirks, such as test_..._quirk_preserves_trailing_space, instead of normalizing them.

For wide output, use one golden-master/approval snapshot. Stop when the net covers the change and blast radius; do not characterize an entire module for a small fix.

2. Cut the smallest seam that lets the test run

Often there is nowhere to observe from: the logic is buried in a 400-line method that hits the database, the clock, and the network. Take the smallest change that creates a testable boundary — and make it behavior-preserving.

  • Sprout. Write the new behavior as a new function or class, fully tested on its own, and call it from one line in the old code. The legacy mess stays untouched; the new logic is born under test. Default choice.
  • Wrap. Rename the old method, create a new one with the original name that calls the old one, and put the new behavior in the wrapper. Use when the new behavior must run before/after the existing one on every call.
  • Break a dependency, minimally: extract an interface, parameterize a constructor, extract-and-override in a test subclass, inject the clock. Only as much as the test needs.

Seam changes are structural, never semantic: same behavior, new boundary. Land them separately from the change you actually came to make.

3. Write the new behavior test before changing anything

Write and run the failing test at the real seam, implement only enough to make it green, then rerun the original characterization loop.

If a pinned behavior conflicts with the intended result, decide explicitly whether it is a bug or a contract; never rewrite the pin silently. If no correct seam exists, record that architectural finding instead of substituting a shallow test.

4. Exercise real collaborators; Remove the temporary harness

Exercise the changed path against real collaborators at least once; a test-double-only boundary is unproven. Remove temporary harnesses, debugging, dead toggles and redundant characterization tests; keep tests that pin undecided behavior.

Size the seam and the new-behavior test to the change, not to the whole legacy module. Once its checks pass, remove the scaffolding and stop; widen coverage again only when a new change, a failure or an unresolved concern gives a reason, not as routine re-checking of what is already green.

5. Refactor green-to-green; keep the final diff clean

Refactor with refactoring-catalog for named moves, tests after each. Keep behavior-preserving structure changes separable from behavior changes; separate commits when they help a bisect or let a reviewer read the risky one alone.

Gotchas

  • Control nondeterminism (clock, randomness, ordering) before pinning behavior.
  • Do not fix unrelated bugs while characterizing.

Validation checklist

  • The changed behavior and reachable blast radius are characterized; quirks and nondeterminism are explicit.
  • The seam is structural and the new-behavior test was observed red before the fix.
  • Real collaborators were exercised, or the boundary is explicitly BLOCKED.
  • Temporary scaffolding is removed and intentional pins have reasons.

Cross-references

  • tdd: the red-green loop this borrows (there the behavior is new, here it exists). diagnosing-bugs: unknown cause, diagnose first. codebase-design: seam and module vocabulary. layered-testing-executor: which layers the change owes (decide from the project's own test layers, preferring the narrowest layer that proves the behavior).
  • Replacing the system instead of changing it is its own incremental migration (strangler-style cutover, parity checks), not a stretched version of this workflow.

Attribution

Practice vocabulary from Michael Feathers, Working Effectively with Legacy Code (2004) — characterization tests, seams, sprout and wrap. Approval/golden-master testing per Llewellyn Falco's approvals work.