mkdir -p .claude/skills/tech-debt-radar/scripts
cd .claude/skills/tech-debt-radar

.claude/skills/tech-debt-radar/
├── SKILL.md              # 唯一入口：frontmatter + 指令
├── scripts/
│   └── scan.py           # 扫描+分级脚本
└── reference/
    └── severity.md       # 渐进式披露：分级细则（按需加载）

---
name: tech-debt-radar
description: 扫描代码库中的技术债标记（TODO/FIXME/HACK/XXX/BUG），按严重度分级并关联 git blame 计算债务年龄，输出可排期的 Markdown 报告。当用户提到「技术债」「扫一下 TODO」「代码里有多少 FIXME」「债务清单」「tech debt」时使用。
---

# 技术债雷达

## 何时使用

当用户想了解代码库中遗留债务的整体情况、需要为下一轮迭代排期、或在合并前评估新增债务时，调用此 Skill。

## 工作流程

1. 运行 `python3 scripts/scan.py`（无参数则扫描当前目录）
2. 脚本会输出一份分级清单到 stdout 和 `tech-debt-report.md`
3. 读取报告，向用户总结：债务总数、各级别分布、最老的 3 条债务、集中在哪些文件/模块
4. 若用户给出范围（如「只看 src/auth 目录」），把路径作为参数传入脚本

## 分级口径（简版）

- **P0 紧急**：`FIXME` / `BUG`，且位于生产代码路径（src/、app/、lib/）
- **P1 高**：`HACK` / `XXX`，位于生产代码路径
- **P2 中**：`TODO`，且债务年龄 > 30 天
- **P3 低**：`NOTE` / `OPTIMIZE`，或位于测试/脚本目录

完整分级细则见 `reference/severity.md`，在用户追问某条债务为何被归为某级时再读取。

#!/usr/bin/env python3
"""技术债扫描器：扫描标记、分级、关联 git blame。
用法: python3 scan.py [目标路径...]   # 默认当前目录
"""
import os, re, sys, subprocess
from datetime import datetime, timezone
from pathlib import Path

# 标记词 -> 基础权重（越大越严重）
MARKERS = {
    "BUG": 4, "FIXME": 4,
    "HACK": 3, "XXX": 3,
    "TODO": 2,
    "NOTE": 1, "OPTIMIZE": 1,
}
# 排除目录与文件类型
EXCLUDE_DIRS = {".git", "node_modules", "dist", "build", ".venv", "vendor", "__pycache__"}
EXCLUDE_EXT = {".md", ".lock", ".min.js", ".min.css", ".svg", ".png"}
# 生产代码路径前缀（影响升级）
PROD_PREFIXES = ("src/", "app/", "lib/", "internal/", "cmd/")

PATTERN = re.compile(r"\b(BUG|FIXME|HACK|XXX|TODO|NOTE|OPTIMIZE)\b[:\s]*(.*)")

def is_prod(rel_path: str) -> bool:
    return rel_path.replace("\\", "/").startswith(PROD_PREFIXES)

def blame_age_days(file_path: str, line_no: int) -> int | None:
    """通过 git blame 获取该行最后修改时间，返回距今天数。"""
    try:
        out = subprocess.run(
            ["git", "blame", "-L", f"{line_no},{line_no}", "--line-porcelain", file_path],
            capture_output=True, text=True, check=True,
        )
        for line in out.stdout.splitlines():
            if line.startswith("author-time "):
                ts = int(line.split()[1])
                return (datetime.now(timezone.utc).timestamp() - ts) // 86400
    except Exception:
        return None
    return None

def classify(marker: str, prod: bool, age: int | None) -> str:
    w = MARKERS[marker]
    if w >= 4 and prod: return "P0"      # BUG/FIXME 在生产路径
    if w >= 3 and prod: return "P1"      # HACK/XXX 在生产路径
    if marker == "TODO" and age and age > 30: return "P2"
    if w <= 1: return "P3"              # NOTE/OPTIMIZE
    return "P2"

