mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
564 lines
27 KiB
HTML
564 lines
27 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head>
|
||
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>engineering-technical-debt</title>
|
||
<meta name="color-scheme" content="dark">
|
||
<style>
|
||
/* Committed to one visual world: a dark instrument panel. No light variant —
|
||
the dot field and the hairline rules only read on black, and a naive
|
||
inversion would wash both out. Every colour is painted explicitly so the page
|
||
never borrows a host background. */
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
||
|
||
:root{
|
||
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
||
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
||
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
||
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
||
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
||
--mono:var(--font-zen-mono);
|
||
--sans:var(--font-zen-sans);
|
||
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
||
--r:999px; --r-soft:14px;
|
||
}
|
||
*{box-sizing:border-box}
|
||
html{-webkit-text-size-adjust:100%}
|
||
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
||
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
||
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
||
|
||
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
||
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
||
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
||
would cut off the copy-prompt menu. */
|
||
.hero{position:relative;border-bottom:1px solid var(--line)}
|
||
.hero::before{content:"";position:absolute;inset:0;
|
||
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
||
background-size:7px 7px;
|
||
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
pointer-events:none}
|
||
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
||
|
||
nav{border-bottom:1px solid var(--line)}
|
||
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
||
justify-content:space-between;align-items:center;gap:1rem}
|
||
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
||
display:inline-flex;align-items:center;gap:.6rem}
|
||
.brand i{font-style:normal;color:var(--faint)}
|
||
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
||
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
||
nav a.up:hover{color:var(--ink)}
|
||
|
||
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
||
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
||
h1 em{font-style:normal;color:var(--faint)}
|
||
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
||
|
||
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
||
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
||
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
||
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
||
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
||
line-height:1.2;font-weight:400}
|
||
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
||
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
||
.btn.solid:hover{background:#d8d8d4}
|
||
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
||
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
||
|
||
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
||
.copy{position:relative;display:inline-flex}
|
||
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
||
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
||
padding:.4rem;display:flex;flex-direction:column;
|
||
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
||
.menu[hidden]{display:none}
|
||
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
||
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
||
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
||
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
||
white-space:nowrap}
|
||
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
||
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
||
.mi:hover .mark{color:var(--ink)}
|
||
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
||
letter-spacing:.1em;text-transform:uppercase}
|
||
|
||
/* Works-with bar: one scrolling row, name and mark per agent. */
|
||
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
||
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
||
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
||
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
||
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
||
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
||
display:flex;align-items:center}
|
||
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
||
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
||
-webkit-overflow-scrolling:touch;
|
||
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
||
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
||
.bar::-webkit-scrollbar{display:none}
|
||
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
||
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
||
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
||
text-decoration:none;background:var(--ground)}
|
||
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
||
.agent .mark{width:.95rem;height:.95rem}
|
||
|
||
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
||
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
||
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
||
p{margin:0 0 1rem;max-width:70ch}
|
||
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
||
li{margin:.22rem 0}
|
||
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
||
text-decoration-color:var(--line-hi)}
|
||
a:hover{text-decoration-color:var(--ink)}
|
||
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
||
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
||
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
||
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
||
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
||
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
||
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
||
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
||
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
||
display:block;overflow-x:auto}
|
||
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
||
|
||
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
||
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
||
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
||
white-space:pre;line-height:1.9}
|
||
.curl b{color:var(--ink);font-weight:400}
|
||
.curl i{font-style:normal;color:var(--faint)}
|
||
|
||
/* index */
|
||
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
||
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
||
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
||
#q:focus{outline:none;border-color:var(--soft)}
|
||
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
||
text-transform:uppercase;margin:0 0 2rem}
|
||
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
||
padding-bottom:.45rem}
|
||
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
||
border-radius:var(--r-soft);text-decoration:none}
|
||
.row:hover{background:#0a0a0a}
|
||
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
||
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
||
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
||
color:var(--faint);font-size:.85rem}
|
||
footer a{color:var(--soft)}
|
||
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
||
margin:0 0 2rem;font-size:.85rem}
|
||
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
||
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
||
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
||
.fmap a:hover{text-decoration:underline}
|
||
.fmap div{color:var(--faint);line-height:1.5}
|
||
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
||
|
||
@media (max-width:640px){
|
||
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
||
.btns{gap:.5rem}
|
||
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
||
.copy,.copy .btn{width:100%;justify-content:center}
|
||
.menu{left:0;right:0;min-width:0}
|
||
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
||
.strip b{border-right:0;padding-right:0}
|
||
.bar{width:100%}
|
||
}
|
||
</style>
|
||
<link rel="icon" href="/favicon.svg">
|
||
<link rel="canonical" href="https://hanzoskills.com/engineering-technical-debt">
|
||
<link rel="alternate" type="text/markdown" href="/engineering-technical-debt.md">
|
||
<script type="module" src="/webmcp.js"></script>
|
||
</head>
|
||
<!-- Reading this with a machine? Every page here is also plain markdown.
|
||
This one: https://hanzoskills.com/engineering-technical-debt.md
|
||
Index: https://hanzoskills.com/llms.txt
|
||
Corpus: https://hanzoskills.com/all.md
|
||
Append .md to any path for the markdown twin. -->
|
||
<body>
|
||
<nav><div class="in">
|
||
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
||
<a class="up" href="/">All skills</a>
|
||
</div></nav>
|
||
|
||
<div class="wrap">
|
||
<h1>engineering-technical-debt</h1><p class="lede">Identifying, measuring, tracking, and managing technical debt strategically and systematically</p><h1>Technical Debt Management</h1>
|
||
<p><strong>Scope</strong>: Comprehensive guide to identifying, measuring, prioritizing, and paying down technical debt <strong>Lines</strong>: ~320 <strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
||
<hr>
|
||
<h2>When to Use This Skill</h2>
|
||
<p>Activate this skill when:</p>
|
||
<ul><li>Evaluating whether to take on technical shortcuts</li><li>Prioritizing refactoring vs new features</li><li>Explaining tech debt costs to stakeholders</li><li>Planning debt paydown sprints</li><li>Auditing codebase health</li><li>Establishing tech debt policies</li><li>Preventing debt accumulation</li><li>Recovering from tech debt crisis</li></ul>
|
||
<h2>Core Concepts</h2>
|
||
<h3>Concept 1: What is Technical Debt?</h3>
|
||
<p><strong>Definition</strong>: Code shortcuts that speed up delivery but increase future maintenance costs</p>
|
||
<p><strong>Martin Fowler's Quadrant</strong>:</p>
|
||
<pre><code> Reckless Prudent
|
||
Deliberate | "We don't have | "We must ship now,
|
||
| time for | will refactor later"
|
||
| design" |
|
||
-------------|----------------|------------------
|
||
Inadvertent | "What's | "Now we know how
|
||
| layering?" | we should have
|
||
| | done it"</code></pre>
|
||
<p><strong>Types of Tech Debt</strong>:</p>
|
||
<ul><li><strong>Code Debt</strong>: Poor code quality, duplication, smells</li><li><strong>Design Debt</strong>: Wrong abstractions, tight coupling</li><li><strong>Test Debt</strong>: Missing tests, brittle tests</li><li><strong>Documentation Debt</strong>: Outdated or missing docs</li><li><strong>Infrastructure Debt</strong>: Outdated dependencies, poor tooling</li><li><strong>Architecture Debt</strong>: Scaling issues, monolith problems</li></ul>
|
||
<hr>
|
||
<h3>Concept 2: Interest vs Principal</h3>
|
||
<p><strong>Like Financial Debt</strong>:</p>
|
||
<ul><li><strong>Principal</strong>: Cost to fix the issue</li><li><strong>Interest</strong>: Ongoing cost of living with it</li></ul>
|
||
<pre><code class="lang-python"># Example: Duplicated validation logic (Principal: 1 day to refactor)
|
||
|
||
# File 1
|
||
def create_user(email):
|
||
if "@" not in email: # Duplicated
|
||
raise ValueError("Invalid email")
|
||
# ... save user
|
||
|
||
# File 2
|
||
def update_user(email):
|
||
if "@" not in email: # Duplicated
|
||
raise ValueError("Invalid email")
|
||
# ... update user
|
||
|
||
# File 3
|
||
def invite_user(email):
|
||
if "@" not in email: # Duplicated
|
||
raise ValueError("Invalid email")
|
||
# ... send invite
|
||
|
||
# Interest paid:
|
||
# - Every bug fix needs 3 changes
|
||
# - Every validation enhancement needs 3 updates
|
||
# - Risk of inconsistency
|
||
# - Slows down all email-related features</code></pre>
|
||
<hr>
|
||
<h3>Concept 3: When to Take On Debt</h3>
|
||
<p><strong>Good Reasons</strong> (Deliberate, Prudent):</p>
|
||
<ul><li>MVP to validate market fit</li><li>Time-sensitive opportunity</li><li>Competitive pressure</li><li>Known paydown plan</li></ul>
|
||
<p><strong>Bad Reasons</strong> (Reckless):</p>
|
||
<ul><li>Laziness or lack of skill</li><li>"We'll never come back to this"</li><li>No plan to pay down</li><li>Not understanding implications</li></ul>
|
||
<hr>
|
||
<h2>Patterns</h2>
|
||
<h3>Pattern 1: Debt Identification</h3>
|
||
<p><strong>Code Smells Checklist</strong>:</p>
|
||
<pre><code>[ ] Duplicated code (copy-paste)
|
||
[ ] Long methods (> 30 lines)
|
||
[ ] Large classes (> 500 lines)
|
||
[ ] Long parameter lists (> 4 params)
|
||
[ ] Divergent change (class changes for multiple reasons)
|
||
[ ] Shotgun surgery (one change affects many classes)
|
||
[ ] Feature envy (method uses another class more than its own)
|
||
[ ] Data clumps (same group of data everywhere)
|
||
[ ] Primitive obsession (over-reliance on primitives)
|
||
[ ] Comments explaining complex code</code></pre>
|
||
<p><strong>Automated Detection</strong>:</p>
|
||
<pre><code class="lang-bash"># Python: Code complexity
|
||
radon cc src/ -a -nb # Cyclomatic complexity
|
||
radon mi src/ # Maintainability index
|
||
|
||
# JavaScript: ESLint complexity rules
|
||
eslint --max-complexity=10 src/
|
||
|
||
# Code duplication
|
||
jscpd src/ # Copy-paste detector
|
||
|
||
# Security debt
|
||
npm audit
|
||
pip-audit</code></pre>
|
||
<hr>
|
||
<h3>Pattern 2: Debt Measurement</h3>
|
||
<p><strong>Debt Score Formula</strong>:</p>
|
||
<pre><code>Debt Score = (Complexity × Impact × Frequency) / Ease of Fix
|
||
|
||
Complexity: 1-5 (how complex is the problem?)
|
||
Impact: 1-5 (how many people/systems affected?)
|
||
Frequency: 1-5 (how often is this code touched?)
|
||
Ease of Fix: 1-5 (how easy to fix?)</code></pre>
|
||
<p><strong>Example Scoring</strong>:</p>
|
||
<pre><code class="lang-python"># Debt Item: Duplicated email validation (3 places)
|
||
Complexity = 2 # Simple validation logic
|
||
Impact = 4 # Used in 10+ features
|
||
Frequency = 5 # Changed weekly
|
||
Ease of Fix = 4 # Easy - extract to function
|
||
|
||
Debt Score = (2 × 4 × 5) / 4 = 10
|
||
|
||
# Debt Item: Monolithic architecture
|
||
Complexity = 5 # Very complex to split
|
||
Impact = 5 # Affects entire system
|
||
Frequency = 3 # Changes monthly
|
||
Ease of Fix = 1 # Very difficult
|
||
|
||
Debt Score = (5 × 5 × 3) / 1 = 75 # High priority!</code></pre>
|
||
<hr>
|
||
<h3>Pattern 3: Debt Tracking</h3>
|
||
<p><strong>Debt Register</strong> (track in <code>TECH_DEBT.md</code>):</p>
|
||
<pre><code class="lang-markdown"># Technical Debt Register
|
||
|
||
## High Priority (Score > 50)
|
||
|
||
### TD-001: Monolithic Database
|
||
- **Debt Score**: 75
|
||
- **Principal**: 4 weeks
|
||
- **Interest**: 1 day/week (slow queries, deployment bottleneck)
|
||
- **Paydown Plan**: Split into microservices over Q2
|
||
- **Status**: Planned
|
||
|
||
## Medium Priority (Score 20-50)
|
||
|
||
### TD-002: Missing Integration Tests
|
||
- **Debt Score**: 30
|
||
- **Principal**: 2 weeks
|
||
- **Interest**: 2 hours/week (manual testing)
|
||
- **Paydown Plan**: Add tests incrementally with each feature
|
||
- **Status**: In Progress
|
||
|
||
## Low Priority (Score < 20)
|
||
|
||
### TD-003: Outdated Dependencies
|
||
- **Debt Score**: 12
|
||
- **Principal**: 1 day
|
||
- **Interest**: 30 min/month (security patches)
|
||
- **Paydown Plan**: Update in Q3 maintenance sprint
|
||
- **Status**: Backlog</code></pre>
|
||
<hr>
|
||
<h3>Pattern 4: Debt Paydown Strategies</h3>
|
||
<p><strong>Boy Scout Rule</strong>: Leave code better than you found it</p>
|
||
<pre><code class="lang-python"># Every PR: Small improvements
|
||
# Before
|
||
def process_user(email, name, age, address, phone): # Too many params
|
||
# ... 50 lines of code
|
||
|
||
# After (in PR for unrelated feature)
|
||
class UserData:
|
||
def __init__(self, email, name, age, address, phone):
|
||
self.email = email
|
||
self.name = name
|
||
# ...
|
||
|
||
def process_user(user_data: UserData): # Better!
|
||
# ... same logic</code></pre>
|
||
<p><strong>Debt Sprints</strong>: Dedicated time to pay down debt</p>
|
||
<pre><code>Sprint 10: Features (80%) + Debt (20%)
|
||
- Feature: User dashboard
|
||
- Debt: Extract shared validation logic
|
||
|
||
Sprint 11: Features (80%) + Debt (20%)
|
||
- Feature: Payment integration
|
||
- Debt: Add integration tests for auth
|
||
|
||
Sprint 15: Debt Sprint (100%)
|
||
- Upgrade all dependencies
|
||
- Refactor monolithic service
|
||
- Add missing documentation</code></pre>
|
||
<p><strong>Strangler Fig Pattern</strong>: Gradually replace old system</p>
|
||
<pre><code>1. Identify module to replace
|
||
2. Build new implementation alongside old
|
||
3. Route new requests to new code
|
||
4. Migrate existing data gradually
|
||
5. Remove old code when fully migrated
|
||
|
||
Example:
|
||
┌─────────────────┐
|
||
│ Old Auth System │ ←─┐
|
||
└─────────────────┘ │
|
||
├─ Route new users to new system
|
||
┌─────────────────┐ │ Migrate old users gradually
|
||
│ New Auth System │ ←─┘
|
||
└─────────────────┘</code></pre>
|
||
<hr>
|
||
<h3>Pattern 5: Preventing Debt</h3>
|
||
<p><strong>Definition of Done</strong> (include quality checks):</p>
|
||
<pre><code class="lang-markdown">## Definition of Done
|
||
|
||
Code Complete:
|
||
- [ ] Feature implemented
|
||
- [ ] Unit tests written (80%+ coverage)
|
||
- [ ] Integration tests added
|
||
- [ ] Documentation updated
|
||
- [ ] Code reviewed
|
||
- [ ] No TODO/FIXME comments (create tickets instead)
|
||
- [ ] No copy-paste code
|
||
- [ ] Cyclomatic complexity < 10
|
||
- [ ] No security vulnerabilities</code></pre>
|
||
<p><strong>Pre-Commit Hooks</strong>:</p>
|
||
<pre><code class="lang-yaml"># .pre-commit-config.yaml
|
||
repos:
|
||
- repo: https://github.com/psf/black
|
||
hooks:
|
||
- id: black # Formatting
|
||
|
||
- repo: https://github.com/pycqa/flake8
|
||
hooks:
|
||
- id: flake8 # Linting
|
||
args: [--max-complexity=10]
|
||
|
||
- repo: https://github.com/pre-commit/mirrors-mypy
|
||
hooks:
|
||
- id: mypy # Type checking</code></pre>
|
||
<p><strong>Quality Gates in CI</strong>:</p>
|
||
<pre><code class="lang-yaml"># .github/workflows/quality.yml
|
||
- name: Check code quality
|
||
run: |
|
||
radon cc src/ -a -nb --total-average-threshold=B
|
||
radon mi src/ --min=C
|
||
|
||
- name: Check test coverage
|
||
run: |
|
||
pytest --cov=src --cov-fail-under=80
|
||
|
||
- name: Check for code duplication
|
||
run: |
|
||
jscpd src/ --threshold 5 # Fail if > 5% duplication</code></pre>
|
||
<hr>
|
||
<h2>Debt Communication</h2>
|
||
<h3>Explaining to Stakeholders</h3>
|
||
<p><strong>Avoid</strong>: "We have technical debt" (vague, no context)</p>
|
||
<p><strong>Better</strong>: Use analogies and business impact</p>
|
||
<pre><code>"Our authentication system is like a house built without a foundation.
|
||
It works today, but:
|
||
- Every new feature takes 2x longer to build
|
||
- Security fixes require changes in 5 different places
|
||
- We have 3 critical bugs per month due to inconsistency
|
||
|
||
Investment: 2 weeks to refactor
|
||
Payoff: 50% faster feature development, 90% fewer auth bugs
|
||
ROI: Pays for itself in 2 months"</code></pre>
|
||
<p><strong>Debt Dashboard</strong> (visualize for stakeholders):</p>
|
||
<pre><code>Tech Debt Metrics Dashboard
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
Total Debt: 12 weeks
|
||
Interest Cost: 8 hours/week
|
||
|
||
High Priority Debt: [██████----] 60%
|
||
Test Coverage: [████------] 45%
|
||
Code Duplication: [██████----] 15%
|
||
Complexity: [████████--] 80%
|
||
|
||
Trend: ↑ Increasing (action needed!)</code></pre>
|
||
<hr>
|
||
<h2>Best Practices</h2>
|
||
<h3>Debt Management Guidelines</h3>
|
||
<p><strong>Do's</strong>:</p>
|
||
<ul><li>Track debt explicitly (don't hide it)</li><li>Measure debt objectively</li><li>Pay down incrementally</li><li>Prevent new debt</li><li>Communicate impact to stakeholders</li><li>Schedule regular debt sprints</li><li>Use automated tools</li></ul>
|
||
<p><strong>Don'ts</strong>:</p>
|
||
<ul><li>Don't ignore growing debt</li><li>Don't pay all debt at once (balance with features)</li><li>Don't blame individuals</li><li>Don't take on debt without plan</li><li>Don't use "tech debt" as excuse for poor work</li><li>Don't let debt compound</li></ul>
|
||
<hr>
|
||
<h2>Anti-Patterns</h2>
|
||
<h3>Common Debt Management Mistakes</h3>
|
||
<pre><code>❌ "We'll fix it later" (Never happens)
|
||
→ Fix now or create explicit paydown plan
|
||
|
||
❌ Ignoring debt until crisis
|
||
→ Track and pay down incrementally
|
||
|
||
❌ Only paying principal, ignoring interest
|
||
→ Prioritize high-interest debt first
|
||
|
||
❌ 100% features, 0% debt paydown
|
||
→ Allocate 20% of sprint to debt
|
||
|
||
❌ Rewriting from scratch
|
||
→ Refactor incrementally (strangler fig)
|
||
|
||
❌ Not measuring debt
|
||
→ Quantify to prioritize effectively
|
||
|
||
❌ Debt as excuse for poor quality
|
||
→ Deliberate, prudent debt only</code></pre>
|
||
<hr>
|
||
<h2>Decision Framework</h2>
|
||
<h3>Should We Take On This Debt?</h3>
|
||
<pre><code>IF time_pressure AND short_term_need AND have_paydown_plan:
|
||
TAKE_ON_DEBT
|
||
DOCUMENT(why, when_fix, cost)
|
||
SCHEDULE_PAYDOWN
|
||
ELSE:
|
||
DO_IT_RIGHT</code></pre>
|
||
<p><strong>Example Decision Matrix</strong>: | Situation | Take Debt? | Condition | |-----------|------------|-----------| | MVP launch | ✅ Yes | Must have paydown plan | | Competitive threat | ✅ Yes | Document & schedule fix | | Learning new tech | ✅ Yes | First time doing X | | Lack of skill | ❌ No | Learn or ask for help | | Laziness | ❌ No | Do it right | | No plan to fix | ❌ No | Schedule paydown or don't ship |</p>
|
||
<hr>
|
||
<h2>Code Examples</h2>
|
||
<h3>Before (High Debt):</h3>
|
||
<pre><code class="lang-python"># Duplicated validation everywhere
|
||
def create_user(email, password):
|
||
if not email or "@" not in email:
|
||
raise ValueError("Invalid email")
|
||
if len(password) < 8:
|
||
raise ValueError("Password too short")
|
||
# ... create user
|
||
|
||
def update_email(user_id, email):
|
||
if not email or "@" not in email: # Duplicated!
|
||
raise ValueError("Invalid email")
|
||
# ... update email
|
||
|
||
def send_invite(email):
|
||
if not email or "@" not in email: # Duplicated!
|
||
raise ValueError("Invalid email")
|
||
# ... send invite</code></pre>
|
||
<h3>After (Debt Paid):</h3>
|
||
<pre><code class="lang-python"># Extracted validation (DRY)
|
||
class EmailValidator:
|
||
@staticmethod
|
||
def validate(email: str) -> None:
|
||
if not email or "@" not in email:
|
||
raise ValueError("Invalid email")
|
||
|
||
class PasswordValidator:
|
||
@staticmethod
|
||
def validate(password: str) -> None:
|
||
if len(password) < 8:
|
||
raise ValueError("Password too short")
|
||
|
||
def create_user(email, password):
|
||
EmailValidator.validate(email)
|
||
PasswordValidator.validate(password)
|
||
# ... create user
|
||
|
||
def update_email(user_id, email):
|
||
EmailValidator.validate(email)
|
||
# ... update email
|
||
|
||
def send_invite(email):
|
||
EmailValidator.validate(email)
|
||
# ... send invite</code></pre>
|
||
<hr>
|
||
<h2>Related Skills</h2>
|
||
<ul><li><strong>engineering-refactoring-patterns</strong>: Techniques for paying down debt</li><li><strong>engineering-code-quality</strong>: Preventing debt through quality</li><li><strong>engineering-code-review</strong>: Catching debt in reviews</li><li><strong>engineering-test-driven-development</strong>: Preventing test debt</li><li><strong>engineering-continuous-integration</strong>: Automated debt detection</li></ul>
|
||
<hr>
|
||
<h2>References</h2>
|
||
<ul><li><a href="https://martinfowler.com/bliki/TechnicalDebt.html">Technical Debt by Martin Fowler</a></li><li><a href="https://www.construx.com/blog/managing-technical-debt/">Managing Technical Debt by Steve McConnell</a></li><li><a href="https://stackoverflow.blog/2023/02/27/the-human-cost-of-tech-debt/">The Human Cost of Tech Debt</a></li><li><a href="https://martinfowler.com/bliki/TechnicalDebtQuadrant.html">Tech Debt Quadrant</a></li></ul>
|
||
<footer>
|
||
<div class="fmap">
|
||
<div><b>Build</b>
|
||
<a href="https://hanzo.app">hanzo.app</a> app builder
|
||
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
||
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
||
<div><b>Run</b>
|
||
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
||
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
||
<div><b>Account</b>
|
||
<a href="https://hanzo.id">hanzo.id</a> sign in
|
||
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
||
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
||
<div><b>Company</b>
|
||
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
||
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
||
</div>
|
||
<div class="fend"><a href="/engineering-technical-debt.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
||
</footer>
|
||
</div></body></html> |