doc-drift

doc-drift — Claude memory audit

One sentence: It scans the memory and documents that Claude reads in this project, finds outdated, inconsistent, risky, or ambiguous items, and organizes them by priority.

Step 3

1. Gather what is read

Gather the files that Claude Code can actually load or reference in this project context. Without a script, the LLM Read / Glob / Grepfinds them directly with

Starting point

~/.claude/CLAUDE.md (if present)
<cwd>/CLAUDE.md + nested **/CLAUDE.md
~/.claude/projects/<encoded-cwd>/memory/MEMORY.md
- Encoding: replace with / 를 - of the cwd absolute path. Example: /foo/bar → -foo-bar
<cwd>/.claude/skills/**/SKILL.md
<cwd>/.claude/agents/*.md
<cwd>/.claude/commands/*.md
~/.claude/plugins/** (skills/agents/commands of installed plugins)

Extension Extract the following from each file and follow them recursively:

@import tokens (user global is based on ~/.claude/ , others are based on the file directory or project root)
Relative-path Markdown link [text](./path.md)
File path mentions inside backticks (only if they actually exist)

Collect until no new nodes appear.

2. Detect three things

The LLM reads each file to be audited, and only the following three things finds:

Type	Criteria
Outdated	Claims that do not match the reality of the code/config (paths, commands, numbers, policies, versions, etc.)
Conflict	Two documents describe the same topic differently
Risky / Ambiguous	Instructions whose interpretation varies or that are dangerous if followed incorrectly (e.g., "do it appropriately", "depending on the case", instructions to delete/override without specification, etc.)

Each finding must have evidenceattached: the claimed location (file:line) and the counterevidence (file:line or a quote of the current code).

If confidence is low, omit it entirely. False positives are this tool's biggest enemy.

3. Suggest improvements by priority

Write the report sorted by the following criteria:

Scope of impact — CLAUDE.md / MEMORY.md Files loaded in every conversation, such as , are at the top
Severity — things that break if you follow the wrong instruction (HIGH), things that are confusing but easy to recover from (MED), minor inconsistencies (LOW)
Difficulty of fixing — start with those whose fix is clear

각 finding에 Include the proposed fixat a level where a person can judge "OK/NO" at a glance.

Output

.drift-reports/ Save to the directory (create it if absent, do not add .gitignore — the history must be visible in the PR):

.drift-reports/<YYYY-MM-DD-HHMM>.md — timestamped report
.drift-reports/latest.md — copy of the latest version

Report template:

# 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 중 수정안 명확한 것만)

Auto-fix (optional)

Ask only after outputting the report summary:

"Found {h} HIGH issues. What would you like to do?

Create a PR only for those with a clear fix

Report only"

If selected, docs/drift-fix-<timestamp> atomic commit per finding on the branch, gh pr create.

always exclude: Conflict (a human decides which side is right), Risky/Ambiguous (intent needs confirmation).

Principles

Minimize false positives — If uncertain, leave it out. People must trust the report for the tool to survive.
Evidence required — Every finding is file:line quoted from both sides.
Respect summary + link patterns — CLAUDE.mdsummarizing or linking another document is normal. Report only when the meaning has actually drifted.
Prioritize files loaded in every conversation — CLAUDE.md, MEMORY.md 's drift is more dangerous than any other file's.

Argument

Input	Action
`/doc-drift`	Full audit (default)
`/doc-drift recent` / `recent 50`	Only areas changed in the last N commits
`/doc-drift path <glob>`	Only a specific path