rules-check-drift

Original：🇺🇸 English

Translated

Check whether your rules file (CLAUDE.md or AGENTS.md) still matches the codebase after recent changes — run before a merge, or fold into your code-review pass. Reports stale/now-false rules, drifted architecture-map entries, and any new invariant worth adding, each with the minimal edit. Advisory and anti-bloat: it keeps the rules file true, never longer than it needs to be.

2installs

Sourcecoleam00/skills

Added on2026-08-14

NPX Install

npx skill4agent add coleam00/skills rules-check-drift

SKILL.md Content

View Translation Comparison →

/rules-check-drift — keep your rules file true, not longer

Your rules file — CLAUDE.md
or AGENTS.md
— is a steering document, not documentation: your ground rules, your conventions, and a current map of where things live. Its only failure mode that matters is being wrong: a stale rule or a drifted map actively misleads the agent on every future run. This skill checks the rules file against what just changed and proposes the smallest edit that keeps it true.

Wrong rules are worse than missing rules. A longer rules file is worse than a lean one. Most changes need no edit at all — adding a wrong or verbose line makes it worse.

Input

```
$ARGUMENTS
```
— optional diff range. Default: uncommitted + staged (
```
git diff HEAD
```
); fall back to
```
main...HEAD
```
.
Scope: the project's rules file(s) —
```
CLAUDE.md
```
and/or
```
AGENTS.md
```
, the root file + any package-level ones. (If
```
CLAUDE.md
```
is just a
```
@AGENTS.md
```
import, check
```
AGENTS.md
```
.) Ignore README,
```
docs/
```
, and
```
.claude/
```
agent/command/skill files. This skill exists to keep the rules honest, nothing else.

Process

1. See what changed

git diff <range>

+

git status

. Note: moved/renamed/removed files, new modules, changed conventions, and any new invariant the change establishes.

2. Read the rules file as it is now

Load the project's rules file —

CLAUDE.md

or

AGENTS.md

(and any package-scoped ones). Hold each claim against the change set.

3. Flag ONLY these three things

A stated rule or fact is now false — e.g. "routes live in
```
src/routes/
```
" but they moved. → fix it.
The architecture map drifted — a path or "where things live" pointer no longer matches reality. → fix the wrong entry (don't catalog every new file).
A new durable invariant must hold going forward — the change introduces a rule that must stay true (e.g. "never call the DB from handlers — go through
```
repository/
```
"). → add it as one line.

Everything else, leave alone. Do not suggest an edit to record that a feature was added (that's a changelog — the codebase is the source of truth), to restate what the code already makes obvious, or to add background/rationale/prose that doesn't steer future work.

4. Write each suggestion the way CLAUDE.md should read

One bullet, not a paragraph. A rule is a line, not an essay.
Keep the map current — don't grow it. Fix the wrong path; don't enumerate the new ones.
State rules in natural language; reference the codebase, never paste code. Copied code goes stale; the codebase stays true. Good: "follow the error pattern in
```
src/core/errors/
```
." Bad: pasting the class.

Output

## Rules-file drift check — range: <range>

### Fix (now false)
| Where | What's wrong | Minimal fix |
|-------|--------------|-------------|
| "Architecture" map | routes moved `src/routes/` → `src/api/routes/` | update the one path |

### Add (new invariant only)
- <one-line rule> — established by <the change that made it durable>

### Checked, still true — no edit
- <areas you verified need no change>

If nothing drifted: "The rules file is still accurate for these changes — no edits needed."

Rules

Advisory. Report the drift; only apply/piv-commit edits if the caller explicitly asks.
Rules file only (
```
CLAUDE.md
```
/
```
AGENTS.md
```
). Not README, not docs.
Lean by default. When in doubt, suggest nothing.
Run it before every merge (or as part of
```
/piv-review-changes
```
) so your rules never drift behind the code.