Nobody wakes up one morning to find their codebase is unmaintainable. It happens gradually, like a frog in boiling water. I've watched it happen three times in my career, at three different companies, and the pattern is remarkably consistent. The codebase doesn't rot because of bad engineers. It rots because of rational decisions that compound into irrational outcomes.
The codebase understanding guide helps establish the system’s boundaries before examining the mechanisms that make changes difficult. Inspect dependencies, abstractions and knowledge ownership together.
# The Contrarian Take: Code Quality Isn't the Problem
Most discussions about unmaintainable codebases focus on code quality. Spaghetti code, missing tests, poor naming. Those are symptoms, not causes. I've seen codebases with excellent code quality become unmaintainable, and messy codebases that stayed productive for years.
Coupling becomes a maintenance problem when the team cannot trace how a change spreads. Use dependency mapping to inspect those connections and identify the boundaries that need attention.
For N modules, N*(N-1)/2 counts possible unordered pairs, not observed dependencies. That gives 45 pairs at 10 modules, 1,225 at 50 and 19,900 at 200. A directed graph can have N*(N-1) possible links. Actual coupling depends on which connections the architecture permits and the implementation uses.
Every new dependency is a rational decision in isolation. You need date formatting, so you add date-fns. You need HTTP calls, so you add axios. You need validation, so you add zod. Each decision takes 30 seconds and saves hours.[1][2]
But dependencies compound. I audited a codebase last year with 847 transitive dependencies. A single npm audit revealed 23 known vulnerabilities. Upgrading one library broke 3 others. The team spent 4 weeks just getting to a state where they could deploy safely.
bash
# Inventory installed dependency instances, excluding the project root.npm query ':not(:root)' > dependency-inventory.jsonnode <<'JS'const inventory = require("./dependency-inventory.json");const versions = new Map();for (const dependency of inventory) { if (!versions.has(dependency.name)) versions.set(dependency.name, new Set()); versions.get(dependency.name).add(dependency.version);}console.log("Installed package instances:", inventory.length);for (const [name, found] of versions) { if (found.size > 1) console.log(name, [...found].join(", "));}JS# Review findings and maintenance cost before judging the inventory size.
The tipping point: when dependency maintenance (upgrades, security patches, compatibility fixes) consumes more than 15% of engineering time, you've crossed into unmaintainable territory.
Teams build abstractions to manage complexity. A database access layer. A shared component library. An API client. These work great initially. Then edge cases arrive.
Each option was added for a good reason. But the abstraction no longer simplifies anything. It's just indirection with extra steps. I call this "abstraction erosion": when an abstraction accumulates so many special cases that understanding the abstraction is harder than understanding the raw implementation.
The indicator: When engineers start bypassing your abstractions and writing direct implementations because "it's easier than figuring out the options," your abstractions have eroded.
In every codebase I've audited, I find what I call "knowledge monopolies": critical modules that only 1-2 people understand.
bash
# Find knowledge monopolies: files with only 1 contributor in the last yearpython3 - <<'PY'from collections import defaultdictimport subprocessrevisions = subprocess.check_output([ "git", "rev-list", "--no-merges", "--since=1 year ago", "HEAD", "--", "src/"], text=True).splitlines()authors = defaultdict(set)for revision in revisions: author = subprocess.check_output([ "git", "show", "-s", "--format=%ae", revision ], text=True).strip() paths = subprocess.check_output([ "git", "diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", revision, "--", "src/" ]).split(b"\0") for path in paths: if path: authors[path.decode("utf-8", "surrogateescape")].add(author)print("Files with one recorded author:", sum(len(found) == 1 for found in authors.values()))PY
Git author records show recorded contributions. Review the result alongside the team’s knowledge and review history.[3]
On one team, I found that 42% of the codebase had exactly one person who'd touched it in the past year. When that person goes on vacation, gets sick, or leaves the company, those modules become black boxes.
Knowledge concentration can delay changes when the team relies on one person to explain a module. Review code ownership and the opportunities for other engineers to work in those areas.
Tests start as safety nets. Over time, they become ankle weights.
The progression looks like this: Tests are written close to the implementation. Implementation changes. Tests break. Engineers fix the tests (not because the behavior was wrong, but because the implementation shifted). After enough cycles, engineers dread changing code because they know they'll spend more time fixing tests than writing the feature.
I measured this on a team: the ratio of test code changes to production code changes was 3.2:1. For every line of production code changed, 3.2 lines of test code needed updating. That's not a safety net. That's a straitjacket.
typescript
// Brittle test: coupled to implementationtest("fetchUser calls database with correct query", async () => { const spy = jest.spyOn(db.users, "findUnique"); await fetchUser("123"); expect(spy).toHaveBeenCalledWith({ where: { id: "123" } });});// Resilient test: coupled to behaviortest("fetchUser returns user data for valid ID", async () => { const user = await fetchUser(knownUserId); expect(user?.id).toBe(knownUserId); expect(user?.email).toBeDefined();});
A lookup may return null when no record matches. Await asynchronous calls before making assertions about their completed work.[4][5]
This is the sneakiest mechanism. As a codebase grows, behavior gets externalized into configuration: feature flags, environment variables, config files, database-driven settings.[6]
I audited one system with 347 feature flags. Nobody knew which ones were still active. 40% of the flags controlled code paths that hadn't been exercised in production for over 6 months. But removing them was terrifying because nobody could trace their impact through the codebase.
Each flag doubles the number of possible states your system can be in. 347 flags means 2^347 theoretical states. The theoretical state space is finite but far too large to enumerate in a practical test suite.
Figure 2. Use the checklist to assign a concrete investigation.
Run this quarterly to catch unmaintainability before it catches you:
D - Dependencies: Run npm audit and npm outdated. Count transitive deps. If any dependency is more than 2 major versions behind, flag it.
E - Erosion: Review your top 10 most-used abstractions. If any function has more than 5 optional parameters or more than 3 return types, it's eroded.
C - Concentration: Run git analysis to find single-author modules. Schedule pairing sessions for anything critical with only one knowledgeable engineer.
A - Automation tax: Measure the test-to-production change ratio. If it's above 2:1 for any module, those tests need refactoring toward behavioral testing.
Y - YAGNI violations: Audit feature flags and configuration. Review flags that have not been toggled in 90 days. Remove obsolete release flags after checking consumers and rollout state, while retaining operational controls that still have a defined purpose.
The uncomfortable truth is that unmaintainability isn't a technical failure. It's a management failure. Every mechanism I described is detectable and preventable with the right measurements. The teams that keep their codebases maintainable aren't the ones with the best engineers. They're the ones that measure these indicators and act on them before the compound interest of decay makes action impossible.
Start the DECAY checklist this quarter. Your future self will thank you.
Frequently asked questions
Does a large dependency count prove a codebase is unhealthy?
A dependency count shows the inventory size. Assess it alongside security findings, duplicate versions, upgrade effort and actual maintenance cost. The article’s thresholds are review prompts for that assessment.
How can I find knowledge concentration in Git?
Count distinct recorded authors for each file within a stated time window, then inspect important single-author areas with the team. Commit authorship is a proxy for contribution and does not directly measure who understands the code.
How do I tell whether a test is brittle?
Inspect whether a harmless implementation change breaks a test whose expected behaviour is still valid. A test-to-production change ratio can identify an area to inspect, but it cannot establish the reason on its own.
Should every old feature flag be deleted?
Review a flag’s purpose, owner and remaining consumers before removing it. Release flags and long-lived operational controls have different lifecycles, so an old last-toggle date alone does not establish that a flag is obsolete.
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.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
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.