flowchart LR
    A[会话启动] --> B[只加载各 Skill 的<br/>description 摘要<br/>≈ 极低成本]
    B --> C{是否被触发?}
    C -- 用户敲 /命令 --> D[加载完整 SKILL.md 正文]
    C -- Claude 判断描述匹配 --> D
    C -- 不匹配 --> E[正文永不加载<br/>零成本]
    D --> F[执行动态注入 !命令]
    F --> G[把脚本输出 + 指令<br/>一起交给 Claude]
    G --> H[Claude 产出最终结果]

mkdir -p ~/.claude/skills/tech-debt-scan
cd ~/.claude/skills/tech-debt-scan

~/.claude/skills/tech-debt-scan/
├── SKILL.md              # 必需：frontmatter + 指令
└── scan_tech_debt.sh     # 可选：支撑脚本（干脏活的）

#!/usr/bin/env bash
# scan_tech_debt.sh — 扫描技术债标记，附加 git blame 的作者与债龄
set -euo pipefail

ROOT="${1:-.}"          # $1 为空时默认扫当前目录
cd "$ROOT"

# 1) grep 出所有 TODO/FIXME/HACK/XXX，过滤常见无关目录与二进制后缀
grep -rnIE '\b(TODO|FIXME|HACK|XXX)\b[: ]' \
  --include='*.py' --include='*.js' --include='*.ts' --include='*.tsx' \
  --include='*.java' --include='*.go' --include='*.rs' \
  --exclude-dir=node_modules --exclude-dir=.git \
  --exclude-dir=dist --exclude-dir=build --exclude-dir=.next \
  . 2>/dev/null || true \
| while IFS=: read -r file lineno content; do
    [ -f "$file" ] || continue

    # 2) git blame 该行，取作者与提交时间戳
    blame=$(git blame --line-porcelain "$file" -L "$lineno,$lineno" 2>/dev/null || true)
    author=$(awk '/^author /{print $2" "$3; exit}' <<<"$blame")
    ts=$(awk '/^author-time /{print $2; exit}' <<<"$blame")

    # 3) 把时间戳换算成"债龄天数"
    days="-"
    if [[ "$ts" =~ ^[0-9]+$ ]]; then
      days=$(( ( $(date +%s) - ts ) / 86400 ))
    fi

    # 4) 严重度初判：FIXME/HACK = 高，其余 = 低（留给 Claude 再细化）
    sev="低"
    if grep -qE '\bFIXME\b|\bHACK\b' <<<"$content"; then sev="高"; fi

    content=$(printf '%s' "$content" | sed 's/^[[:space:]]*//; s/|/\\|/g')
    # 输出：严重度 | 文件:行号 | 债龄 | 作者 | 内容
    printf '%s|%s:%s|%s天|%s|%s\n' "$sev" "$file" "$lineno" "$days" "$author" "$content"
  done

chmod +x ~/.claude/skills/tech-debt-scan/scan_tech_debt.sh

---
name: 技术债扫描
description: 扫描代码库的 TODO/FIXME/HACK/XXX 注释，结合 git blame 算出债龄与作者，输出按严重度和陈旧度排序的技术债清单。在用户问"技术债""还有多少 TODO""哪些 FIXME 该先还""清理技术债"时使用。
argument-hint: [扫描根目录，默认当前目录]
allowed-tools: Bash Read
---

## 待分析的原始债清单

扫描脚本输出（格式：严重度 | 文件:行号 | 债龄 | 作者 | 内容）：

\`\`\`
!`${CLAUDE_SKILL_DIR}/scan_tech_debt.sh "$ARGUMENTS"`
\`\`\`

## 你的任务

把上面的原始清单整理成一份**技术债体检报告**：

1. **总览**：报总数，并按标记类型（TODO/FIXME/HACK/XXX）与严重度分桶统计。
2. **明细表**：输出 Markdown 表格，列 `严重度 | 债龄 | 文件:行号 | 作者 | 内容摘要`，**按"严重度降序、债龄降序"排序**——FIXME/HACK 且超过 90 天的排最前。
3. **Top 3 必还债**：逐条说明为什么危险（FIXME=已知缺陷，HACK=脆弱实现，XXX=待定危险区），并给处理方向（删除 / 重写 / 补测试 / 转工单）。
4. **空结果**：若脚本输出为空，明确回复"未发现技术债标记，工作树干净"。

`$ARGUMENTS` 是用户传入的扫描根目录；为空时脚本默认扫当前目录。

!`命令`        # 行内注入：Claude Code 先执行命令，再用输出替换这一行
```!            # 代码围栏注入：整块执行并替换

/tech-debt-scan

/tech-debt-scan ./src

帮我看看项目里欠了多少技术债，哪些 FIXME 最该先还？

## 技术债体检报告

共发现 7 处技术债标记：TODO×4、FIXME×2、HACK×1；高严重度 3 条。

| 严重度 | 债龄 | 文件:行号 | 作者 | 内容摘要 |
|--------|------|-----------|------|----------|
| 高 | 128天 | src/auth.py:42 | 张三 | FIXME 密码明文比对应换 bcrypt |
| 高 | 96天  | utils/cache.ts:11 | 李四 | HACK 临时绕过空指针，上线前必须修 |
| 低 | 30天  | api/order.go:8 | 王五 | TODO 加幂等校验 |
| ... | | | | |

### Top 3 必还债
1. **auth.py:42 密码明文比对**（FIXME / 128天）——已知安全缺陷且超期 4 个月，建议本周改用 bcrypt，并补一组对照测试。
2. **cache.ts:11 临时绕过**（HACK / 96天）——脆弱实现，建议定位空指针根因后删除该分支。
3. ... 

disable-model-invocation: true

mkdir ~/debt-demo && cd ~/debt-demo
git init -q && git config user.email "[email protected]" && git config user.name "demo"

cat > auth.py <<'EOF'
def login(pwd):
    # FIXME 明文比对密码，存在时序攻击风险，换 bcrypt
    return pwd == "admin"
    # TODO 记录失败次数，连续 5 次锁定账号
EOF

cat > cache.ts <<'EOF'
// HACK 这里直接吞掉了空值，先让 demo 跑起来，上线前必须修
export function get(k){ return store[k] ?? null }
// XXX 缓存过期策略待定
EOF

git add -A && git commit -qm "init demo with debt"

claude
# 进入交互后输入：
/tech-debt-scan

context: fork
agent: Explore

paths: "**/*.{py,ts,tsx,go,java,rs}"

flowchart TD
    U[用户: 帮我看看技术债] --> M{Claude 匹配 description?}
    M -->|匹配| L[加载 SKILL.md 正文]
    M -->|用户敲 /tech-debt-scan| L
    L --> S[替换变量: ${CLAUDE_SKILL_DIR}, $ARGUMENTS]
    S --> I[动态注入: 运行 scan_tech_debt.sh]
    I --> R[拿到原始管道分隔清单]
    R --> C[Claude 排序/归类/点名 Top3]
    C --> O[输出技术债体检报告]
    I -.失败.-> DBG[排查: chmod? git 仓库? 后缀?]