technical debt

Bilingual

technical debt is different from technical risk
2 months ago
- The original definition of technical debt by Ward Cunningham refers to iterative design, not shortcuts or poor code.
- Common usage of 'technical debt' is misleading; it actually describes 'technical risk'—the risk of introducing bugs when modifying code.
- Technical risk increases over time as code becomes harder to change, unlike debt which can be repaid with time.
- All programs have some degree of technical risk, regardless of initial planning or code quality.
- Feature flags are often used to mitigate risk but can lead to combinatorial complexity and lock-in.
- Ongoing refactors and rebuilding systems can reduce risk, as seen in successful projects like the Rust compiler.
- New systems can adopt different paradigms (e.g., SQLite vs. OracleDB) to avoid stagnation.
Fix Like No One’s Watching — overreacted
2 months ago
- Some technical debt, such as inadequate data structures or sloppy code, is highly visible and causes bugs, performance issues, and feature difficulties.
- Another insidious technical debt involves slow test suites, untrusted deployment scripts, rigid abstractions, or rigid unit tests that subtly discourage improvements and innovations.
- These friction-causing issues often go unaddressed because they seem minor, yet reducing friction is crucial as it can determine a project's success or failure.
- The author urges to fix technical debt proactively, as if no one is watching, since its impact can be transformative.
Prompts are technical debt too
2 months ago
- Prompts are a form of technical debt that can silently degrade as models are updated.
- Carefully crafted prompts for one model may become obsolete or harmful with the next model release.
- Unlike code, prompt degradation often goes unnoticed because model capabilities are hard to measure.
- Most users should rely on maintained AI coding tools with minimal custom configuration to benefit from ongoing prompt tuning.
- When writing AGENTS.md files, avoid behavior steering and focus on concrete project facts; regularly review and delete unneeded prompts.
Why the Cleanup Sprint Always Loses
2 months ago
- Technical debt proposals get approved when framed as a price (e.g., cost in days or incidents), not as an adjective (e.g., 'the module is a mess'), because prices are comparable to roadmap priorities.
- Use a four-field template to describe debt: Construct (specific location), Interest (repeatable cost in tracked metrics), Principal (effort to fix), and Trigger (upcoming work increasing interest).
- Example: payment logic duplicated across three services costs 12 days per quarter in extra work and incidents, costs 3 weeks to fix, and a Q4 checkout redesign will increase interest.
- The template reveals that debt with no planned changes and zero interest can be intentionally accepted, ending pointless arguments.
- Three key habits: price interest in organizational metrics (e.g., lead time), attach principal to existing feature work instead of separate cleanup sprints, and let some debt stay based on interest vs. ugliness.
- Signs pricing is missing: unscheduled refactoring tickets, unexplained estimate growth, and all items marked critical in a debt register.
- AI-generated code increases debt because ununderstood code is debt even if clean, making visibility through pricing more critical.
The difference between "today's task" and "accretive work"
3 months ago
- Distinguishing between 'today's task' (getting something working) and 'accretive work' (creating reusable, maintainable code) resolves the paradox of AI's impact on programmers.
- AI can empower 'centaurs' (autonomous workers using AI) but often creates 'reverse centaurs' (workers forced to manage AI outputs), driven by capital's need to cut costs, leading to technical debt.
- The concept of 'canonization' highlights the social process of making code legible and reusable, contrasting with disposable 'vibe coding' for personal use.
- The AI industry's focus on generating code without contributing to reusable knowledge devalues cleanup and canonization, consuming the 'seed corn' of shared knowledge.
Most rewrites serve the engineer, not the business
3 months ago
- Rewrites often prioritize the engineer's preferences over business value, as shown by an example of porting a CakePHP application to Laravel without tangible benefits.
- Existing code holds historical knowledge and bug fixes; rewriting it risks reintroducing past issues and losing valuable 'scar tissue' documented by Joel Spolsky.
- Unfamiliarity with a codebase or framework can lead to misjudgments; assuming previous developers made reasoned choices is crucial before deeming code 'broken'.
- Legitimate reasons for rewrites include end-of-life runtimes, loss of key personnel, high feature development costs, or business needs that outgrow the current design.
- AI can accelerate code generation but may omit context for past fixes, leading to rediscovery of old bugs and perpetuating a cycle of rewrites without addressing root causes.
- To break the rewrite cycle, document the rationale behind code decisions clearly, ensuring future engineers or AI models understand the 'why' and not just the 'what'.

technical debt

technical debt is different from technical risk

Fix Like No One’s Watching — overreacted

Prompts are technical debt too

Why the Cleanup Sprint Always Loses

The difference between "today's task" and "accretive work"

Most rewrites serve the engineer, not the business