What is technical debt? (the interest your shortcuts charge)

What it actually is

Technical debt is the future cost of the shortcuts you take today. Every time you (or your agent) pick the fast fix over the solid one, you borrow speed from your future self. The loan comes due with interest: the next feature takes longer to build, and the one after that longer still, because new code has to work around the mess the old shortcuts left behind.

Think of it as a credit card for your codebase. Charging a quick patch feels free in the moment. The feature ships, nothing visibly breaks. But the balance sits there, and the interest gets paid in time: an afternoon hunting a bug that a test would have caught in seconds, a “small” change that touches five files because the same logic got pasted into all of them.

The term covers more than sloppy code. A perfectly reasonable decision (“skip the tests, this is a demo”) becomes debt the moment the demo turns into a real product. The shortcut was fine. Keeping it past its expiration date is what costs you.

Why your AI just did this

Your agent may have said something like “this approach adds technical debt” or “we should refactor before adding more features.” It flags debt when it can see the pattern forming: a patch stacked on a patch, a third copy of the same validation logic, a utils.js that has grown past a thousand lines.

Vibe coding accrues debt unusually fast, and mostly out of sight. Each session, your agent starts with limited memory of past decisions, so it writes a new formatDate helper instead of finding the one it wrote last week. When you say “just make the error go away,” it obliges with a wrapper around the broken code rather than a fix. Dead code from abandoned directions stays in the repo because nobody deletes what nobody sees. And since you never asked for tests, there are none, which makes every change a small gamble. The app runs fine, so from the outside nothing looks wrong.

When you’ll run into it

There is no error string for debt. It shows up as friction. The feature that took your agent 20 minutes in week one takes a full afternoon in week five. You fix the login page and the settings page breaks, because both secretly share a pasted-around chunk of code. Your linter output fills with “defined but never used” warnings, a census of your dead code.

You will also feel it in the agent itself. Bloated files eat its reading budget: to change one function it wades through 1,200 lines of utils.js, then loses track of half your instructions. Many people hit this at the point where the app mostly works but every remaining change fights back, what we call the 70% wall. Debt is also a main ingredient of AI slop: duplicated helpers, needless abstraction layers, and leftover scaffolding are exactly what reviewers point at.

What to check

• Ask your agent for a debt inventory: “List duplicated logic, dead code, and any file over 300 lines in this project.” You can’t repay what you can’t see.
• Decide whether this project deserves repayment. A throwaway prototype can die in debt; that is what prototypes are for. Anything with users, or with your own future attention, should pay it down.
• Request tests before cleanup, in that order. A test that captures current behavior is your safety net, and refactoring without one is how “cleanup” becomes “outage.”
• Pay in small installments: one refactoring target per session (merge the duplicate helpers, delete one dead file, split one giant module), then confirm the app still works before the next.
• Mark new debt as you take it on. When you accept a shortcut, have the agent leave a TODO comment naming the proper fix, so future sessions can find the balance.

Say it like a dev

Instead of: “the app breaks every time we add something new” Say: “We’ve accumulated technical debt. Give me the three worst spots in this codebase and a small, safe refactor plan for each.”

Instead of: “just make it work for now” Say: “Take the shortcut for now, but leave a TODO comment describing the proper fix so we can pay this back later.”

Instead of: “clean up the code” Say: “Refactor only the duplicate date helpers in utils.js into one function. Write a test for the current behavior first, and run it after.”