Claude Code Skills 开发实战：造一个死代码侦探 Skill

flowchart LR
    A["用户提问<br/>'帮我找死代码'"] --> B{"Claude 读取<br/>description 判断相关性"}
    B -->|相关| C["加载 SKILL.md 正文<br/>进入上下文"]
    B -->|不相关| Z["不加载<br/>零 token 成本"]
    C --> D["按正文执行流程"]
    D --> E["调用 scripts/analyze.py"]
    E --> F["产出报告供人决策"]

dead-code-detect/
├── SKILL.md              # 入口（必需，保持精简，<500 行）
├── references/
│   └── detection-rules.md # 详细检测规则（按需加载，不占常用上下文）
├── scripts/
│   └── analyze.py         # 真正干活的调用图分析器
└── examples/
    └── sample-report.md   # 期望的报告格式样例

# 个人级：所有项目可用
mkdir -p ~/.claude/skills/dead-code-detect/{references,scripts,examples}

# 或项目级：仅当前项目可用（推荐先在项目里试）
mkdir -p .claude/skills/dead-code-detect/{references,scripts,examples}

---
description: Scans a Python project to find dead code — functions/methods never called and imports never used — and produces a risk-ranked report. Use when the user asks to find dead code, unused functions, orphaned imports, or wants to clean up / slim down the codebase.
allowed-tools: Bash(python3 *) Bash(pytest *) Read Grep Glob
paths: "**/*.py"
argument-hint: "[path-to-scan]"
---

## Your task

You are a dead-code detective. You DETECT and REPORT — you never delete code on your own.

Scan the target path (default: the current project root) and produce a dead-code report.

## Workflow

1. Run the analyzer. Execute the bundled script and capture its JSON:
   ```!bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/analyze.py" "${1:-${CLAUDE_PROJECT_DIR}}"
   ```
   - `$1` is the first user argument (a path). If absent, default to the project root.
   - `${CLAUDE_SKILL_DIR}` always points to this skill's own directory.
   - The `!` prefix makes Claude Code run the command and inline its output HERE before you read the rest.

2. Interpret the output. The script prints JSON with two lists: `unreferenced_defs` and `unused_imports`. For each candidate, check for false positives (see references/detection-rules.md):
   - Is it a test subject referenced only by test runners / fixtures?
   - Is it exported in `__all__` or re-exported (a public API entry)?
   - Is it referenced via a string, getattr, or dynamic dispatch the regex missed?

3. Write the report. Produce a Markdown report with this structure:
   - A summary count table.
   - A table of unreferenced definitions: `file:line`, name, type, confidence (high/medium/low), and a one-line reason.
   - A table of unused imports.
   - A "Do not touch" section listing anything that LOOKS dead but is actually live (entry points, __all__ exports, framework hooks).

4. Recommend next steps: suggest a branch + per-item confirmation before any removal. Do NOT remove anything.

## Safety rules (non-negotiable)

- NEVER delete files or symbols. Report only.
- ALWAYS treat `if __name__ == "__main__"`, CLI entry points, and `__all__` members as LIVE.
- ALWAYS treat names that appear only in strings, `getattr`, or config as POSSIBLY LIVE (confidence = low).
- When in doubt, keep it. False negatives beat false positives.

## Reference

For the full detection rules and false-positive patterns, load [references/detection-rules.md](references/detection-rules.md).
For an example report, see [examples/sample-report.md](examples/sample-report.md).

#!/usr/bin/env python3
"""Dead-code analyzer for Python projects.
Strategy: build a name->definition map, then count project-wide references.
Zero-reference names (excluding their own def site) are dead-code candidates.
"""
import ast
import json
import sys
from pathlib import Path
from collections import defaultdict


def collect_definitions(root: Path):
    """Return {fully_qualified_name: (file, lineno, kind)}."""
    defs = {}
    for py in root.rglob("*.py"):
        if any(p in py.parts for p in ("venv", ".venv", "node_modules", "__pycache__", ".git")):
            continue
        try:
            tree = ast.parse(py.read_text(encoding="utf-8"), filename=str(py))
        except SyntaxError:
            continue
        for node in ast.walk(tree):
            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                defs[node.name] = (str(py), node.lineno, "function")
            elif isinstance(node, ast.ClassDef):
                defs[node.name] = (str(py), node.lineno, "class")
    return defs


def count_references(root: Path, names: set):
    """Count how many times each name token appears across the project."""
    refs = defaultdict(int)
    for py in root.rglob("*.py"):
        if any(p in py.parts for p in ("venv", ".venv", "node_modules", "__pycache__", ".git")):
            continue
        try:
            tokens = set(ast.walk(ast.parse(py.read_text(encoding="utf-8"))))
        except SyntaxError:
            continue
        # crude but effective: count name occurrences as attribute/id nodes
        text = py.read_text(encoding="utf-8")
        for name in names:
            refs[name] += text.count(name)
    return refs


