hs-data/.claude/commands/docs-check.md

---

description: 审计规格文档是否与代码现状一致(防漂移)—— 按"改动类型→文档"映射逐项查,报告漂移并修复

审计项目文档与代码现状的一致性,是 CLAUDE.md 规则 6(改动同步文档)的兜底:规则负责每次改动当场同步,本命令负责定期/发版前扫出漏网的漂移。

范围

• $ARGUMENTS 给了 git 范围(如 HEAD~10..HEAD 或某 commit)→ 只查这些改动波及的文档。
• 为空 → 全量审计文档集:README.md、apps/api/README.md、docs/01~docs/07(以及 CLAUDE.md 规则 6 的映射表自身是否仍准)。

映射(改了什么 → 查哪份)

改了什么	必须检查
接口/契约(端点、字段、校验)	docs/02 §5、docs/06、apps/api/README、apps/web/src/api/types.ts(+ packages/api-types)
取数/口径/表结构	docs/02 §6、docs/03
IA/导航/产品范围	docs/01、README 能力域表
UI 控件/文案/视觉/交互	docs/04
目录/模块/运行/部署架构	docs/07、docs/02 §10、README、infra

步骤

1. 看清现状:git log --oneline -15 + git diff --stat(或 $ARGUMENTS 范围),掌握近期改了哪些代码区域;据此圈定要查的文档。
2. 逐份对照:对每份相关文档,读文档 + 读对应代码/契约,逐条核对——文档里写的端点/字段/口径/默认值/控件文案/目录树/部署方式,与代码现状是否一致。覆盖面大时,可按文档区并行派 Explore 子代理,只回结论(漂移点 + 现状)。
3. 产出漂移清单:每条 文档:段/行 — 写的是 X,现状是 Y — 建议改 Z。无漂移就明说"未发现漂移",不要硬凑。
4. 修复:逐条外科手术式改掉(只碰过期处,不顺手重写);改完按规则 5 记一条 CHANGELOG。
5. 不臆测:拿不准是"漂移"还是"有意保留"(历史修订注、后续设计、术语)时,摆出来问,别默删默改。

注意

• 只查规格/契约/IA/视觉/结构类漂移;纯内部实现细节(不改对外行为)不在范围。
• 诚实:真有漂移就列全,别为"看起来一致"漏报或谎报。