Claude Code

Verified against Claude Code · 2026-08-14

Set up a TECH_DEBT.md ledger Claude Code appends to instead of fixing things on the sly

A rules file that turns technical debt from a vague, unprioritized complaint into a tracked, file-and-line-referenced ledger with effort and impact scored per item, so debt gets paid down deliberately instead of opportunistically rewritten mid-task.

Claude Code4 fillable variables

The prompt

Ready to copy — highlighted parts are example details you can swap.

Set up TECH_DEBT.md at the repository root and establish the rule Claude Code follows around it from now on: when work in the ingestion pipeline (rag/loaders/ and rag/chunking/) surfaces something that is technical debt — not a bug, not a missing feature, but a shortcut, an outdated pattern, or a known-fragile piece of code — it gets logged here, not silently fixed as a side effect of whatever task happens to be touching it nearby.

For an initial pass, scan the ingestion pipeline (rag/loaders/ and rag/chunking/) now and populate the ledger with what you find, one row per item:

| Item | Location | Severity | Effort | Why it matters |

- Location must be an actual file and line or function, not a vague area description — an item nobody can find again by reading the ledger is not tracked, it is just noted.
- Severity and effort are scored using this rubric: Severity: low/medium/high based on blast radius if it fails in production; Effort: hours estimate assuming one engineer familiar with this module. Score both independently; a high-severity item can still be low-effort to fix, and conflating the two is how a ledger ends up ranked by how scary something sounds rather than by what should actually be worked on next.
- 'Why it matters' is one sentence stating the concrete consequence if this stays unfixed — a slow query under real load, a silent data-corruption edge case, a dependency past end-of-life — not a generic 'this is bad practice.'

If a ledger already exists at docs/TECH_DEBT.md (last updated three months ago, seven open items), read it first and merge into it rather than starting a second, competing list — reconcile any item that appears in both, and mark anything the existing ledger lists as fixed that this scan can now confirm is actually resolved in the current code.

PRIORITIZATION
At the end of the ledger, order items by highest severity first, then lowest effort as a tiebreaker, so cheap high-severity fixes surface at the very top, and state the ordering rule explicitly at the top of that section so a future session extending the list applies the same rule rather than inventing a new ordering.

RULE GOING FORWARD
When future work touches code near a logged debt item but the current task does not actually require fixing it, leave it alone and leave the ledger entry as is — do not fix it silently because you happen to be right there. If the current task's own scope genuinely requires touching the debt item to complete correctly, fix it, then update its ledger row to fixed with the commit reference, rather than leaving a now-inaccurate row for the next session to trip over.

Do not log anything here that is actually a bug (something already broken now) or a feature gap (something that was never built) — both belong in the issue tracker, not this ledger; TECH_DEBT.md is only for working code that is more fragile, harder to change, or costlier to run than it should be.

Customize

Optional — swap in your own details for the highlighted parts above.

Why this works

Technical debt tracked only in conversation or in someone's memory decays the same way any unwritten institutional knowledge does — it gets rediscovered repeatedly, argued about from scratch each time, and eventually just becomes ambient background complaint rather than something anyone acts on, which is why the ledger's most important structural feature is the same one that makes CLAUDE.md itself useful: it is a file a fresh Claude Code session reads automatically, so the debt list survives across sessions instead of resetting to zero every time context runs out. Requiring an actual file and line per item, rather than an area description, is what makes the difference between a ledger and a complaint list — 'the ingestion pipeline is messy' cannot be acted on by a future session or verified as fixed later, while 'rag/loaders/pdf_loader.py:88, silent except that swallows corrupt-PDF errors' can be found, fixed, and checked off with no ambiguity about whether it's the same item someone meant three weeks ago. Scoring severity and effort as two independent numbers rather than one blended priority is a deliberate correction against the natural bias to rank by how alarming something sounds — a severity-only ranking will bury a five-minute fix to a genuinely risky pattern beneath a terrifying-sounding but multi-week rewrite, when the actual next best action is almost always the cheap fix to the dangerous thing, not the expensive fix to anything. The rule against fixing debt silently mid-task exists because an agent that notices nearby debt while working tends to want to clean it up on the spot, which feels helpful in the moment but produces an unreviewable diff that mixes the actual requested change with an unrelated opportunistic rewrite, and quietly removes the paper trail the ledger exists to provide — the rule instead routes that impulse into either leaving a now-accurate ledger entry for deliberate future work, or fixing it only when the current task's own scope genuinely requires it, at which point it's a legitimate part of that diff rather than a surprise inside it.

What you get back

| Item | Location | Severity | Effort | Why it matters | |---|---|---|---|---| | Broad except swallows parse errors | rag/loaders/pdf_loader.py:88 | high | 2h | corrupt PDFs fail silently, no error surfaces to the ingestion job status | | Chunk size hardcoded, not from Settings | rag/chunking/fixed.py:14 | medium | 1h | can't tune per ingestion job without a code change and redeploy | Ordering rule: severity desc, effort asc as tiebreaker -> broad except fix ranked first (high severity, only 2h).

Verified against

Claude Code Sonnet 4.6 · 2026-08-14

Changelog

  • 2026-08-14 Initial publish, verified against Claude Code Sonnet 4.6.

Building this for real?

This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All Claude Code prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY