{"canonical_url":"https://engineer.company/glossary/technical-debt/","content_markdown":"# Technical debt\n\n## What it is\n\nTechnical debt is the future cost of a shortcut in the design or code of a\nsystem: a choice that saves time today and makes later changes slower, riskier\nor impossible until the shortcut is undone. Teams often shorten it to tech\ndebt. The word is a metaphor, and it was chosen because the shortcut behaves\nlike a loan. It buys something now, and it charges for it later, for as long\nas it stays in place.\n\nThe idea comes from Ward Cunningham's experience report at OOPSLA in 1992, on\nWyCash, a portfolio management system written in Smalltalk. A small team kept\ngeneral knowledge of roughly four megabytes of source, and the mature parts of\nthe program had been revised or rewritten many times. That\nconsolidation, the report argues, is what made steady incremental growth\npossible, and its absence is the serious pitfall: code that works and pleases\nthe customer, but has never been brought into shape. Cunningham put it in one\nline: \"Shipping first time code is like going into debt.\" The report itself\nspeaks only of debt and of its debt analogy. Later work uses the two-word\nname, and a 2015 paper from Google credits the metaphor to Ward Cunningham and\ndates it to 1992.\n\nResearchers who met at Dagstuhl in April 2016 to agree on what the term covers\nwrote a working definition. In it, debt is a set of design or implementation\nconstructs that save effort in the short run but leave the system in a shape\nthat makes later changes cost more, or puts some out of reach. They limit its\nimpact to qualities inside the system, above all how easy it is to maintain and\nto evolve. That separates debt from a feature nobody built: the cost of debt\nfalls on the people who change the system, and reaches users only through them.\nThe same report keeps the financial vocabulary. The principal is what the\nshortcut saved, or what a better solution would cost today. The interest comes\nin two kinds: recurring interest, paid as lower velocity, induced defects and\nlost quality, and accruing interest, the extra cost of every new piece of\nsoftware built on top of the code that is not quite right. Debt lives mostly in\ncode, and also in documentation, tests and known defects.\n\n## Why it matters\n\nDebt taken on deliberately can be a good decision. Cunningham's report says a\nsmall amount of it lets a team move faster, provided it is settled soon by\nrewriting the code, and the Google paper agrees that borrowing is often a sound\nstrategic choice. What both warn about is debt left in place. In the report,\nthe interest is paid in time, with each minute lost to code that is not quite\nright, and an implementation nobody consolidates can grow heavy enough to halt\nwhole engineering organisations. Before that point, the program becomes\nsomething no single person can master, which leads to programmers who each\nknow one corner and finally to a product that cannot change direction.\n\nThe trouble is that debt is often not chosen. The Dagstuhl report observes that\nit often arises without anyone meaning it to and takes developers by surprise,\nwhich is why it is mostly discovered during maintenance, long after the\ndecision that created it. Its causes are ordinary: schedule pressure, the\nabsence of a key person, or too little information about a technical feature at\nthe time. The Google paper adds that hidden debt is the dangerous kind, because\nit compounds silently.\n\nThe metaphor also gives developers and managers a shared language. The\nDagstuhl report calls it a strong communication mechanism, and the vision its\nparticipants set out includes managing debt as carefully as defects and new\nfeatures, with a way to translate between what developers worry about and\nwhat managers decide. A study presented at the seminar shows what that can\nmean in a team. Graziela Tonin, Alfredo Goldman and Carolyn Seaman asked\nstudent teams of 60 people in total to identify and track their debt\nexplicitly. A visible list let teams negotiate time with their customer for\nrefactoring, kept a record of which parts of the project were still immature,\nand showed whether code quality was improving. Most team members said they\ncommunicated more, thought harder about whether a debt was really needed and\nrefactored more often. Because decisions to take on debt were talked through,\nthe authors add, some teams ended up with fewer experts nobody else could\nstand in for.\n\n## What it looks like in practice\n\nDebt becomes manageable when it is written down where the team plans its work.\nAn entry in a register, written for this article, can be as short as this:\n\n```text\nTD-14       Invoice totals are calculated in three places\nArtifacts:  billing/web, billing/export, reports/monthly\nCause:      a fixed launch date; copying the rule was quicker than\n            moving it into a shared module\nPrincipal:  about 2 days to move the rule into one module, with tests\nInterest:   every tax-rule change is made and tested three times, and\n            one of the last five changes missed a copy\nNext:       repay with the next tax-rule change; the e-invoice export\n            planned this quarter must not become a fourth copy\nOwner:      billing team\n```\n\nThe fields follow the model from the Dagstuhl report: an item tied to\nconcrete artifacts, with a cause, a principal and interest. Writing the\ninterest down is what makes the entry useful, because it turns a feeling that\nthe billing code is messy into a cost someone can weigh. If tax rules change\nfour times a year and each change costs an extra day of work and testing, the\ntwo days of principal are repaid within six months. The planned export is\naccruing interest in the Dagstuhl sense: every new piece built on the\nduplicated rule raises the price of fixing it later. If, on the other hand, the\ncode were frozen and nobody expected to touch it again, the same entry would\njustify leaving the debt alone.\n\nDebt is not only a matter of code. This site's portfolio entry on\n[overhauled internal processes, saving 8,000 hours](/portfolio/overhauled-internal-processes-saving-8000-hours/)\nrecords the founder's earlier work at Mappitall. It asks whether technical debt\nis slowing the reader down, and describes the kind\nthat builds up around how the work runs: software architecture that had grown by\naccretion rather than design, systems that worked but not efficiently, and\nscheduling that left people either waiting or overloaded. None of it was on\nfire, which is why it had been left alone. Reworking the architecture, the\nsystems and the scheduling saved roughly 8,000 hours over the work carried out\nfrom 2015 to 2022, and the page credits part of that to making the changes stick\nin how the team operated, since improvements that are not made permanent decay\nback to the old way.\n\n## Where it goes wrong\n\n**Everything is called technical debt.** Once the phrase is popular, every\nannoyance gets the label, from an old library to a missing feature to a\ncolleague's style. The Dagstuhl report names this risk directly and asks for\ncrisp definitions in answer. Keep the term for shortcuts whose cost lands on\nfuture change, record defects as defects and wishes as features, and refuse a\nregister entry that cannot name its cause and its interest.\n\n**The debt exists only in people's heads.** Debt nobody wrote down is paid\nfor by whoever touches the code next, usually without knowing why the work\ntakes so long. Keep a register next to the backlog, and check it before\nchanging a part of the system, the way the student teams in the Tonin study\nused their list. An item becomes visible to the people who decide on time only\nwhen it is written where they look.\n\n**Principal is repaid where no interest is charged.** Cleaning up a module that\nnobody changes feels productive and returns nothing, while the code that\nchanges every week keeps charging. Interest only accrues where people work, so\nrank the register by how often each part changes and by what is about to be\nbuilt on it, and repay the expensive items first.\n\n**Repayment waits for one large rewrite.** Debt left for years tends to be\nanswered with a project to replace the whole system, which takes on new debt\nof its own while the old system keeps charging. Cunningham's advice was prompt\nrepayment, and the Google paper lists the usual ways to pay it down:\nrefactoring, stronger unit tests, removing dead code, fewer dependencies,\ntighter APIs and better documentation. None of these adds a feature; the\npoint is to make the next change cheaper. Schedule them as part of ordinary\nwork, close to the change that needs them.\n\n**Experiments stay in production.** Trying an alternative as a conditional\nbranch in the production code is cheap for each experiment, and the Google\npaper describes how such branches pile up until testing every combination\nbecomes difficult or impossible. It cites Knight Capital, whose system it\nsays lost $465 million in 45 minutes, apparently because obsolete experimental\ncode paths behaved unexpectedly. Re-examine each experimental branch and each\nflag on a schedule, delete what is no longer used, and reward deleting code as\nmuch as adding it.\n\n**A tool's score is taken for the debt.** Static analysis can count\nduplicated lines and long functions, and a dashboard makes the count look like\na balance. The Google paper is plain that the metaphor provides no strict\nmetric to track over time, and that a team still moving quickly is not\nevidence of low debt. At Dagstuhl, Forrest Shull reported that no single set of\nrules for detecting debt correlated consistently with its symptoms, such as\nrising change cost and falling velocity, across different projects. Check a\ntool's findings against your own history of changes and defects, keep the\nrules that predict cost, and drop the rest. The paper's own questions are a\nbetter test, among them how quickly a new member of the team can be\nbrought up to speed.\n\n## Further reading\n\n- [The WyCash Portfolio Management System](https://c2.com/doc/oopsla92.html) —\n  Ward Cunningham's OOPSLA '92 experience report, where the debt analogy first\n  appears.\n- [Managing Technical Debt in Software Engineering](https://drops.dagstuhl.de/entities/document/10.4230/DagRep.6.4.110)\n  — the report of Dagstuhl Seminar 16162, with the working definition, principal\n  and interest, and the study of explicit debt lists.\n- [Hidden Technical Debt in Machine Learning Systems](https://proceedings.neurips.cc/paper_files/paper/2015/hash/86df7dcfd896fcaf2674f757a2463eba-Abstract.html)\n  — the 2015 paper by Sculley and colleagues at Google on how debt builds up,\n  how to pay it down, and why it resists measurement.\n- [Refactoring](https://refactoring.com/) — Martin Fowler's site on the small,\n  behaviour-preserving changes that the Google paper lists first among the\n  ways to pay debt down.\n\n\u003chttps://engineer.company/glossary/technical-debt/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Where technical debt comes from, how its principal and interest are counted, how to keep a register of it, and why paying it down goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/technical-debt/index.gmi","gopher":"https://engineer.company/glossary/technical-debt/gophermap","html":"https://engineer.company/glossary/technical-debt/","json":"https://engineer.company/glossary/technical-debt/index.json","markdown":"https://engineer.company/glossary/technical-debt/index.md","pdf":"https://engineer.company/glossary/technical-debt/index.pdf"},"kind":"page","language":"en","title":"What is technical debt?","url":"https://engineer.company/glossary/technical-debt/","version":1}