Legacy Codebase Audit Framework
A 5-step process for auditing a legacy codebase before deciding whether to refactor, rewrite, or retire.
steps
Gather the facts — no code yet
Interview: longest-tenured dev, last person to ship a major feature, someone who's had a recent incident. Ask: "What is the scariest part of this codebase?"
Map the blast radius
Identify 5 critical user flows. For each: trace end-to-end, identify all dependencies, note who is the only person who understands it.
Measure the health signals
Run: cyclomatic complexity, test coverage %, dependency age, DORA metrics. Look for clusters — they reveal systemic risk.
Classify the debt
(A) Blocks delivery, (B) Security/stability risk, (C) Slows onboarding, (D) Cosmetic. Only A and B need immediate action.
Write the recommendation
1-page doc: risk level (1–5), top 3 improvements, estimated effort, clear recommendation: Refactor / Targeted Rewrite / Full Rewrite / Retire.
Checklist
- Interviewed 3+ engineers
- Mapped 5 critical flows
- Identified bus-factor-1 areas
- Automated analysis run
- Debt classified by business impact
- 1-page recommendation written
- Recommendation reviewed with engineering lead
Prompts
Interview questions
Generate 10 interview questions for an engineer who has worked on a legacy codebase for 3+ years. Focus on undocumented assumptions, historical incidents, areas they avoid.
Translate metrics
Here are our cyclomatic complexity metrics. Identify the top 5 highest-risk areas and explain what the numbers mean in business terms, not engineering terms.