A codebase audit workflow for finding and organizing technical debt—the unfinished cleanup and design problems that make software harder to change. It records evidence from files, metrics, and version history.

Use it to find TODOs, ignored type errors, oversized or complex code, duplication, outdated or vulnerable dependencies, and other cleanup items, then save a prioritized report.

It turns vague concerns about code quality into a documented list of specific problems. It also helps rank work by risk and separates investigation from later fixes.

tech-debt — Skill for Claude Code by rtazima

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add rtazima/claude-proj-blueprint --skill tech-debt

Clone the repo

git clone --depth 1 https://github.com/rtazima/claude-proj-blueprint

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/rtazima/claude-proj-blueprint/tech-debt/github.svg)](https://agentmods.dev/skills/rtazima/claude-proj-blueprint/tech-debt)

Your own site

<a href="https://agentmods.dev/skills/rtazima/claude-proj-blueprint/tech-debt"><img src="https://agentmods.dev/badge/skills/rtazima/claude-proj-blueprint/tech-debt/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/rtazima/claude-proj-blueprint/tech-debt"><img src="https://agentmods.dev/badge/skills/rtazima/claude-proj-blueprint/tech-debt.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 56 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 1,396 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00056	$0.01396
Opus 5	$0.00028	$0.00698
Sonnet 5	$0.00011	$0.00279
Haiku 4.5	$0.00006	$0.00140

Measured 8d ago against content hash 5ceb15d3ee94, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-08, from the pricing page.

Security

Grade A, and why

tech-debt scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 8d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/skills/tech-debt/SKILL.md · 151 lines

How it starts

The opening of the file, as written. The whole thing — 151 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Tech Debt Tracker

Systematically identify, catalog, and prioritize technical debt. Not opinions — evidence-based assessment from the codebase itself.

Rules

Evidence over opinion — every debt item must reference specific files, lines, or metrics
Quantify impact — estimate effort to fix and cost of NOT fixing
Prioritize by risk — debt near active features > debt in dormant code
Check history — use git log to find high-churn files (debt compounds where changes are frequent)
Output to docs — write report to docs/architecture/tech-debt-report-{date}.md
Don't fix during audit — catalog first, fix later (separate concerns)

Debt Categories

1. Code quality debt

TODO / FIXME / HACK / XXX comments without tracking
@ts-ignore / # type: ignore / nolint suppressions
any types (TypeScript) or untyped functions
Functions > 50 lines or files > 500 lines
Cyclomatic complexity hotspots (deeply nested logic)
Copy-paste duplication (similar blocks in 3+ places)

2. Dependency debt

Outdated dependencies (major versions behind)
Dependencies with known vulnerabilities
Deprecated packages still in use
Unnecessary dependencies (installed but unused)
Pinned to exact versions without update strategy

3. Test debt

Source files without corresponding test files
Tests that are skipped (.skip, @pytest.mark.skip, xit)
Tests with no assertions (passing but testing nothing)
Missing edge case coverage (only happy path tested)
Flaky tests (pass/fail inconsistently)

4. Architecture debt

Circular dependencies between modules
God objects/files (one file does everything)
Missing abstraction layers (business logic in controllers/handlers)
Hardcoded values that should be configurable
Deferred ADR decisions ("we'll decide later" still pending)

5. Documentation debt

CLAUDE.md [SPEC] markers still unfilled
Missing or outdated .env.example entries
README project structure doesn't match actual files
ADRs with status "proposed" that were never accepted/rejected
Runbooks that reference outdated procedures

Read the full file on GitHub · 151 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

8d ago First seen · 151 lines · 56 tokens per session scan A 5ceb15d3ee94

Subscribe to this mod's changes

tech-debt is a skill published in the GitHub repository rtazima/claude-proj-blueprint (20 stars, last pushed 3mo ago), licensed MIT. It adds 56 tokens to every session and 1,396 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Claude Code Debugging ai-agents architecture chroma developer-tools figma-make

truecourse-fix

Fix TrueCourse violations that have suggested fixes.

truecourse-ai/truecourse · 13 tokens

truecourse-list

List TrueCourse violations found in this repository.

truecourse-ai/truecourse · 12 tokens

mandu-lint

A code-quality checking guide built around linting, type checking, and architecture checks. Linting finds issues such as unused variables, while type checking catches incorrect data types.

konamgil/mandu · 53 tokens

mandu-mcp-verify

An automatic verification workflow for the Mandu project that runs after edits, generated files, or before a commit. It checks generated behavior, architecture rules, code quality, and project structure in parallel.

konamgil/mandu · 66 tokens

scan

Scan a project with sentrux to get structural health grades (A-F) across 14 dimensions including coupling, cycles, cohesion, dead code, and test coverage. Use when the user wants to check code quality, architecture health, or before/after an agent session.

sentrux/sentrux · 57 tokens

pointer

Runs a bounded evidence conversation over an existing implementation, asks one decision-changing question at a time, presents correction options, and applies the accepted correction plan once. Use when the user invokes /glasses:pointer, asks Pointer to inspect or correct an implementation, or wants a focused diagnosis…

DanielGouveiah/glasses · 62 tokens