The problem was never taking on debt — it's taking it on without noticing, without a reason, and without a plan to ever look at it again.
1The Difference Is Awareness, Not the Shortcut Itself
A hardcoded value chosen deliberately, with a reason and a note, is a different thing entirely from the same hardcoded value left behind because nobody thought about it. Both look identical in the code — the difference lives entirely in whether it was a conscious, tracked decision.
2Take the Debt When You're Still Answering 'Is This Worth It'
Debt is most justified when the alternative (building it properly) would be wasted effort if the answer turns out to be 'this isn't worth building at all.' Once something is validated as genuinely worth investing in, the calculation for taking on more debt around it changes.
3Step-by-Step Breakdown
Technical debt is a useful metaphor precisely because loans aren't inherently bad — a loan taken deliberately, with a plan to repay it, to get something valuable sooner, is a reasonable trade. Debt that accumulates by accident, with no plan and no awareness, is the actual problem.
Intentional debt is the right call when you're still validating whether something is worth building at all — hardcoding a value instead of building an admin panel for it, or skipping an edge case you're confident is rare, buys you a faster answer to 'is this worth it' before investing in doing it properly.
What makes technical debt 'intentional' rather than just a shortcut that happened by accident?
- →Any shortcut counts as intentional debt as long as it saves time
- →It's a deliberate, aware trade-off — made with a specific reason and some plan to revisit it — rather than an unnoticed or unplanned corner cut
- →It only counts as intentional if a manager approved it in writing
- →Intentional debt doesn't need to ever be repaid
The habit that keeps intentional debt from quietly becoming accidental debt: write it down. A short comment or ticket noting what was skipped and why turns a silent shortcut into a visible, trackable decision someone can revisit later with the right context.
Why does writing down an intentional shortcut (even briefly) matter?
- →It doesn't matter, the code itself is enough documentation
- →It turns a silent, easy-to-forget corner cut into a visible, trackable decision that can be revisited with the original context later, instead of being rediscovered as a confusing surprise
- →It's only useful for legal compliance
- →It makes the code run faster
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Accessibility Is a Poor Candidate for Intentional Debt
Unlike an admin panel or a rare edge case, skipping accessibility work doesn't just risk revisiting it later — it actively excludes real users right now. Treat accessibility as one of the categories where 'take the shortcut and revisit later' is rarely the right trade, even under time pressure.
// Acceptable debt: hardcoded config value, revisit if it scales
// Poor debt candidate: skipped keyboard navigation, excludes users todaySEO Implications
- 1
Target 'intentional technical debt' as a distinct, positive-framed concept from 'avoiding technical debt' content
Most existing content treats all technical debt as purely negative. Readers researching the deliberate, strategic use of debt want a framework for choosing it well, not just warnings against it.
Best Practices
Write a One-Line 'Debt Note' at the Point of the Shortcut
Right where the shortcut is taken, leave a short comment or linked ticket stating what was skipped and why — this costs seconds and is what separates a deliberate, trackable trade from an invisible landmine for whoever encounters it next.
Frequent Bugs
Taking a shortcut under time pressure with the intention to 'come back to it later,' but leaving no note or ticket, so the context and even the existence of the shortcut is forgotten.
Make writing the debt note part of the act of taking the shortcut itself, not a follow-up task — if there's no time to write one line explaining the trade, that's a signal to reconsider the shortcut.
Real-World Examples
The Hardcoded Value That Was Fine
An engineer hardcoded a shipping fee instead of building a pricing admin panel, with a comment noting the decision and a linked ticket. Three months later, when a second shipping tier was needed, the comment made it trivial to find and address — the debt was intentional, tracked, and paid off cheaply exactly when it mattered.
// DEBT: hardcoded shipping fee, revisit if a 2nd tier is needed (see TICKET-142)
const SHIPPING_FEE = 5.99;