从零构建一个"测试骨架生成 Skill"：让 Claude 自动产出单测样板

mkdir -p .claude/skills/test-scaffold/{scripts,references}
cd .claude/skills/test-scaffold

.claude/skills/test-scaffold/
├── SKILL.md                 # 必需：核心说明书
├── scripts/
│   └── extract_symbols.py   # 用 AST 提取函数/方法签名
└── references/
    ├── jest_template.md     # JS 端测试模板（按需加载）
    └── pytest_template.md   # Python 端测试模板（按需加载）

---
name: test-scaffold
description: 为 Python/JavaScript 源文件生成单元测试骨架。扫描指定目录，提取函数与方法签名，输出对应语言的测试样板（pytest / Jest）。当用户要求"生成测试""补单测""写测试样板""为 xxx 模块补测试"或处理缺少测试覆盖的代码时触发。支持指定框架与目标目录。
---

# 测试骨架生成 Skill

## 何时使用
当用户希望为新写或已有的函数/类快速产出可运行的单测样板时使用。

## 工作流程
1. 运行 `python scripts/extract_symbols.py <源文件或目录> --lang python` 得到符号清单（JSON）。
2. 根据目标语言读取对应模板：Python 读 `references/pytest_template.md`，JS 读 `references/jest_template.md`。
3. 把每个公共函数/方法渲染成一个测试用例：一个正常路径、一个边界值、一个异常路径。
4. 写入 `tests/test_<模块名>.py`（或 `.test.<name>.js`），避免覆盖已有文件。
5. 运行生成的测试，确认能 collect 通过（即使断言待补）。

## 约定
- 跳过以 `_` 开头的私有符号，除非用户明确要求。
- 不修改被测源码，只新增测试文件。
- 若目标测试文件已存在，在其末尾追加，并打印提示。

#!/usr/bin/env python3
# extract_symbols.py — 从 Python 源文件提取公共函数/方法签名
import ast, json, sys, argparse
from pathlib import Path

def is_public(name: str) -> bool:
    return not name.startswith("_")

