Claude Code Skills 开发实战：从零造一个配置漂移检测技能

.claude/skills/config-drift-detector/
├── SKILL.md            # 头部（必需）+ 正文（按需加载）
├── scripts/
│   └── drift_compare.py # 捆绑脚本：干活的实际代码
├── references/
│   └── drift-rules.md   # 深度参考资料：仅在追问"为什么"时加载
└── examples/
    └── sample-configs/  # 样例配置，便于自测

---
name: config-drift-detector
description: Compare config files across environments and report structural drift — missing keys, extra keys, value mismatches, and leftover placeholders. Use when onboarding to a project, debugging "works on my machine" issues caused by env differences, or gating a release before promotion. Examples: "compare .env and .env.example", "check config drift between staging and prod", "find missing env vars in production".
allowed-tools: Read, Bash(python3:*)
---

# Config Drift Detector

Compare two config files and surface structural drift. Works with `.env`
style (`KEY=VALUE`) and flat YAML. Output is a drift report you act on:
missing keys go to the user as a checklist; placeholder leftovers must be
filled before deploy.

## When to use

- A feature works in staging but fails in prod → compare their configs.
- Onboarding → diff `.env.example` against the team's real `.env`.
- Release gate → assert no drift between the target environments.

## How to run

\`\`\`bash
python3 scripts/drift_compare.py .env.example .env \
  --name-a example --name-b local --format json
\`\`\`

**Acting on output:** `only_in_a`/`only_in_b` → hand the missing-key list to
the user as a checklist; `placeholder_leftover` → block deploy until filled;
`value_differs` → confirm the intended value per environment.

Read `references/drift-rules.md` **only** when the user asks *why* a key is
flagged (placeholder regex, type-hint heuristics). Don't load it by default.

#!/usr/bin/env python3
"""drift_compare.py — 比较两个配置文件并报告结构漂移。

支持 .env 风格 (KEY=VALUE) 与扁平 YAML (key: value)。报告四类漂移：
  - 仅在 A / 仅在 B        (键只出现在一侧)
  - 取值不一致              (同名键，值不同)
  - 占位符未替换            (值仍是 <...> / changeme / example.com 等)
退出码：发现任意漂移返回 1，便于用作 CI 门禁；完全一致返回 0。
"""
import argparse, json, re, sys
from pathlib import Path

# 占位符特征：尖括号、未解析的 ${VAR、常见占位字面量
PLACEHOLDER_RE = re.compile(
    r"^(<[^>]+>|\$\{|changeme|todo|xxx|replace_me|example\.com|your_)",
    re.I,
)

def _strip_quotes(v: str) -> str:
    if len(v) >= 2 and v[0] == v[-1] and v[0] in ("'", '"'):
        return v[1:-1]
    return v

def parse_env(text: str) -> dict:
    cfg = {}
    for raw in text.splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        key, _, val = line.partition("=")
        cfg[key.strip()] = _strip_quotes(val.strip())
    return cfg

def parse_yaml_flat(text: str) -> dict:
    cfg = {}
    for raw in text.splitlines():
        line = raw.split("#", 1)[0].rstrip()
        if ":" not in line:
            continue
        key, _, val = line.partition(":")
        key, val = key.strip(), val.strip()
        if key and val:
            cfg[key] = _strip_quotes(val)
    return cfg

def load(path: str) -> dict:
    text = Path(path).read_text(encoding="utf-8", errors="replace")
    if path.endswith((".yml", ".yaml")):
        return parse_yaml_flat(text)
    return parse_env(text)

def drift(a: dict, b: dict, na: str, nb: str) -> dict:
    ka, kb = set(a), set(b)
    differs = [
        {"key": k, na: a[k], nb: b[k]}
        for k in sorted(ka & kb) if a[k] != b[k]
    ]
    placeholders = [
        k for k in sorted(ka & kb)
        if PLACEHOLDER_RE.match(a[k]) or PLACEHOLDER_RE.match(b[k])
    ]
    return {
        "only_in_a": sorted(ka - kb),
        "only_in_b": sorted(kb - ka),
        "value_differs": differs,
        "placeholder_leftover": placeholders,
    }

def render_text(report: dict, na: str, nb: str) -> str:
    out = []
    if report["only_in_a"]:
        out.append(f"## 仅在 {na}（{nb} 缺失）")
        out += [f"  - {k}" for k in report["only_in_a"]]
    if report["only_in_b"]:
        out.append(f"## 仅在 {nb}（{na} 缺失）")
        out += [f"  - {k}" for k in report["only_in_b"]]
    if report["value_differs"]:
        out.append("## 取值不一致")
        for d in report["value_differs"]:
            out.append(f"  - {d['key']}: {na}={d[na]!r}  vs  {nb}={d[nb]!r}")
    if report["placeholder_leftover"]:
        out.append("## 占位符未替换（疑似忘记配置）")
        out += [f"  - {k}" for k in report["placeholder_leftover"]]
    if not out:
        out.append("✓ 无漂移：两个文件结构与取值完全一致。")
    return "\n".join(out)

def main():
    p = argparse.ArgumentParser(description="比较配置文件并报告结构漂移")
    p.add_argument("file_a")
    p.add_argument("file_b")
    p.add_argument("--name-a", default="A")
    p.add_argument("--name-b", default="B")
    p.add_argument("--format", choices=["text", "json"], default="text")
    args = p.parse_args()

    a, b = load(args.file_a), load(args.file_b)
    report = drift(a, b, args.name_a, args.name_b)

    if args.format == "json":
        print(json.dumps(report, ensure_ascii=False, indent=2))
    else:
        print(render_text(report, args.name_a, args.name_b))

    has_drift = any([report["only_in_a"], report["only_in_b"],
                     report["value_differs"], report["placeholder_leftover"]])
    sys.exit(1 if has_drift else 0)

if __name__ == "__main__":
    main()

DATABASE_URL=postgres://localhost/app
REDIS_URL=redis://localhost:6379
PORT=3000
SECRET_KEY=<replace-me>
FEATURE_FLAG_NEW_UI=false

DATABASE_URL=postgres://localhost/app
PORT=8080
SECRET_KEY=changeme
API_TIMEOUT=30

python3 .claude/skills/config-drift-detector/scripts/drift_compare.py \
  .claude/skills/config-drift-detector/examples/sample-configs/.env.example \
  .claude/skills/config-drift-detector/examples/sample-configs/.env \
  --name-a example --name-b local

## 仅在 example（local 缺失）
  - FEATURE_FLAG_NEW_UI
  - REDIS_URL
## 仅在 local（example 缺失）
  - API_TIMEOUT
## 取值不一致
  - PORT: example='3000'  vs  local='8080'
## 占位符未替换（疑似忘记配置）
  - SECRET_KEY

# Drift Detection Rules（按需加载）

## 什么算漂移
1. **缺失键** — 只出现在一侧。
2. **取值不一致** — 同名键、非占位符值不同。
3. **占位符残留** — 值命中占位符正则。

## 占位符正则
命中以 `<...>` 开头、未解析的 `${VAR`、或字面量
changeme / todo / xxx / replace_me / example.com / your_（不区分大小写）。

## 类型提示（建议性）
两文件共享某键，但一侧是数字另一侧是字符串时，
即便值还没"不一致"也优先标红——端口/超时类型错配是
"在我电脑上没问题"的头号元凶。

## 故意忽略的差异
- 仅空白差异
- 键的顺序
- 注释行

config/
├── base.env       # 公共默认值
├── staging.env    # 预发覆盖
└── prod.env       # 生产覆盖

# .github/workflows/config-gate.yml
name: Config Drift Gate
on: [pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check staging vs base
        run: |
          python3 .claude/skills/config-drift-detector/scripts/drift_compare.py \
            config/base.env config/staging.env \
            --name-a base --name-b staging --format json > staging-drift.json || true
      - name: Check prod vs base
        run: |
          python3 .claude/skills/config-drift-detector/scripts/drift_compare.py \
            config/base.env config/prod.env \
            --name-a base --name-b prod --format text

flowchart TD
    U["用户：检查配置漂移"] --> CC["Claude Code"]
    CC -->|"匹配 description 锚点"| LOAD["加载 SKILL.md 头部+正文"]
    LOAD --> ASK["确认两个配置文件路径"]
    ASK --> RUN["运行 drift_compare.py<br/>allowed-tools: Bash(python3:*)"]
    RUN --> OUT{"有漂移?"}
    OUT -->|"有"| RPT["输出四类漂移报告"]
    OUT -->|"无"| OK["✓ 一致，放行"]
    RPT --> DECIDE{"用户追问为什么?"}
    DECIDE -->|"是"| REF["按需读 references/drift-rules.md"]
    DECIDE -->|"否"| ACT["缺失补全 / 占位符替换 / 门禁拦截"]
    REF --> ACT