Best of Technical Debt — March 2026

1. 1
   Article

   Addy Osmani·9w

   Comprehension Debt — the hidden cost of AI generated code.

   Comprehension debt describes the growing gap between how much code exists in a system and how much any human genuinely understands. As AI coding tools generate code faster than engineers can meaningfully review it, teams accumulate invisible risk: tests pass, velocity metrics look healthy, but no one can explain why design decisions were made or how parts of the system interact. An Anthropic study found engineers using AI assistance scored 17% lower on comprehension tests than those who didn't. Tests and detailed specs help but don't fully solve the problem—tests can't cover behavior no one thought to specify, and specs can't capture all implicit implementation decisions. The real scarce resource becomes engineers who deeply understand the system. Comprehension debt is more insidious than technical debt because it accumulates invisibly, nothing in standard measurement systems captures it, and the reckoning arrives at the worst possible moment. The solution is treating genuine understanding—not just passing tests—as a non-negotiable part of shipping software.

   142

   22
2. 2
   Article

   Code Like A Girl·10w

   Technical Debt

   Using a home renovation analogy of discovering a labyrinth of old pipes behind a wall, this piece explains technical debt as the accumulated cost of past shortcuts. It distinguishes between intentional debt (a conscious tradeoff) and a mess (careless neglect), drawing on Uncle Bob's Clean Code philosophy. The key insight is that debt is painless until you try to change something, at which point it compounds. The recommended mitigation is writing tests to create a safety net that makes future changes less risky.

   130

   6
3. 3
   Article

   Tech Lead Digest·10w

   The Rewrite That Was Really a Resignation Letter

   A senior backend engineer spent 18 months escalating structural problems in a routing engine through retrospectives, backlog tickets, and one-on-ones before writing a 22-page rewrite proposal. When leadership rejected it with a vague deferral and no alternative, he left. The post dissects this pattern: how systematic deprioritization of incremental fixes forces engineers toward dramatic proposals, why those proposals are often the wrong solution to a real problem, and what a substantive rejection should actually look like. It argues that 'no to the rewrite' without a committed alternative is indistinguishable from 'never,' and that the rejection gap is where trust and retention are lost. The story ends with the predicted cascading failure occurring six months after the engineer's departure, validating his diagnosis.

   34

   7
4. 4
   Article

   Manager.dev·9w

   The unwritten laws of software engineering

   Seven hard-learned unwritten rules of software engineering drawn from real incidents: always roll back before debugging when production breaks after a deploy; test your backup restores, not just their existence; logging is always imperfect but aim for balance; every DB change needs a tested rollback plan; external dependencies will fail so plan for it; use the four-eyes rule for any risky operation; and temporary fixes become permanent, so make them at least non-hacky.

   20

   3
5. 5
   Video

   Theo - t3․gg·11w

   Cursor, Claude Code and Codex all have a BIG problem

   A developer and early investor in Cursor argues that AI coding tools like Cursor, Claude Code, and Codex are plagued by poor UX and instability because they were built using early, weaker AI models—a form of premature 'vibe coding' that created low-quality codebases with compounding technical debt. The core thesis is that codebase quality peaks around the 6-month mark and only degrades after that, and bad patterns spread exponentially faster than good ones, especially when AI agents copy existing code. Practical advice includes: tolerate zero bad patterns, aggressively delete and rewrite bad code (now cheap with AI), keep unrelated features in separate repos, spend more time in planning mode with models, and use the latest models. A proposed future pattern is maintaining two parallel codebases—a 'slopfest' prototype version for rapid experimentation and a clean production version—similar to how Vampire Survivors maintains both a Phaser.js prototype and a C++ production build.

   19

   3