A repeatable quarterly process for measuring codebase health using the VITAL Signs Framework. Covers velocity, incidents, test effectiveness, architecture, and legacy burden with real metrics and thresholds.
Last quarter, a VP asked me a question I couldn't answer: "Is our codebase healthy?" I had opinions. I had gut feelings. I didn't have data. That moment forced me to build a repeatable process for measuring codebase health, and the results surprised everyone on the leadership team.
Most engineering orgs treat codebase health like a vibe check. Someone senior says "the code is fine" or "the code is a mess," and everyone nods. That's not engineering. That's folklore. I'm going to walk you through the exact process I now run every quarter, complete with the metrics, tools, and thresholds that actually matter.
Here's the contrarian take: your codebase doesn't need to be "clean." It needs to be changeable. I've seen beautifully architected codebases where every feature takes 3 weeks to ship. I've seen messy codebases where the team delivers daily. The difference isn't code aesthetics. It's whether the codebase actively resists the changes your business needs.
A codebase health check measures changeability, not beauty. The codebase understanding guide helps establish the boundaries and main paths before measuring them. If you're optimizing for anything else, you're solving the wrong problem.
After running health checks across 9 codebases over two years, I've settled on 5 dimensions that predict whether a codebase will slow your team down. I call them VITAL signs.
Figure 1. Read the five VITAL dimensions together before selecting improvement work.
How fast can you safely make changes? DORA defines change lead time from commit to production and deployment frequency as deployments over time. The thresholds below are suggested review triggers for this framework:[1]
Lead time for changes: Time from first commit to production deploy. Healthy: under 24 hours. Concerning: over 1 week.
Deploy frequency: How often you ship to production. Healthy: daily or more. Concerning: monthly or less.
PR cycle time: Time from PR open to merge. Healthy: under 12 hours. Concerning: over 48 hours.
bash
# GNU/Linux date; sample up to 100 merged PRs from the last 90 dayssince=$(date -u -d "90 days ago" +%F)gh pr list --state merged --search "merged:>=$since" --limit 100 --json createdAt,mergedAt \ --jq '[.[] | ((.mergedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) / 3600] | if length == 0 then null else add / length end'
The GitHub CLI command uses a search filter and a result limit, so it describes a bounded sample. If your lead time is over a week, the codebase is fighting you. It doesn't matter how elegant the architecture looks on a whiteboard.[2]
Which parts of the codebase cause production incidents? This is the metric that gets executive attention. Use dependency mapping to investigate what those modules affect.
typescript
// Track change failure rate per moduleinterface ModuleIncidentData { module: string; deploysInPeriod: number; incidentsCaused: number; changeFailureRate: number;}// Real numbers from a health check I ran:const results: ModuleIncidentData[] = [ { module: "auth/", deploysInPeriod: 34, incidentsCaused: 8, changeFailureRate: 0.235 }, { module: "billing/", deploysInPeriod: 21, incidentsCaused: 6, changeFailureRate: 0.286 }, { module: "notifications/", deploysInPeriod: 45, incidentsCaused: 2, changeFailureRate: 0.044 },];
For a DORA change fail rate, count distinct deployments requiring intervention. The incident counts in the example must first be mapped to failed deployments, since several incidents may share one deployment. The proposed 15% and 25% thresholds are investigation triggers for this framework.
Notice I said effectiveness, not coverage. Coverage is a vanity metric. I've seen codebases with 90% coverage that break constantly because the tests were testing implementation details instead of behavior.
Mutation testing checks whether the test suite detects changes made to the code. Stryker’s score counts detected mutants against the eligible total; it excludes mutants that end in an error. Review it alongside other evidence:[3]
Defect escape rate: What percentage of bugs make it past your test suite into production?
Test-to-change ratio: When you change production code, how many test files need updating? If it's more than 1:1, your tests are coupled to implementation.
Mutation testing score: Tools like Stryker can tell you what percentage of intentionally introduced bugs your tests actually catch. Aim for above 60%.
bash
# Run mutation testing to measure true test effectivenessnpx stryker run --reporters clear-text# Look for the mutation score, not line coverage
Can a new engineer understand where to put things? I measure this by tracking how often PRs get "wrong location" feedback in code review. If more than 10% of PRs get this feedback, your architecture isn't communicating intent.
Other signals:
Circular dependencies: Use madge --extensions ts,tsx --ts-config tsconfig.json --circular src/ to detect them. Any circular dependency is a health issue.
God modules: Any module with more than 50 direct dependents is a bottleneck. It'll show up in merge conflicts and slow reviews.
Layering violations: Are your UI components importing from database modules? Map your intended layers and check for violations.
For a TypeScript project, configure Madge’s file extensions and path aliases before relying on its dependency graph. Review any skipped files as part of the result.[4]
How much of your codebase is effectively frozen because nobody understands it or dares to change it?
bash
# Find files that haven't been modified in over a year but are still importedgit log --all --diff-filter=M --since="1 year ago" --name-only --pretty=format: | \ sort -u > recently_modified.txt# Compare against files that are actually imported/used
In one health check, I found that 34% of the codebase hadn't been touched in 18 months but was still actively referenced. That's 34% of code that's effectively unmaintainable because nobody on the current team wrote it or understands it.
# Bash: list the latest recorded author for each tracked source filegit ls-files -z -- src/ | while IFS= read -r -d '' file; do author=$(git log -1 --format='%ae' -- "$file") printf '%s\t%s\n' "$author" "$file"done# Compare with the active team roster and verify current maintainers.
Git history records authorship. Join the file-level result with the active team roster and verify who can maintain each module before labelling an ownership gap.[5][6]
Figure 2. Investigate where delivery evidence and developer feedback identify the same problem.
The magic happens when you cross-reference automated data with survey results. In my last health check:
Automated metrics showed billing/ had a 28.6% change failure rate
Developer surveys showed billing/ scored 1.8 on "confident making changes"
Git analysis showed the original billing author left 14 months ago
That's not three separate problems. That's one problem with three symptoms: knowledge loss. The fix wasn't rewriting billing code. It was pairing sessions and documentation sprints.
Week 1, Day 4: Cross-reference data, build scorecard
Week 1, Day 5: Present to engineering leadership with 3 prioritized action items
Weeks 2-12: Execute on action items, track improvement
The key insight that took me too long to learn: don't try to fix everything. Pick the 3 items where automated metrics AND developer surveys agree there's a problem. Those are your highest-conviction bets.
After four quarters of running VITAL checks, the team I worked with went from a health score of 48 to 79. Lead time dropped from 6 days to 14 hours. Change failure rate went from 22% to 7%. But the number I'm most proud of is the developer survey: "I can confidently make changes to any part of the codebase" went from 2.1 to 3.8.
That's what a healthy codebase feels like. Not perfect code. Confident engineers.
Your codebase is talking to you through metrics, incident reports, and the frustration on your team's faces. A health check is just learning to listen systematically. Start this quarter. You'll wonder why you waited.
Frequently asked questions
Does an unchanged file mean the code is unhealthy?
A file’s age is a prompt for investigation. Check whether it is still used, has a capable maintainer and can be changed safely. The legacy-burden review becomes more useful when history is considered alongside tests, runtime use and developer knowledge.
How should we calculate change failure rate?
Count deployments requiring immediate intervention, such as a rollback or hotfix, and divide by all deployments in the same period. Deduplicate the failed deployments. Several incidents connected to one deployment should not count as several failed deployments.
Why use mutation testing as well as coverage?
Coverage shows which code ran during a test. Mutation testing changes the code and checks whether the tests detect those changes. It supplies another view of test effectiveness, which still needs to be interpreted with the tested behavior and the tool’s limits.
Are the VITAL thresholds industry benchmarks?
The article proposes operating thresholds for its own review framework. Compare them with your service’s baseline, release constraints and risk profile. Record how the score is calculated so that a later review can use the same definitions.
Most code quality dashboards fail because they track too many metrics and live outside the team's workflow. Here are exactly 7 metrics and a 3-week adoption plan that actually works.
A 3-tier succession planning framework for engineering orgs, with a 90-day sprint for accelerating candidates from potential to ready. Based on succession plans built at 4 companies.
The CTO's real job in product development isn't attending every meeting or making every technical call. It's connecting feasibility, viability, and capacity while letting EMs handle the day-to-day.
Four years of data from a fully remote engineering team across 4 time zones. Specific metrics on productivity, retention, and onboarding with the frameworks that actually worked.
Small frictions cost more than big blockers. 47 micro-frictions consume 96 minutes per engineer per day. Here's the TAX Return framework for finding and eliminating the developer productivity tax.
Compare cyclomatic and cognitive code complexity with change risk. Check corrected examples, understand each measure’s limits and target refactoring effort.