def extract(path: Path) -> list[dict]:
    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
    symbols = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            if not is_public(node.name):
                continue
            args = [a.arg for a in node.args.args]
            ret = ast.unparse(node.returns) if node.returns else None
            symbols.append({
                "name": node.name,
                "qualname": node.name,
                "args": args,
                "returns": ret,
                "is_method": isinstance(getattr(node, "parent", None), ast.ClassDef),
                "line": node.lineno,
            })
        elif isinstance(node, ast.ClassDef) and is_public(node.name):
            for item in node.body:
                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and is_public(item.name):
                    symbols.append({
                        "name": item.name,
                        "qualname": f"{node.name}.{item.name}",
                        "args": [a.arg for a in item.args.args],
                        "returns": ast.unparse(item.returns) if item.returns else None,
                        "is_method": True,
                        "class": node.name,
                        "line": item.lineno,
                    })
    return symbols

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("target", help="源文件或目录")
    ap.add_argument("--lang", default="python")
    args = ap.parse_args()

    root = Path(args.target)
    files = [root] if root.is_file() else list(root.rglob("*.py"))
    files = [f for f in files if "test_" not in f.name]  # 跳过已有测试
    out = {}
    for f in files:
        try:
            syms = extract(f)
            if syms:
                out[str(f)] = syms
        except SyntaxError as e:
            print(f"[skip] {f}: {e}", file=sys.stderr)
    print(json.dumps(out, indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()

{
  "src/pricing.py": [
    {"name": "compute_total", "qualname": "compute_total", "args": ["items", "tax_rate"], "returns": "float", "is_method": false, "line": 12},
    {"name": "apply_discount", "qualname": "Cart.apply_discount", "args": ["self", "code"], "returns": null, "is_method": true, "class": "Cart", "line": 40}
  ]
}

# pytest 测试样板渲染规则

对每个符号 `s`，生成：

```python
import pytest
from <module> import <qualname 的类/函数>

def test_<name>_happy_path():
    # 正常路径：给出合法输入，断言返回值
    result = <call with sensible defaults>
    assert result is not None

def test_<name>_boundary():
    # 边界值：空集合 / 0 / 极值
    pass

def test_<name>_error():
    # 异常路径：非法输入应抛出预期异常
    with pytest.raises(Exception):
        <call with bad input>

`references/jest_template.md` 同理，给出 `describe/it` 骨架。

**预期结果**：`SKILL.md` 保持精简（指南建议 < 500 行），大段模板按需加载，token 占用最小化。

**常见问题**：
- **模板要不要内联进 SKILL.md？** 短模板可以内联；超过几十行或存在多语言分支时，外置成引用文件更划算——这正是渐进式披露的价值。
- **模型不主动读 references/**：在 `SKILL.md` 的工作流里**显式写明**"读取 `references/pytest_template.md`"，Claude 才会按指令加载。说明书要像给新人的操作手册，每一步可执行、可验证。

## 第五步：注册、触发与调试

1. **确认放置位置**：项目级 `.claude/skills/test-scaffold/SKILL.md`。
2. **重启 Claude Code**：发现扫描只在初始化进行，改完文件必须重启。
3. **验证索引**：用一句贴近触发词的自然语言试触发——

   > 帮我为 `src/pricing.py` 补一份 pytest 测试样板。

   预期 Claude 读取 Skill → 运行 `extract_symbols.py` → 读模板 → 生成 `tests/test_pricing.py` → 跑 `pytest --collect-only` 确认可收集。

4. **不触发时的排查清单**（生产环境高频坑）：
   - `description` 是否同时含"做什么"和"何时用"？✓
   - 是否含用户真实会用到的词（"补单测""测试样板"）？✓
   - 改动后是否重启？✓
   - 实在不行，**显式点名**：`用 test-scaffold 这个 skill 给 pricing.py 生成测试`——这是最可靠的兜底。

5. **可选：收紧权限**。这个 Skill 只读源码、只写测试目录，可在 frontmatter 加：

   ```yaml
   allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep"]
   ```
   作为纵深防御（但别只依赖它，仍需审阅脚本本身）。

## 实战案例：为一个订单计价模块生成测试

假设 `src/pricing.py`：

```python
def compute_total(items: list[float], tax_rate: float) -> float:
    return sum(items) * (1 + tax_rate)

class Cart:
    def __init__(self):
        self.items: list[float] = []
    def add(self, price: float) -> None:
        self.items.append(price)
    def apply_discount(self, code: str) -> float:
        # 业务规则略
        ...

import pytest
from src.pricing import compute_total, Cart

def test_compute_total_happy_path():
    result = compute_total([10.0, 20.0], 0.1)
    assert result == pytest.approx(33.0)

def test_compute_total_boundary():
    assert compute_total([], 0.1) == 0.0   # 空集合

def test_compute_total_error():
    with pytest.raises(TypeError):
        compute_total(None, 0.1)

class TestCart:
    def setup_method(self):
        self.cart = Cart()

    def test_apply_discount_happy_path(self):
        # TODO: 填入合法折扣码与预期金额
        assert isinstance(self.cart.apply_discount("VIP10"), float)

flowchart TD
    A[会话启动] --> B[扫描 .claude/skills/*]
    B --> C[仅加载 name+description\n约30-50 tokens/Skill]
    C --> D{用户: 给 pricing.py 补测试}
    D --> E[语义匹配命中 test-scaffold]
    E --> F[加载 SKILL.md 正文]
    F --> G[运行 scripts/extract_symbols.py]
    G --> H[脚本输出 JSON 符号清单\n脚本源码不进上下文]
    H --> I[按需读取 references/pytest_template.md]
    I --> J[渲染并写入 tests/test_pricing.py]
    J --> K[pytest --collect-only 验证]
    K --> L[7 tests collected ✓]