# 个人级 Skill：全局生效，跨项目可用
mkdir -p ~/.claude/skills/docs-drift-detector/{scripts,references}

# 项目级 Skill：随 git 分发给团队
# mkdir -p .claude/skills/docs-drift-detector/{scripts,references}

docs-drift-detector/
├── SKILL.md                      # 必须：核心指令（阶段2加载）
├── scripts/
│   └── drift_check.py            # 确定性扫描器（阶段3，仅输出进上下文）
└── references/
    ├── extraction-rules.md       # 按需加载：各语言符号抽取规则
    └── output-format.md          # 按需加载：报告 schema 说明

---
name: docs-drift-detector
description: Detect documentation drift by comparing README/docs against actual source code to find symbols documented but no longer implemented (stale docs) and symbols implemented but missing from docs (gaps). Use when the user asks to check if docs are up to date, verify README accuracy, find outdated documentation, audit doc-vs-code consistency, or says "文档漂移"/"文档和代码不一致"/"检查 README 是否过期". Runs a bundled Python scanner and emits a structured drift report.
allowed-tools:
  - Read
  - Grep
  - Bash
---

# Docs Drift Detector

检查项目文档是否仍然与真实源代码一致。

## 何时使用
当用户想验证 README/docs 准确性、或寻找文档与代码的漂移时运行本 Skill。

## 工作流
1. 确认文档文件（默认 `README.md`）与源码根目录（默认 `.`）。
2. 运行扫描器——源码不进上下文，只有报告输出进上下文：
   `python3 scripts/drift_check.py --doc README.md --src src`
3. 阅读报告中 "Stale docs"（文档写了但代码没有）与 "Undocumented"（代码有但文档没提）。
4. 对每个过期符号，用 Grep 在代码库中确认：是被改名、删除，还是从未存在？给出具体的文档修改建议。
5. 用简短表格汇总漂移；编辑文档前先征求用户同意。

## 规则
- 以扫描器输出作为"代码中已定义"的事实依据，不要凭记忆猜符号。
- 各语言抽取规则见 `references/extraction-rules.md`；报告 schema 见 `references/output-format.md`。
- 非零退出码表示发现漂移，可直接用于 CI。

#!/usr/bin/env python3
# scripts/drift_check.py
"""Deterministic docs-drift scanner.
NOTE: This source code never enters Claude's context window —
only this script's stdout (the report) does. That is progressive disclosure."""
import re, sys, json, argparse
from pathlib import Path

# 每种语言"定义符号"的正则（按需扩展，详见 references/extraction-rules.md）
LANG_PATTERNS = {
    ".py": r"^\s*(?:def|class)\s+([A-Za-z_][A-Za-z0-9_]*)",
    ".ts": r"^\s*(?:export\s+)?(?:function|class|const|interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)",
    ".js": r"^\s*(?:export\s+)?(?:function|class|const)\s+([A-Za-z_$][A-Za-z0-9_$]*)",
    ".go": r"^\s*func\s+(?:\([^)]*\)\s+)?([A-Za-z_][A-Za-z0-9_]*)",
}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", "vendor", "__pycache__"}

def collect_definitions(roots):
    defs = {}  # name -> [files]
    for root in roots:
        for path in Path(root).rglob("*"):
            if not path.is_file() or path.suffix not in LANG_PATTERNS:
                continue
            if any(seg in path.parts for seg in SKIP_DIRS):
                continue
            try:
                text = path.read_text(encoding="utf-8", errors="ignore")
            except OSError:
                continue
            for m in re.finditer(LANG_PATTERNS[path.suffix], text, re.M):
                defs.setdefault(m.group(1), []).append(str(path))
    return defs

def collect_documented(doc_path):
    """文档声称存在的符号：反引号代码片段 + 围栏代码块里的签名。"""
    text = Path(doc_path).read_text(encoding="utf-8", errors="ignore")
    names = set()
    for span in re.findall(r"`([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?)`", text):
        names.add(span.split(".")[-1])  # 取 a.b.c 的最后一段
    for block in re.findall(r"```[a-z]*\n(.*?)```", text, re.S):
        for line in block.splitlines():
            m = re.search(r"\b(?:def|function|class|const|func)\s+([A-Za-z_][A-Za-z0-9_]*)", line)
            if m:
                names.add(m.group(1))
    return names

