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

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

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

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

步骤 2：生成并行子代理

同时启动 4 个子代理（如果指定了类别，则启动子集）：

子代理 1：重复代码扫描器

• 任务：使用 AST 相似性查找重复的代码块
• 工具：ast-grep、结构搜索、令牌分析
• 输出：带有相似性分数的重复代码块列表

子代理 2：安全扫描器

• 任务：检测安全漏洞和反模式
• 检查项：硬编码密钥、SQL 注入、XSS、不安全的加密
• 输出：带有严重性和修复指导的安全发现

子代理 3：复杂度扫描器

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

子代理 4：死代码扫描器

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

子代理指令模板：

Scan {scope} for {category} issues.

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：整合发现

主代理收集所有子代理的结果并：

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：30+ 行代码在 3+ 个位置重复
• P2：15+ 行代码在 2+ 个位置重复
• P3：6+ 行代码在 2 个位置重复

安全性

模式检测：

语言特定检查：

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

复杂度

指标：

重构建议：

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

死代码

检测方法：

• 未使用的导入（语言特定的 linter）
• 不可达代码（在 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

高级用法

基线跟踪

随时间跟踪债务：

# 初始基线
/techdebt --deep --save-baseline

# 与基线比较
/techdebt --compare-baseline
# 输出："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 输出用于工具集成
/techdebt --format=markdown # Markdown 报告（默认）
/techdebt --format=sarif    # SARIF 用于 IDE 集成

故障排除

问题：扫描超时

• 解决方案：仅对较小模块使用 --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 - 子代理模式
• references/patterns.md - 语言特定的债务模式
• references/severity-guide.md - 如何对发现进行排序

每周安装数

8

仓库

0xdarkmatter/claude-mods

GitHub 星标数

8

首次出现

Feb 5, 2026

安全审计

Gen Agent Trust HubPassSocketFailSnykPass

安装于

opencode8

gemini-cli8

replit7

claude-code7

codex7

github-copilot6

Workflow

Step 1: Determine Scope

Default (no flags):

• Scan files changed since last commit: git diff --name-only HEAD
• Fast session-end workflow (~2-3 seconds)
• Perfect for "wrap up" scenarios

Deep scan (--deep flag):

• Scan entire codebase
• Comprehensive analysis (~10-15 seconds for medium projects)
• Use when refactoring or preparing major releases

Specific category (e.g.,--duplicates):

• Run only specified scanner
• Fastest option for targeted analysis

Step 2: Spawn Parallel Subagents

Launch 4 subagents simultaneously (or subset if category specified):

Subagent 1: Duplication Scanner

• Task: Find duplicated code blocks using AST similarity
• Tools: ast-grep, structural search, token analysis
• Output: List of duplicate code blocks with similarity scores

Subagent 2: Security Scanner

• Task: Detect security vulnerabilities and anti-patterns
• Checks: Hardcoded secrets, SQL injection, XSS, insecure crypto
• Output: Security findings with severity and remediation guidance

Subagent 3: Complexity Scanner

• Task: Identify overly complex functions and methods
• Metrics: Cyclomatic complexity, nested depth, function length
• Output: Complexity hotspots with refactoring suggestions

Subagent 4: Dead Code Scanner

• Task: Find unused imports, variables, and unreachable code
• Checks: Unused imports, dead branches, orphaned functions
• Output: Dead code list with safe removal instructions

Subagent instructions template:

Scan {scope} for {category} issues.

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

Step 3: Consolidate Findings

Main agent collects results from all subagents and:

1. Deduplicate - Remove duplicate findings across categories
2. Rank by severity:
   • P0 (Critical): Security vulnerabilities, blocking issues
   • P1 (High): Major duplication, high complexity
   • P2 (Medium): Minor duplication, moderate complexity
   • P3 (Low): Dead code, style issues
3. Group by file - Organize findings by affected file
4. Calculate debt score - Overall technical debt metric

Step 4: Generate Report

Create actionable report with:

# 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.

Step 5: Auto-Fix Mode (Optional)

If --fix flag provided:

1. Identify safe fixes:

   • Dead import removal (safe)
   • Simple duplication extraction (review required)
   • Formatting fixes (safe)

2. Interactive prompts:

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

3. Apply changes:

   • Edit files with confirmed fixes
   • Show git diff of changes
   • Prompt for commit

Safety rules:

• Never auto-fix security issues (require manual review)
• Never auto-fix complexity (requires design decisions)
• Only auto-fix with explicit user confirmation

Detection Patterns

Duplication

AST Similarity Detection:

• Use ast-grep for structural pattern matching
• Detect code blocks with >80% structural similarity
• Ignore trivial differences (variable names, whitespace)

Token-based Analysis:

• Compare token sequences for exact duplicates
• Minimum threshold: 6 consecutive lines
• Group similar duplicates across files

Thresholds:

• P1: 30+ lines duplicated in 3+ locations
• P2: 15+ lines duplicated in 2+ locations
• P3: 6+ lines duplicated in 2 locations

Security

Pattern Detection:

Language-specific checks:

• Python: pickle usage, yaml.load() without SafeLoader
• JavaScript: eval(), innerHTML with user data
• SQL: String concatenation in queries

Complexity

Metrics:

Refactoring suggestions:

• Extract method for long functions
• Introduce parameter object for many parameters
• Simplify conditionals with guard clauses
• Break up deeply nested logic

Dead Code

Detection methods:

• Unused imports (language-specific linters)
• Unreachable code (after return/break/continue)
• Unused variables (written but never read)
• Orphaned functions (never called in codebase)

Safe removal criteria:

• No external references found
• Not part of public API
• Not dynamically imported/called

Language Support

Tier 1 (Full support):

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

Tier 2 (Basic support):

• Java, C#, Ruby, PHP: Pattern-based detection only

Language detection:

• Auto-detect from file extensions
• Use appropriate tools per language
• Fallback to universal patterns if specific tools unavailable

Integration Patterns

Session End Automation

Add to your workflow:

## Session Wrap-Up Checklist

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

Pre-Commit Hook

Create .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 Integration

Run deep scan on pull requests:

# .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

Advanced Usage

Baseline Tracking

Track debt over time:

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

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

Baseline stored in .claude/techdebt-baseline.json:

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

Custom Patterns

Add project-specific patterns in .claude/techdebt-rules.json:

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

Report Formats

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

Troubleshooting

Issue: Scan times out

• Solution: Use --deep only on smaller modules, or increase timeout
• Consider: Break large codebases into smaller scan chunks

Issue: Too many false positives

• Solution: Adjust thresholds in .claude/techdebt-rules.json
• Consider: Use --ignore-patterns flag to exclude test files

Issue: Missing dependencies (ast-grep, etc.)

• Solution: Install tools via npm install -g @ast-grep/cli or skip category
• Fallback: Pattern-based detection still works without specialized tools

Best Practices

1. Run at every session end - Catch debt while context is fresh
2. Address P0 immediately - Don't commit critical issues
3. Create tasks for P1/P2 - Track technical debt in backlog
4. Use baselines for trends - Monitor debt accumulation over time
5. Automate in CI/CD - Prevent debt from merging
6. Educate team - Share findings, discuss refactoring strategies

References

See also:

• Anthropic's Agent Skills - Subagent patterns
• references/patterns.md - Language-specific debt patterns
• references/severity-guide.md - How to rank findings

Weekly Installs

8

Repository

0xdarkmatter/claude-mods

GitHub Stars

8

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPassSocketFailSnykPass

Installed on

opencode8

gemini-cli8

replit7

claude-code7

codex7

github-copilot6

AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成

1,200 周安装