AI-Coding-Insights: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

评估一个人对 AI 编码工具的使用情况：分析其本机的 Claude Code 会话记录，做深度分析，给出画像与改进建议。形态是 Claude Code plugin，由用户本人手动触发，产出本机报告。机器只给分析与证据，结论与奖惩判决在人。

常用命令

uv run pytest                                  # 全量测试
uv run pytest tests/test_window.py             # 单文件
uv run pytest tests/test_window.py::test_xxx   # 单用例

# 规则层手动调试（正常由 skill 编排调用）
uv run python -m ai_coding_insights scan --plugin-root . --emit-batches ~/.ai-coding-insights/run

# 指定来源（不传则跟触发环境走）
uv run python -m ai_coding_insights scan --source codex --emit-batches ~/.ai-coding-insights/run

# 安装器预演：看 playbook 会落到哪、有没有走降级版（不写盘）
uv run python -m ai_coding_insights install --print

零运行时依赖（纯 stdlib），dev 仅 pytest。

规则层共 8 个子命令，正常由 skill 编排调用，单独调试时也可直接跑（点到存在即可，参数以代码为准）。这份清单有测试守着（tests/test_skill_contract.py）：子命令名与条数必须与 cli.py 实际注册面一致，加了子命令不补这里即测试红。

• scan —— 扫描 / 窗口决策 / 分批 / 硬指标；--emit-batches 是编排主路径，四种输出形态互斥（--emit-batches / --profile-input / --json / 默认渲染 HTML）。
• init —— 交互配置向导，从本机会话来源勾选团队归属。
• verify-obs —— 校验 LLM 观测（obs）对批次的覆盖与 posture 计数完整性。
• render-profile —— 渲染最终画像 HTML 报告。
• auto-scan —— SessionEnd hook 后台自动评估（接线在 hooks/hooks.json；自带 lock 防重入 + 滚动日志，失败对用户静默）。
• reset —— 清空本机可再生产物（snapshots/ / reports/ / run/ / auto-scan.log）解除 30 天增量窗口闸门，并把今日写进 .auto-scan.lock（而非删它），压住 SessionEnd 的 auto-scan 当天抢先写新快照重新武装闸门——这是「reset 后重跑仍 too_soon」的根因修复。按白名单删、--dry-run 只预览，永不碰 config.toml 与会话原文。slash 入口 commands/reset.md。
• install —— 统一安装器：把单一真相源 playbook（skills/ai-coding-insights/SKILL.md）渲染并落到当前 harness 该放的位置。「装哪一家」与取数一样跟触发环境走（--source 可覆盖）；--print 只预演落点不写盘，目标已存在须 --force 才覆盖（用户可能改过自己的 playbook）。三个薄适配器在 installers.py，各配一条契约测试。无子代理能力的 harness 会装降级编排版，且降级状态写进报告 caveat——静默劣化是本项目定义的最危险故障。
• calibrate —— 手动调试命令：给出各指标分布与当前阈值的分位定位，不进 SKILL.md 编排、不产 HTML。两种取数来源：默认读 snapshots/ 里已脱敏的历史标量；--replay 则把本机会话按等长窗口切片重放成伪快照（--replay-window 默认对齐 WINDOW_FLOOR_DAYS，--replay-step 可滑动）。回放存在的理由：窗口闸门是「不足 30 天即 too_soon」，快照最快 30 天落一个，攒 20 个要 1.6 年——靠等快照校准阈值走不通，而档位闸门用的全是规则层硬指标，可直接从既有会话按同口径重算。切片长度必须与评估窗口同口径，改小即跨口径（阈值是按「一个 30 天窗口内的量级」定的）。回放不跑 git log、不跑 LLM，git 三键与姿态四档整键不放进伪快照（未测量 ≠ 0）。只给本机单人分布，不是人群分位；样本不足时逐层挂 caveat，且 n < 5 时压住「过门/未过门」的定性读法，只给数字。