Software Architecture and Technical Debt

Technical debt is more like cancer than a heart attack. Using AI tools poorly in your codebase won’t kill your product immediately. It will degrade over time...

Share
Software Architecture and Technical Debt
Photo by Martin Flottrong / Unsplash

There’s something that’s been bothering me for a while now, and considering all the recent outages of online services and infrastructure, I think it’s time to talk about technical debt.

The term originated with Ward Cunningham, a gifted software architect and author who invented it to explain to his boss the need to slow down occasionally and refactor code bases to pay down the debt that naturally accrues in software development.

But I’m already throwing developer terms in there. Let’s switch gears and talk about refactoring. Refactoring is the process by which you change code without changing the behavior. Here’s an example. Let’s say you have a surge strip with a lot of items plugged into it. I’m sure that sometime in your life you’ve seen a “rat’s nest” of cables, tangled and disorganized. If you were to unplug those cables, lay them out nicely, maybe use some twist-ties or tape to hold them in a nice position, then plug them back in, the items would still have power. It would also be much easier to work with those cables in the future, whether to replace a faulty cable, unplug or replace a device experiencing issues, or add new devices.

Doing this well takes time and planning. In the world of business and development, sometimes you don’t have that time for various reasons: external pressure from management, budget/runway, or sometimes you’re simply exploring new features and need to get something in front of a customer for feedback, so you don’t actually know up front what the shape of the code should be.

All these are valid reasons to “move fast and break things” as Silicon Valley types like to say, and there is always some amount of tension between IT and the business about this. Even when the code is “clean”, meaning it’s not in need of refactoring, the only constant in a long-running system is change, and with enough change you will sometimes have to take shortcuts or discover better ways to do things, both of which incur debt.

The reason that Cunningham refers to it as debt is because it accrues. The longer you defer refactoring, the harder it is to change. Consider the tangle of wires at the top of this post. If it’s just a few wires tangled up, it’s still a mess, but it’s manageable. When you get dozens or hundreds of wires tangled up, the amount of effort to fix them is exponentially more difficult.

I often tell my mentees that one of the best measures of software system quality is how easy it is to make changes.

So I’m not saying that you should avoid all debt up-front; that is impossible. If your app goes down one day, disrupting customers, and you need to slap a patch in there to get it up and running, you don’t really care about technical debt because servicing your customers is more important at that point in time.

The problem is when you let it go. “We’ll clean that up next sprint.” you say. But you never do. You have created debt, and as you layer on more debt, problems show up.

Non-Technical Symptoms of Debt

Before I get into code examples, let’s talk about the symptoms of technical debt that regular users and managers experience. Here are some of the most common:

  • Unrelated things breaking: Your team adds feature “Y” and something in feature “X” breaks. You feel like every time you push a release, you’re playing “whack-a-mole” with issues cropping up in other parts of the system.
  • Estimation inflation: You ask for a small or simple change, and the answer you get back is that it’ll take weeks or months.
  • Onboarding Slowdowns: Getting new team members into the codebase and productive takes months.
  • Fear: There are areas of the codebase that your development team is reluctant to touch.

Technical Symptoms of Debt

If you have some experience writing code, here are some things I notice as an architect:

  • Duplication: When you have duplicate functions and lines of code, that means that any change has to find every occurrence and fix them simultaneously. “DRY” (don’t repeat yourself) means only having to change one place and having that flow through the system.
  • Dead Code: Commented out code blocks, functions that are still alive but no longer used, feature flags that were abandoned years ago. These things create clutter in your code base. And with AI tools, those are extra tokens you’re paying for.
  • Leaky Abstractions: Calling functions requires understanding their internals to use them correctly.
  • Tight Coupling: Swapping out some behavior requires rewriting everything around it.
  • “God” Objects: Huge code files that have many unrelated functions in them. Good code is focused code, leaning towards SRP (single responsibility principle).
  • Inconsistency & Bloat: This is more of a style/pattern issue. When I open a code file, I shouldn’t know which team member wrote it, because the style should be consistent across the code base. This also includes packages you don’t need or use, and duplicate effort such as multiple logging frameworks or multiple styles of error handling.

AI Tools Accelerate Technical Debt

Yes, AI can write some code. I don’t think anyone serious is disputing that today. And while that’s useful and can accelerate implementing code, what I am noticing from an architect’s perspective is that in unskilled hands, AI accelerates technical debt.