def main():
    ap = argparse.ArgumentParser(description="Docs drift detector")
    ap.add_argument("--doc", default="README.md")
    ap.add_argument("--src", nargs="*", default=["."])
    ap.add_argument("--json", action="store_true")
    a = ap.parse_args()

    if not Path(a.doc).is_file():
        print(f"ERROR: doc not found: {a.doc}", file=sys.stderr); sys.exit(2)

    defs = collect_definitions(a.src)
    documented, defined = collect_documented(a.doc), set(defs)
    stale = sorted(documented - defined)   # 文档有、代码无 → 过期文档
    gaps  = sorted(defined - documented)   # 代码有、文档无 → 文档缺口
    matched = sorted(documented & defined)

    if a.json:
        print(json.dumps({"stale_docs": stale, "undocumented": gaps,
                          "matched": matched, "total_defined": len(defined),
                          "total_documented": len(documented)}, indent=2)); return

    print(f"# Docs Drift Report — {a.doc}\n")
    print(f"Documented symbols : {len(documented)}")
    print(f"Defined in code    : {len(defined)}")
    print(f"Matched            : {len(matched)}\n")
    print(f"## Stale docs (documented but not in code): {len(stale)}")
    for s in stale: print(f"  - {s}")
    print(f"\n## Undocumented (in code but not in docs): {len(gaps)}")
    for g in gaps[:50]: print(f"  - {g}")
    if len(gaps) > 50: print(f"  ... ({len(gaps)-50} more)")
    sys.exit(1 if stale else 0)   # 发现过期文档 → 非零退出码

if __name__ == "__main__":
    main()

# 符号抽取规则

## 源码侧（"已定义"）
| 语言 | 匹配 | 示例 |
|------|------|------|
| Python | `def`/`class` 名 | `def create_user` → create_user |
| TS/JS | `function`/`class`/`const`/`interface`（含 `export`） | `export const MAX` → MAX |
| Go | `func` 名（跳过接收者） | `func (s *S) Run` → Run |

跳过目录：node_modules, .git, dist, build, vendor, __pycache__。

## 文档侧（"已记录"）
- 反引号代码片段：`createUser`、`auth.login()`（取最后一段）。
- 围栏代码块内形如 `def/function/class/const/func X` 的签名。

# 报告 Schema
- Stale docs（过期）：文档提到、代码中已不存在 → 优先修，可能误导用户。
- Undocumented（缺口）：代码存在、文档未提 → 次优先，按公开 API 重要性筛选。
- Matched：一致，无需处理。
--json 输出供 CI 解析；文本输出供人读。

mkdir demo && cd demo

cat > README.md <<'EOF'
# Demo API
## 端点
- `createUser(name)` 创建用户
- `deleteUser(id)` 删除用户
- `legacyAuth()` 兼容旧登录
EOF

cat > app.py <<'EOF'
def createUser(name):
    pass

def updateUser(name, email):
    pass
EOF

python3 ~/.claude/skills/docs-drift-detector/scripts/drift_check.py \
  --doc README.md --src .
echo "exit=$?"

# Docs Drift Report — README.md

Documented symbols : 4
Defined in code    : 2
Matched            : 1

## Stale docs (documented but not in code): 3
  - deleteUser
  - legacyAuth
  - Demo        # 来自标题里的反引号无关词，属噪声，见下文优化
## Undocumented (in code but not in docs): 1
  - updateUser
exit=1

> 帮我检查这个项目的 README 是否过期

flowchart TD
    A[会话启动] --> B[阶段1: 扫描 ~/.claude/skills 与 .claude/skills]
    B --> C[仅加载 name+description<br/>~30-50 tokens/个]
    C --> D{模型判定: 用户请求<br/>与某 Skill 相关?}
    D -- 否 --> E[该 Skill 保持休眠<br/>零额外成本]
    D -- 是 docs-drift --> F[阶段2: 加载 docs-drift-detector/SKILL.md]
    F --> G[运行 scripts/drift_check.py]
    G --> H[阶段3: 仅脚本 stdout 进入上下文<br/>源码/脚本本身不进]
    H --> I[读 references/extraction-rules.md<br/>仅当需解释某结果]
    I --> J[Grep 逐个核实过期符号]
    J --> K[输出漂移表格 + 文档修改建议]

    style C fill:#e8f5e9
    style H fill:#fff3e0
    style K fill:#e3f2fd