A rulebook rots quietly. What checks it every Monday?
Rules for Claude Code pile up until two of them contradict each other and nobody notices. A scheduled read-only lint found the contradictions the team had stopped seeing.
How to do it
- Start without a model. A plain script can find rule IDs, commands, scripts and links that point at nothing. Those are the cheapest findings and they need no Claude at all.
- Add four read-only passes with claude -p, one question each: CONFLICT, STALE, DRIFT and DUPLICATE. Give it only Read, Grep and Glob, no project settings loaded, no session saved. One pass with one question is easier to trust than one pass that asks everything.
- Put it on a schedule, not in a hook. Ours is a launchd job on Monday at 11:00. It runs the lint script straight from the remote main branch, so the local checkout is never pulled and never changes under it.
- Write the report to a dated file and keep a log. The first report held 41 findings. Three were checked by hand and were real: a gate script blocked a push that the handoff guide said goes through, and a guide accepted a ticket prefix that a check script refused. Each had sat there while people read the files every day.
- Keep the fixes human. Nothing in the job edits a rule. Every finding goes through the same review as any other rule change, because only one person on the team approves rules.
- Say no to the full wiki. We looked at the LLM Wiki pattern and took only the lint job. An earlier auto-capture queue had collected 1669 events and nobody ever read one of them. A weekly report someone opens beats a stream nobody consumes.
You are linting a rulebook that a coding agent follows. Read-only: do not edit, create or move any file. Read every rule, script and guide under the rules directory. Report only CONFLICT findings: two places that cannot both be true, such as a script that blocks what a guide says is allowed, or two rules that give different answers to the same situation. For each finding give both file paths, quote the exact lines, and say in one sentence what happens to an engineer who follows the first one. Do not propose rewrites. If you find nothing, say so in one line.