Practical workflows
Legacy Codebase Refactor Workflow
Characterize existing behavior, create safety seams, and refactor legacy code in reversible slices without allowing AI to redesign undocumented contracts.
- Format
- Playbook
- Level
- Advanced
- Audience
- Developer, Operator
- Owner
- Project42 Editorial
- Review cadence
- Every 90 days
- Prerequisites
- Version-controlled source and a reproducible build or runtime; An owner for compatibility decisions; A recovery point and observable production or test signals
Characterize behavior and hidden contracts
Map entry points, callers, data shapes, side effects, external dependencies, configuration, permissions, concurrency, error handling, deployment, monitoring, and rollback. Use logs, tests, history, schemas, and representative fixtures to distinguish intended contracts from accidents that still have consumers.
Ask AI to produce a dependency and risk map with evidence references, not an immediate rewrite. Protect unfamiliar code until a characterization test or accountable decision defines what may change.
Create seams and move in reversible slices
Add deterministic characterization tests around stable boundaries, isolate volatile dependencies behind explicit interfaces, and choose one behavior-preserving slice. Keep data and API migrations backward compatible until every consumer and rollback path is verified.
Review AI edits for silent dependency, error, permission, performance, or observability changes. Deploy with a bounded canary or shadow path where justified, compare signals, and stop on declared thresholds.
Task: [ONE BEHAVIOR-PRESERVING REFACTOR OUTCOME]
Scope: [COMPONENT, CALLERS, DATA, DEPENDENCIES, AND ALLOWED PATHS]
Permissions: [SOURCE/LOG/DATA READ, WRITES, COMMANDS, NETWORK, AND DEPLOY LIMITS]
Current contract: [INPUTS, OUTPUTS, SIDE EFFECTS, ERRORS, PERFORMANCE, AND EVIDENCE]
Characterization: [REPRESENTATIVE, EDGE, FAILURE, AND COMPATIBILITY TESTS]
Slice and seam: [SMALLEST CHANGE -> EXPLICIT BOUNDARY]
Release gate: [TESTS, DIFF, SECURITY, PERFORMANCE, CANARY, AND OBSERVABILITY]
Stop conditions: [CONTRACT DRIFT, DATA RISK, UNEXPLAINED EDIT, OR THRESHOLD]
Verification: [OLD/NEW COMPARISON, CONSUMER TEST, POSTCONDITION, AND MONITORING]
Recovery: [ROUTE/ROLL BACK, REVERSE MIGRATION, RECONCILE STATE, AND RETEST]Expected result and verification
Expected evidence includes the system and dependency map, current-contract record, characterization suite, migration and compatibility plan, bounded diff, security and performance results, canary comparison, monitoring window, owner, and rehearsed rollback.
Stop when an undocumented consumer breaks, data cannot be reversed, permissions broaden, performance crosses its threshold, or the AI introduces unexplained behavior. Restore the verified route or version, reverse only rehearsed migrations, reconcile data and side effects, and preserve the new characterization case.