def scan(roots):
    debts = []
    for root in roots:
        for dirpath, dirs, files in os.walk(root):
            dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS]
            for f in files:
                if Path(f).suffix in EXCLUDE_EXT: continue
                fp = os.path.join(dirpath, f)
                rel = os.path.relpath(fp)
                try:
                    with open(fp, encoding="utf-8", errors="ignore") as fh:
                        for i, line in enumerate(fh, 1):
                            m = PATTERN.search(line)
                            if not m: continue
                            marker, text = m.group(1), m.group(2).strip()
                            age = blame_age_days(fp, i)
                            sev = classify(marker, is_prod(rel), age)
                            debts.append((sev, rel, i, marker, age, text))
                except (UnicodeDecodeError, OSError):
                    continue
    return debts

def main():
    roots = sys.argv[1:] or ["."]
    debts = sorted(scan(roots), key=lambda d: (d[0], -(d[4] or 0)))
    # 输出到文件 + stdout
    lines = ["# 技术债报告", "", f"共 {len(debts)} 条债务", ""]
    lines.append("| 级别 | 文件 | 行 | 标记 | 年龄(天) | 内容 |")
    lines.append("|------|------|----|------|---------|------|")
    for sev, rel, i, marker, age, text in debts:
        lines.append(f"| {sev} | {rel} | {i} | {marker} | {age if age else '-'} | {text[:60]} |")
    report = "\n".join(lines)
    Path("tech-debt-report.md").write_text(report, encoding="utf-8")
    print(report)
    # 摘要
    from collections import Counter
    c = Counter(d[0] for d in debts)
    print(f"\n摘要: " + ", ".join(f"{k}={v}" for k, v in sorted(c.items())))

if __name__ == "__main__":
    main()

chmod +x scripts/scan.py

# 严重度判定细则

## P0 紧急（必须本迭代清掉）
- `BUG` / `FIXME` 出现在生产路径（src/ app/ lib/ internal/ cmd/）
- 出现在认证、支付、事务等关键模块，无论标记词

## P1 高
- `HACK` / `XXX` 出现在生产路径
- 任何标记词出现在最近一次生产事故相关文件

## P2 中
- `TODO` 且债务年龄 > 30 天
- 非生产路径的 `HACK` / `XXX`

## P3 低
- `NOTE` / `OPTIMIZE`
- 测试目录（test/ tests/ *_test.go）下的所有标记

cd /path/to/your/repo
claude

> 这个项目欠了多少技术债？

> 帮我扫一下代码里的 TODO 和 FIXME

> 只看 src/auth 目录的技术债，按严重度排一下

# 技术债报告

共 17 条债务

| 级别 | 文件 | 行 | 标记 | 年龄(天) | 内容 |
|------|------|----|------|---------|------|
| P0 | src/auth/login.py | 42 | FIXME | 89 | 临时绕过 OAuth 校验，上线前必须修 |
| P0 | src/payment/refund.go | 118 | BUG | 12 | 并发退款会重复扣款 |
| P1 | lib/cache.py | 7 | HACK | 203 | 用全局变量模拟线程局部存储 |
...
摘要: P0=2, P1=5, P2=7, P3=3

{"input": "扫一下所有 FIXME", "should_trigger": true}
{"input": "技术债雷达跑一下 src", "should_trigger": true}
{"input": "这段代码时间复杂度多少", "should_trigger": false}
{"input": "帮我写个 TODO 应用", "should_trigger": false}

# src/auth/login.py
def login(user):
    # FIXME: 临时绕过 OAuth 校验，上线前必须修
    return token(user)

// src/payment/refund.go
func Refund(orderID string) {
    // BUG: 并发退款会重复扣款
    processRefund(orderID)
}

cd /path/to/project
python3 .claude/skills/tech-debt-radar/scripts/scan.py src/

> 这两条 P0 债务分别在做什么？能合并到下个迭代吗？

flowchart TD
    A[用户: '扫一下技术债'] --> B{Claude 语义匹配}
    B -->|命中触发词| C[加载 SKILL.md]
    B -->|未命中| Z[按普通对话处理]
    C --> D[运行 scan.py]
    D --> E[正则扫描标记]
    E --> F[git blame 取债务年龄]
    F --> G[分级: P0-P3]
    G --> H[生成 tech-debt-report.md]
    H --> I[Claude 读取报告]
    I --> J[总结: 分布/最老/热点模块]
    J --> K[给出排期建议]
    K --> L{用户追问分级细则?}
    L -->|是| M[渐进式加载 reference/severity.md]
    L -->|否| N[完成]