Codebase Understanding

How Large Codebases Become Unmaintainable

Vaibhav Verma

May 19, 2026

10 min read

codebase-healthmaintainabilitytechnical-debtarchitectureengineering-leadershipcode-quality

How Large Codebases Become Unmaintainable

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.

This post is about the specific mechanisms that turn a productive codebase into one where every change feels like defusing a bomb. More importantly, it's about recognizing these mechanisms early enough to intervene.

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.

The actual cause of unmaintainability is coupling growth that outpaces understanding growth. Your codebase becomes unmaintainable the moment the connections between components grow faster than your team's ability to understand those connections.

Let me show you the math. A codebase with N modules has a potential coupling surface of N*(N-1)/2. At 10 modules, that's 45 potential connections. At 50, it's 1,225. At 200, it's 19,900. Module count grows linearly with features. Coupling surface grows quadratically. Your team's understanding doesn't grow at all unless you actively invest in it.

The Five Mechanisms of Decay

Mechanism 1: Dependency Creep

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.

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

# Check your dependency depth
npm ls --all 2>/dev/null | wc -l
# If this number is above 1000, you have a dependency problem

# Check for duplicate packages (different versions of the same lib)
npm ls --all 2>/dev/null | awk -F@ '{print $1}' | sort | uniq -d | wc -l

The tipping point: when dependency maintenance (upgrades, security patches, compatibility fixes) consumes more than 15% of engineering time, you've crossed into unmaintainable territory.

Mechanism 2: Abstraction Erosion

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.

typescript

// Month 1: Clean abstraction
async function fetchUser(id: string): Promise&#x3C;User> {
  return db.users.findUnique({ where: { id } });
}

// Month 6: Edge cases arrive
async function fetchUser(
  id: string,
  options?: {
    includeDeleted?: boolean;
    includePendingVerification?: boolean;
    bypassCache?: boolean;
    withRelations?: ('posts' | 'comments' | 'payments')[];
    forAdminView?: boolean;
    asOf?: Date;  // time-travel query for audit
  }
): Promise&#x3C;User | DeletedUser | PendingUser | null> {
  // 87 lines of conditional logic
}

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.

Mechanism 3: Knowledge Concentration

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 year
git log --since="1 year ago" --format='%ae' --name-only -- src/ | \
  awk '/^$/{next} /@/{author=$0; next} {print author, $0}' | \
  sort -k2 | \
  awk '{files[$2][$1]=1} END {for(f in files) if(length(files[f])==1) print f}' 2>/dev/null | wc -l

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 isn't just a bus-factor risk. It makes the codebase unmaintainable for everyone except the knowledge holder. Features that touch those modules slow to a crawl because every change requires consulting the one person who understands it.

Mechanism 4: Test Brittleness

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 implementation
test("fetchUser calls database with correct query", () => {
  const spy = jest.spyOn(db.users, "findUnique");
  fetchUser("123");
  expect(spy).toHaveBeenCalledWith({ where: { id: "123" } });
});

// Resilient test: coupled to behavior
test("fetchUser returns user data for valid ID", async () => {
  const user = await fetchUser(knownUserId);
  expect(user.id).toBe(knownUserId);
  expect(user.email).toBeDefined();
});

Mechanism 5: The Configuration Explosion

This is the sneakiest mechanism. As a codebase grows, behavior gets externalized into configuration: feature flags, environment variables, config files, database-driven settings.

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 test matrix is literally infinite.

The Unmaintainability Score

I've built a scoring system to assess how close a codebase is to the unmaintainability cliff:

Indicator	Score 1 (Danger)	Score 2 (Warning)	Score 3 (Healthy)
Dependency count (transitive)	> 1000	500-1000	< 500
Abstraction bypass rate	> 20% of code bypasses abstractions	10-20%	< 10%
Knowledge monopoly %	> 40% single-author files	20-40%	< 20%
Test change ratio	> 3:1 test:prod changes	1.5-3:1	< 1.5:1
Active feature flags	> 100	30-100	< 30
Time for new engineer to ship	> 4 weeks	2-4 weeks	< 2 weeks

Scoring: Total of 6-9 means you're in the danger zone. 10-14 means you're accumulating risk. 15-18 means you're healthy.

The Stealable Framework: The DECAY Checklist

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. Delete anything that hasn't been toggled in 90 days. Remove dead code paths.

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.