doc-drift

doc-drift 是一个 Claude 记忆审计技能，用于检查 Claude Code 在某个项目上下文中实际加载或可能引用的记忆与文档，找出其中过时、互相不一致、危险或含糊的内容，并按优先级整理成报告。

用途

当用户希望审计 Claude Code 加载进上下文的记忆和文档时使用，包括 CLAUDE.md（用户全局 + 项目 + 嵌套）、MEMORY.md 等。一句话概括：通览 Claude 在该项目中读取的记忆与文档，找出陈旧、互不匹配、危险或模糊的内容，并给出优先级排序。

主要能力

审计分三步：

收集被读取的文件：不使用脚本，由 LLM 通过 Read / Glob / Grep 直接查找。起点包括：
- ~/.claude/CLAUDE.md（若存在）
- <cwd>/CLAUDE.md 及嵌套 **/CLAUDE.md
- ~/.claude/projects/<encoded-cwd>/memory/MEMORY.md，其中编码方式为 cwd 绝对路径的 / 替换为 -，例如 /foo/bar → -foo-bar
- <cwd>/.claude/skills/**/SKILL.md
- <cwd>/.claude/agents/*.md
- <cwd>/.claude/commands/*.md
- ~/.claude/plugins/**（已安装插件的 skills/agents/commands）
扩展方式：从每个文件中递归提取并跟踪 @import 令牌（用户全局以 ~/.claude/ 为基准，其他以文件所在目录或项目根为基准）、相对路径 Markdown 链接 text、以及反引号中提及且实际存在的文件路径，直到不再出现新节点。
检测三类问题：
- Outdated：与代码/配置现实不符的陈述（路径、命令、数字、策略、版本等）
- Conflict：两份文档对同一主题的描述互相矛盾
- Risky / Ambiguous：解读存在分歧，或错误遵循会带来危险的指令（例如“适当处理”“视情况而定”、未明确说明就删除或覆盖的指令等）
每条发现都必须附带证据：所声称位置（file:line）与反证（file:line 或当前代码引用）。置信度低的内容会被直接剔除——误报是该工具最大的敌人。
按优先级给出改进建议：排序标准为：
- 影响范围——CLAUDE.md / MEMORY.md 等每次对话都会加载的文件优先
- 严重度——遵循错误指令会破坏系统为 HIGH，令人困惑但易恢复为 MED，轻微不一致为 LOW
- 修复难度——修复方案明确的优先
每条发现都包含建议的修正方案，达到人工一眼即可判断“OK/NO”的程度。

输出

保存到 .drift-reports/ 目录（不存在则创建，禁止加入 .gitignore——历史记录需要在 PR 中可见）：

.drift-reports/<YYYY-MM-DD-HHMM>.md —— 带时间戳的报告
.drift-reports/latest.md —— 最新版本的副本

报告模板：

# Memory Audit — {timestamp}

**Scanned:** {n} files reachable from CLAUDE.md / MEMORY.md / skills / agents
**Findings:** HIGH {h} / MED {m} / LOW {l}

## Top priority
1. **[HIGH] `path:line`** — {一行摘要}
   - 声称: "..."
   - 现实: `other/path:line` — ...
   - 建议: ...
2. ...

## Medium
...

## Low
...

## 待判断（需人工决定）
- Conflict 中无法确定哪一方正确的条目
- Ambiguous 中意图不明确的条目

## 下一步
要创建自动修复 PR 吗？（仅限 Outdated 中修复方案明确的）

自动修复（可选）

仅在输出报告摘要之后才询问：

“发现 HIGH {h} 条。要如何处理？

仅为修复方案明确的条目创建 PR
只要报告”

选择后，在 docs/drift-fix-<timestamp> 分支上按每条发现生成原子提交，并 gh pr create。

始终排除：Conflict（哪一方正确需人工判断）、Risky/Ambiguous（需确认意图）。

原则

最小化误报——没有把握就剔除。只有人信任报告，工具才有价值。
证据必需——每条发现都要引用 file:line 双方。
尊重“摘要 + 链接”模式——CLAUDE.md 摘要或链接其他文档属正常，仅在含义实际发生漂移时才报告。
优先处理每次对话都加载的文件——CLAUDE.md、MEMORY.md 的漂移比其他任何文件都危险。

参数

输入	行为
/doc-drift	全量审计（默认）
/doc-drift recent 或 recent 50	仅审计最近 N 次提交中变更的区域
/doc-drift path <glob>	仅审计特定路径

技能介绍

用途

主要能力

输出

自动修复（可选）

原则

参数