techdebt

技术债务扫描器

使用并行子 Agent 自动检测技术债务。设计用于在会话结束时运行，以便在上下文仍然清晰时发现问题。

快速开始

# Session end - scan changes since last commit (default)
/techdebt

# Deep scan - analyze entire codebase
/techdebt --deep

# Specific categories
/techdebt --duplicates    # Only duplication
/techdebt --security      # Only security issues
/techdebt --complexity    # Only complexity hotspots
/techdebt --deadcode      # Only dead code

# Auto-fix mode (interactive)
/techdebt --fix

架构

始终使用并行子 Agent进行快速分析：

Main Agent (orchestrator)
    │
    ├─> Subagent 1: Duplication Scanner
    ├─> Subagent 2: Security Scanner
    ├─> Subagent 3: Complexity Scanner
    └─> Subagent 4: Dead Code Scanner

    ↓ All run in parallel (2-15s depending on scope)

Main Agent: Consolidate findings → Rank by severity → Generate report

优点：

• 🚀 并行执行——所有扫描同时运行
• 🧹 保持主上下文整洁——分析工作不会造成干扰
• 💪 可扩展——可高效处理大型代码库
• 🎯 速度快——即使是小型差异也能从并行化中受益

工作流

第 1 步：确定范围

默认（无标志）：

• 扫描自上次提交以来更改的文件：git diff --name-only HEAD
• 快速的会话结束工作流（约 2-3 秒）
• 非常适合“收尾”场景

深度扫描（--deep 标志）：

• 扫描整个代码库
• 全面分析（中型项目约需 10-15 秒）
• 在重构或准备重大发布时使用

指定类别（例如 --duplicates）：

• 仅运行指定的扫描器
• 有针对性分析的最快选项

第 2 步：启动并行子 Agent

同时启动 4 个子 Agent（如果指定了类别，则启动部分 Agent）：

子 Agent 1：重复代码扫描器

• 任务：使用 AST 相似度查找重复代码块
• 工具：ast-grep、结构化搜索、令牌分析
• 输出：重复代码块列表及相似度评分

子 Agent 2：安全扫描器

• 任务：检测安全漏洞和反模式
• 检查项：硬编码机密、SQL 注入、XSS、不安全的加密
• 输出：安全问题及其严重性和修复建议

子 Agent 3：复杂度扫描器

• 任务：识别过于复杂的函数和方法
• 指标：圈复杂度、嵌套深度、函数长度
• 输出：复杂度热点及重构建议

子 Agent 4：死代码扫描器

• 任务：查找未使用的导入、变量和不可达代码
• 检查项：未使用的导入、死分支、孤立函数
• 输出：死代码列表及安全移除说明

子 Agent 指令模板：

Scan {scope} for {category} issues.

## Domain Knowledge
Before scanning, read the relevant skill for deeper patterns:
- Security scanner: Read skills/security-ops/references/owasp-top10-a01-a05.md and owasp-top10-a06-a10.md
- Complexity scanner: Read skills/refactor-ops/SKILL.md

Scope: {file_list or "entire codebase"}
Language: {detected from file extensions}
Focus: {category-specific patterns}

Output format:
- File path + line number
- Issue description
- Severity (P0-P3)
- Suggested fix (if available)

Use appropriate tools:
- Duplication: ast-grep for structural similarity
- Security: pattern matching + known vulnerability patterns
- Complexity: cyclomatic complexity calculation
- Dead Code: static analysis for unused symbols

第 3 步：汇总发现

主 Agent 收集所有子 Agent 的结果，并执行以下操作：

1. 去重——移除不同类别中的重复发现
2. 按严重性排序：
   • **P0（严重）：**安全漏洞、阻塞性问题
   • **P1（高）：**大量重复代码、高复杂度
   • **P2（中）：**少量重复代码、中等复杂度
   • **P3（低）：**死代码、样式问题
3. 按文件分组——按受影响的文件整理发现
4. 计算债务评分——衡量整体技术债务的指标

第 4 步：生成报告

创建可执行的报告，包含：

# Tech Debt Report

**Scope:** {X files changed | Entire codebase}
**Scan Time:** {duration}
**Debt Score:** {0-100, lower is better}

## Summary

| Category | Findings | P0 | P1 | P2 | P3 |
|----------|----------|----|----|----|----|
| Duplication | X | - | X | X | - |
| Security | X | X | - | - | - |
| Complexity | X | - | X | X | - |
| Dead Code | X | - | - | X | X |

## Critical Issues (P0)

### {file_path}:{line}
**Category:** {Security}
**Issue:** Hardcoded API key detected
**Impact:** Credential exposure risk
**Fix:** Move to environment variable

## High Priority (P1)

### {file_path}:{line}
**Category:** {Duplication}
**Issue:** 45-line block duplicated across 3 files
**Impact:** Maintenance burden, inconsistency risk
**Fix:** Extract to shared utility function

[... continue for all findings ...]

## Recommendations

1. Address all P0 issues before merge
2. Consider refactoring high-complexity functions
3. Remove dead code to reduce maintenance burden

## Auto-Fix Available

Run `/techdebt --fix` to interactively apply safe automated fixes.

第 5 步：自动修复模式（可选）

如果提供了 --fix 标志：

1. 识别安全的修复项：

   • 移除无用导入（安全）
   • 提取简单的重复代码（需要审核）
   • 修复格式问题（安全）

2. 交互式提示：

   Fix: Remove unused import 'requests' from utils.py:5
   [Y]es / [N]o / [A]ll / [Q]uit
   

3. 应用更改：

   • 编辑文件以应用已确认的修复
   • 显示更改的 git diff
   • 提示是否提交

安全规则：

