Technical Debt

A short document recording one significant technical decision, its context, and its consequences, kept alongside the code so later readers know why the system is shaped the way it is.

Bots that open pull requests whenever a dependency releases a new version, how they keep upgrades small and security patches fast, and how they turn into noise or a supply-chain risk when misconfigured.

Keeping new versions working with old code, data, and clients, the extreme lengths platforms go to preserve it, and the accumulated cost of never being allowed to change.

Adding people to a late software project makes it later, because onboarding and coordination costs outpace the new capacity.

Do not remove something whose purpose you cannot explain.

Prose inside source code, useful only when it records a constraint the code cannot state.

A team's shared checklist of what must be true before work counts as finished, such as reviewed, tested, documented, and deployed, which keeps hidden work from piling up behind items marked complete.

Marking something as superseded and scheduled for removal, without removing it yet.

Documentation that has drifted from the system it describes, and is now worse than none.

The measure of how many ways a system's parts can be arranged without changing how it looks, which always grows in total and gives time its direction.

A genre whose core verb is building the machine that plays the game, turning the player into a systems engineer.

A product accumulates features one reasonable addition at a time until the sum is bloated, slow, and hard to use.

A runtime switch that decouples shipping code from enabling behavior.

A recurring character reduced, across a long run, to a single exaggerated trait.

A complex system that works evolved from a simple system that worked; a complex system built from scratch never does.

A game operated as a running service rather than shipped as a finished artifact, with the consequences that shift implies.

A release line that receives security and bug fixes for years instead of months, letting users who value stability skip the constant upgrade treadmill.

The bias against adopting an outside solution simply because it wasn't built by your own team.

Outcomes shaped by the sequence of past choices rather than by present merit.

Spending effort making code fast before you know where it's actually slow trades clarity for speed you may not need.

The recorded origin of a change or a claim — who made it, when, and on what evidence.

Changing the structure of code without changing what it does, in small verified steps, so that the next change becomes easy.

Escalating past the visible symptom until you find the layer that actually produced it.

Divergence between a schema and the code, types, or documentation that describe it.

The tendency for a system's successor, freed of its predecessor's constraints, to become dangerously over-engineered.

Continuing an effort because of what has already been spent on it, rather than what remains to be gained.

A simpler, less correct design that ships and spreads beats a more correct one that doesn't, because adoption compounds.

A chain of prerequisite tasks that stands between you and the task you meant to do.