def find_unused_imports(root: Path):
    """Find 'import X' / 'from m import Y' where the imported name is never used."""
    unused = []
    for py in root.rglob("*.py"):
        if any(p in py.parts for p in ("venv", ".venv", "node_modules", "__pycache__", ".git")):
            continue
        try:
            tree = ast.parse(py.read_text(encoding="utf-8"), filename=str(py))
        except SyntaxError:
            continue
        imported = set()
        for node in ast.walk(tree):
            if isinstance(node, ast.Import):
                for alias in node.names:
                    imported.add(alias.asname or alias.name.split(".")[0])
            elif isinstance(node, ast.ImportFrom):
                for alias in node.names:
                    if alias.name != "*":
                        imported.add(alias.asname or alias.name)
        used = {n.id for n in ast.walk(tree) if isinstance(n, ast.Name)}
        for name in imported:
            if name not in used:
                unused.append({"file": str(py), "line": 0, "name": name})
    return unused


def main():
    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
    defs = collect_definitions(root)
    names = set(defs.keys())
    refs = count_references(root, names)

    unreferenced = []
    for name, (file, line, kind) in defs.items():
        # a definition references its own name once at the def site
        if refs.get(name, 0) <= 1 and not name.startswith("__"):
            unreferenced.append({"file": file, "line": line, "name": name, "kind": kind})

    print(json.dumps({
        "root": str(root),
        "unreferenced_defs": unreferenced,
        "unused_imports": find_unused_imports(root),
    }, indent=2))


if __name__ == "__main__":
    main()

{
  "root": "/home/me/demo-project",
  "unreferenced_defs": [
    {"file": "/home/me/demo-project/utils/legacy.py", "line": 12, "name": "old_formatter", "kind": "function"},
    {"file": "/home/me/demo-project/services/v1.py", "line": 8, "name": "V1Client", "kind": "class"}
  ],
  "unused_imports": [
    {"file": "/home/me/demo-project/main.py", "line": 0, "name": "os"}
  ]
}

# Detection Rules & False-Positive Patterns

## High confidence (likely dead)
- Private helper (`_foo`) referenced nowhere outside its own module
- Standalone function never imported or called project-wide

## Medium confidence
- Public method on a class whose class itself is unreferenced
- Functions in modules marked deprecated

## Low confidence / DO NOT FLAG as dead
- Names in `__all__` (public API surface)
- `if __name__ == "__main__"` entry points
- CLI command handlers (Click/Typer/argparse targets)
- Framework hooks: Django `models.py` classes, FastAPI route handlers,
  pytest fixtures, Celery tasks, SQLAlchemy models
- Names appearing in strings, configs, or `getattr()` (dynamic dispatch)

# Dead Code Report — demo-project

| Category | Count |
|----------|-------|
| Unreferenced definitions | 2 |
| Unused imports | 1 |

## Unreferenced definitions
| Location | Name | Type | Confidence | Reason |
|----------|------|------|-----------|--------|
| utils/legacy.py:12 | old_formatter | function | high | no project-wide references |
| services/v1.py:8 | V1Client | class | medium | class unreferenced; verify not re-exported |

## Unused imports
| Location | Name |
|----------|------|
| main.py | os |

## Do not touch
- `cli.py:run` — Click entry point, appears live

mkdir -p demo-project/{utils,services} && cd demo-project
cat > main.py <<'EOF'
import os  # 故意不用的导入
from utils.calc import add
print(add(1, 2))
EOF
cat > utils/calc.py <<'EOF'
def add(a, b):
    return a + b

def old_formatter(x):   # 从未被调用 —— 死代码
    return f"[{x}]"
EOF
cat > services/v1.py <<'EOF'
class V1Client:          # 整个类无人引用 —— 死代码
    def fetch(self):
        return "v1"
EOF

扫一下这个项目，找找哪些代码是死代码

flowchart TD
    A["analyze.py 收集所有 def/class"] --> B["统计每个名字全项目引用次数"]
    B --> C{"引用次数 <= 1 ?<br/>（排除定义自身）"}
    C -->|是| D["加入 unreferenced 候选"]
    C -->|否| E["判定为存活"]
    D --> F["Claude 二次甄别<br/>__all__ / 入口点 / 动态调度"]
    F --> G{"确认真死?"}
    G -->|是| H["报告 high 置信度"]
    G -->|存疑| I["报告 low / 列入 Do not touch"]
    H --> J["建议开分支逐项确认"]
    I --> J