造注释补全Skill：裸函数秒变自解释

flowchart TD
    A[用户提问/命令] --> B{Tier 1: 仅读 frontmatter description}
    B -->|不相关| C[不加载, 零成本]
    B -->|相关| D[Tier 2: 加载 SKILL.md 正文]
    D --> E[执行任务]
    E -->|需要细规范| F[Tier 3: 按需加载 references/ 脚本]
    F --> E
    style B fill:#fef3c7
    style D fill:#dbeafe
    style F fill:#dcfce7

~/.claude/skills/comment-doctor/
├── SKILL.md                      # 入口：元数据 + 正文指令
├── scripts/
│   └── find_undocumented.py      # Tier 3：静态扫描脚本
└── references/
    └── docstring-styles.md       # Tier 3：各语言注释风格规范

mkdir -p ~/.claude/skills/comment-doctor/scripts
mkdir -p ~/.claude/skills/comment-doctor/references

---
name: comment-doctor
description: 扫描项目源代码，定位缺失文档注释的函数、方法与类，按目标语言规范（Python docstring、JSDoc、GoDoc、JavaDoc）生成准确的中文注释并写回文件。当用户要求"补全注释""给函数加文档""生成 docstring""让代码自解释"，或代码缺少文档时触发。
---

# Comment Doctor

## 何时使用
当用户希望为无注释的函数、方法、类补全文档注释时使用。语言涵盖 Python、JavaScript/TypeScript、Go、Java。

## 工作流程（务必按序）
1. **先扫描**：运行 `python3 ~/.claude/skills/comment-doctor/scripts/find_undocumented.py <目标路径>`，得到缺失注释的函数清单（JSON）。
2. **读上下文**：对清单中的每一项，读取该函数及其调用处的代码，理解真实行为，而非按函数名臆测。
3. **查规范**：按目标语言，参考 `references/docstring-styles.md` 中的格式样板生成注释。内容要准确反映实际逻辑（参数含义、返回值、副作用、抛出的异常）。
4. **写回文件**：用 Edit 工具把注释插入到函数定义正下方。每改完一个文件，向用户报告本次新增注释的函数数量。
5. **输出总结**：在会话末尾给出 Markdown 表格，列出已补全注释的文件与函数数。

## 边界（禁止行为）
- 不要修改函数体逻辑，只加注释。
- 不要生成显而易见的废话注释（如 `# 返回 a + b` 给 `def add(a, b): return a+b`）。如果函数确实简单，写一句总结即可，或主动跳过并说明。
- 不要为已经存在注释的函数重复添加。

#!/usr/bin/env python3
"""扫描源文件，输出缺失文档注释的函数/类清单（JSON）。
用法: python3 find_undocumented.py <path>
"""
import ast, json, sys, os

# 支持的扩展名 → 解析器（本脚本聚焦 Python；JS/TS 可用 tree-sitter 扩展）
SUPPORTED = {".py": "python"}
SKIP_DIRS = {"node_modules", ".git", "venv", ".venv", "__pycache__", "dist", "build"}

def find_py(path):
    """解析单个 Python 文件，返回缺 docstring 的函数/类。"""
    src = open(path, encoding="utf-8").read()
    tree = ast.parse(src)
    out = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            if not ast.get_docstring(node):
                kind = "class" if isinstance(node, ast.ClassDef) else "function"
                out.append({"type": kind, "name": node.name,
                            "line": node.lineno, "file": path})
    return out

def walk(root):
    results = []
    for dp, dn, fn in os.walk(root):
        dn[:] = [d for d in dn if d not in SKIP_DIRS]   # 原地剪枝
        for f in fn:
            p = os.path.join(dp, f)
            if os.path.splitext(f)[1] in SUPPORTED:
                try:
                    results += find_py(p)
                except SyntaxError:
                    pass   # 跳过无法解析的文件
    return results

if __name__ == "__main__":
    root = sys.argv[1] if len(sys.argv) > 1 else "."
    print(json.dumps(walk(root), ensure_ascii=False, indent=2))

[
  {"type": "function", "name": "calculate_tax", "line": 12, "file": "./billing/calc.py"},
  {"type": "class", "name": "OrderRepository", "line": 40, "file": "./billing/repo.py"}
]

# 文档注释风格规范

## Python（Google 风格 docstring）
"""计算含税金额。

Args:
    price: 不含税单价。
    rate: 税率，0~1 之间的小数。

Returns:
    含税后的总价。

Raises:
    ValueError: rate 超出 [0, 1] 时抛出。
"""

## JavaScript / TypeScript（JSDoc）
/**
 * 计算含税金额。
 * @param {number} price - 不含税单价。
 * @param {number} rate - 税率，0~1。
 * @returns {number} 含税总价。
 */

## Go（GoDoc，注释紧贴声明、以名字开头）
// CalculateTax 计算含税金额。price 为不含税单价，rate 为 0~1 的税率。
func CalculateTax(price float64, rate float64) float64 { ... }

## Java（JavaDoc）
/** 计算含税金额。
 * @param price 不含税单价
 * @param rate 税率，0~1
 * @return 含税总价
 */

# ~/demo_shop/billing.py
def apply_discount(price, pct):
    if pct < 0 or pct > 1:
        raise ValueError("pct 必须在 0~1")
    return price * (1 - pct)

class Cart:
    def add(self, sku, qty=1):
        self.items[sku] = self.items.get(sku, 0) + qty

def apply_discount(price, pct):
    """对原价施加折扣。

    Args:
        price: 原价。
        pct: 折扣比例，0~1 之间（0.2 表示打 8 折）。

    Returns:
        折扣后的价格。

    Raises:
        ValueError: pct 不在 [0, 1] 区间时抛出。
    """
    if pct < 0 or pct > 1:
        raise ValueError("pct 必须在 0~1")
    return price * (1 - pct)

class Cart:
    """购物车，维护 SKU 到数量的映射。"""

    def add(self, sku, qty=1):
        """向购物车加入商品，已存在则累加数量。

        Args:
            sku: 商品唯一标识。
            qty: 本次添加数量，默认 1。
        """
        self.items[sku] = self.items.get(sku, 0) + qty

flowchart LR
    U[真实使用] --> T[触发记录]
    T --> M{该触发时触发?}
    M -->|漏触发| D1[在 description 补同义短语]
    M -->|误触发| D2[收窄 description 场景]
    M -->|准| OK[保持]
    D1 --> U
    D2 --> U
    OK --> U