It gives me a mild panic attack when I see professional developers bragging about how they don’t even read the code anymore. Because I do and let me tell you what I find.

The big one is duplication. The context window limits LLMs. Coding agents work by searching the codebase for places where they need to make changes. For small, new applications, this goes really well, but as the codebase grows, you start to hit those context window limits and now suddenly the AI tool “forgets” or “isn’t aware” of that function it wrote previously, so it just adds another. Eventually, you run into an issue where you need to change that behavior, and the AI can’t find all the places where it made the change, often because it not only duplicated the code, but it named and structured it differently.

And again, the larger the codebase and the broader the AI search is, the more you’re going to pay in tokens.

Another issue is shallow tests. AI tools often write trivial tests that look good on report metrics but don’t actually test the behavior that matters. Focusing on code coverage as a metric already did this with humans, but now the lies are automatically generated. AI tools also flat out skip tests if you don’t explicitly ask for them. And how do you know to ask for them? By knowing how to code!

Complexity is another issue. AI tools produce code based on patterns in the training data. Some of this code is easy to read. Some of it isn’t. In my career, I would shape the complexity of the code to the team I was working with. A weaker team needs simpler, easier-to-read code, even if it’s less efficient. Validating code that is difficult to read is both error-prone and time-consuming. With AI, the bottleneck has moved from code generation to review, and that’s not going particularly well.

Notice that I’m not saying AI can’t be used as a code assistant. What I’m saying is that the limitations of the technology lead to technical debt if a skilled human isn’t driving.

Technical Debt, Not Technical Death

This is where things get insidious. Technical debt is more like cancer than a heart attack. Using AI tools poorly in your codebase won’t kill your product immediately. It will degrade over time, progressing from stage 0 to stage 4. And, just like in humans, it’s best dealt with early on. When technical debt progresses too far, you end up in a situation where you think about whether fixing or scrapping and starting over is the better approach.

And this is something I’ve been talking about with my peers (and my wife, who isn’t a coder but listens to me anyway). The glee with which the executives running things have tossed out senior professionals and rammed AI tools into every process to save a buck was always going to end up in accelerating technical debt.

And here, in November 2026, we are. Longer, more frequent outages than we’ve had previously. Malicious AI agents exploiting aging and neglected infrastructure. Skilled open source developers experiencing burnout. And worst of all, lowered investment in the next generation of developers, who aren’t getting as many job opportunities and are often using AI to short-circuit learning, making them fundamentally incapable of cleaning up the mess that’s being created.

The Job is Changing

I’m not in the “turn it off” camp. AI tools are genuinely useful in the right hands, with the right guidance, and the right discipline and review. But a capable human brain needs to be controlling the harness.

I’ve had in uptick in working with educators and training programs lately: the days of “learn to write a React app and get a job” are gone. They aren’t coming back. The modern developer must be able to read and write code because they must validate it, but they also need to understand more about systems engineering, infrastructure, and validation, or they are simply not capable of responsibly using coding agents.

To tame the technical debt these tools produce, software teams need discipline, and everyone needs a dash of software architecture. This means:

  • Owning the boundaries: Humans must define (and verify) the boundaries, contracts, and invariants before code generation. Unsupervised and unconstrained generation creates a mess of debt.
  • Invert the test relationship: Some parts of applications are riskier than others. For example, code that touches a customer’s money requires much more rigorous human intervention than setting the color of a button on a form. In fact, I advocate that humans should design and implement that critical workflow testing.
  • Cap the merge rate: Producing code faster than it can be validated leads to burnout and shortcuts. It will bite your team, eventually.
  • Keep a ledger: If you do “vibe code” parts of the application, document those decisions and isolate that code from other parts of the application. As incidents rise, you can usually identify the culprits in that area.
I’m working with people on reimagining software developer training right now. More details on that in the future. Stay tuned.

For Now, I’m Still Waiting

I like the cancer metaphor because that’s what I’ve expected to happen since AI coding agents hit the scene. The degradations in quality and outages put us somewhere around stage 2. There will eventually be some critical outages that are difficult or impossible to recover from without data loss and extreme disruption.

When that happens, losing trust will effectively be stage 4, and some businesses will be forced to rewrite their code base or fail (die).

Unfortunately, the hit to the bottom line is the only thing that will wake up the “leaders” who are pushing their teams down this path.