• 绝不自动修复安全问题（需要人工审核）
• 绝不自动修复复杂度问题（需要设计决策）
• 仅在用户明确确认后自动修复

检测模式

重复代码

AST 相似度检测：

• 使用 ast-grep 进行结构化模式匹配
• 检测结构相似度超过 80% 的代码块
• 忽略无关紧要的差异（变量名、空白字符）

基于令牌的分析：

• 比较令牌序列，查找完全重复项
• 最低阈值：连续 6 行
• 将跨文件的相似重复项分组

阈值：

• P1：3 个或更多位置重复了 30 行或更多
• P2：2 个或更多位置重复了 15 行或更多
• P3：2 个位置重复了 6 行或更多

安全性

模式检测：

模式	严重级别	示例
硬编码密钥	P0	API_KEY = "sk-..."
SQL 注入风险	P0	f"SELECT * FROM users WHERE id={user_id}"
加密方式不安全	P0	hashlib.md5()、将 random.random() 用于令牌
路径遍历	P0	未验证就执行 open(user_input)
XSS 漏洞	P0	HTML 中未经转义的用户输入
使用 eval/exec	P1	eval(user_input)
密码强度弱	P2	硬编码的默认密码

语言特定检查：

• Python：使用 pickle、未使用 SafeLoader 的 yaml.load()
• JavaScript：eval()、使用用户数据的 innerHTML
• SQL：查询中使用字符串拼接

复杂度

指标：

指标	P1 阈值	P2 阈值
圈复杂度	>15	>10
函数长度	>100 行	>50 行
嵌套深度	>5 层	>4 层
参数数量	>7	>5

重构建议：

• 为长函数提取方法
• 参数过多时引入参数对象
• 使用守卫子句简化条件判断
• 拆分深度嵌套的逻辑

死代码

检测方法：

• 未使用的导入（语言特定的代码检查工具）
• 无法到达的代码（位于 return/break/continue 之后）
• 未使用的变量（已赋值但从未读取）
• 孤立函数（在代码库中从未调用）

安全移除标准：

• 未发现外部引用
• 不属于公共 API
• 不会被动态导入或调用

语言支持

第 1 级（全面支持）：

• Python：ast-grep、radon、pylint
• JavaScript/TypeScript：ast-grep、eslint、jscpd
• Go：gocyclo、golangci-lint
• Rust：clippy、cargo-audit

第 2 级（基本支持）：

• Java、C#、Ruby、PHP：仅支持基于模式的检测

语言检测：

• 根据文件扩展名自动检测
• 针对每种语言使用适当的工具
• 如果特定工具不可用，则回退到通用模式

集成模式

会话结束时自动运行

添加到工作流中：

## Session Wrap-Up Checklist

- [ ] Run `/techdebt` to scan changes
- [ ] Address any P0 issues found
- [ ] Create tasks for P1/P2 items
- [ ] Commit clean code

提交前钩子

创建 .claude/hooks/pre-commit.sh：

#!/bin/bash
# Auto-run tech debt scan before commits

echo "🔍 Scanning for tech debt..."
claude skill techdebt --quiet

if [ $? -eq 1 ]; then
  echo "❌ P0 issues detected. Fix before committing."
  exit 1
fi

echo "✅ No critical issues found"

CI/CD 集成

在拉取请求上运行深度扫描：

# .github/workflows/techdebt.yml
name: Tech Debt Check
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tech debt scan
        run: claude skill techdebt --deep --ci

高级用法

基线跟踪

跟踪债务随时间的变化：

# Initial baseline
/techdebt --deep --save-baseline

# Compare against baseline
/techdebt --compare-baseline
# Output: "Debt increased by 15% since baseline"

基线存储在 .claude/techdebt-baseline.json 中：

{
  "timestamp": "2026-02-03T10:00:00Z",
  "commit": "a28f0fb",
  "score": 42,
  "findings": {
    "duplication": 8,
    "security": 0,
    "complexity": 12,
    "deadcode": 5
  }
}

自定义模式

在 .claude/techdebt-rules.json 中添加项目专属模式：

{
  "security": [
    {
      "pattern": "TODO.*security",
      "severity": "P0",
      "message": "Security TODO must be resolved"
    }
  ],
  "complexity": {
    "cyclomatic_threshold": 12,
    "function_length_threshold": 80
  }
}

报告格式

/techdebt --format=json     # JSON output for tooling
/techdebt --format=markdown # Markdown report (default)
/techdebt --format=sarif    # SARIF for IDE integration

故障排除

问题：扫描超时

• 解决方案：仅对较小的模块使用 --deep，或延长超时时间
• 建议：将大型代码库拆分成较小的扫描块

问题：误报过多

• 解决方案：调整 .claude/techdebt-rules.json 中的阈值
• 建议：使用 --ignore-patterns 标志排除测试文件

问题：缺少依赖项（ast-grep 等）

• 解决方案：通过 npm install -g @ast-grep/cli 安装工具，或跳过该类别
• 后备方案：即使没有专用工具，基于模式的检测仍可运行

最佳实践

1. 在每次会话结束时运行 - 趁上下文仍然清晰时发现技术债务
2. 立即处理 P0 - 不要提交严重问题
3. 为 P1/P2 创建任务 - 在待办事项中跟踪技术债务
4. 使用基线观察趋势 - 监控技术债务随时间的累积情况
5. 在 CI/CD 中自动化 - 防止技术债务随代码合并
6. 培训团队 - 分享发现，讨论重构策略

参考资料

另请参阅：

• Anthropic's Agent Skills - 子 Agent 模式
• references/patterns.md - 特定语言的技术债务模式
• references/severity-guide.md - 如何评定发现项的严重级别