The missing linter for AI instruction files.
You asked for a small refactor. A small(!) refactor.
Claude Code rewrote half the module.
"You're right, I apologize." "Let me fix that." "Sorry, I misunderstood." — on repeat.
So you open the CLAUDE.md. Then the rules. Then the SKILLS. Each is 400 lines at least. 24 files total.
You cross-reference the official docs, skim three "best practices" blog posts, dig through GitHub examples.
Hours of trial and error later, you do what any reasonable person would: you ask Claude to figure it out.
───────────────────────────────────────────────────────────────────
❯ review my CLAUDE.md and rules. Tell me what is wrong.
───────────────────────────────────────────────────────────────────
Burn ALL the tokens
Claude Code obliges. It reads all 24 files, their cross-referencing imports and all the additional relevant documentation. It neatly summarizes them. It suggests improvements, you accept them, it rewrites a few sections, adds here, removes there.
It burns tokens like kindling.
Your CLAUDE.md, rules, SKILLS got just a bit longer, but you're fine with that — at least it won't happen again... right? This is fine. Right?
Forty minutes later, you have a slightly different mess and no idea if it's better. So you open CLAUDE.md ...
Lint the vibes!
Your code needs structure, types, format. It has tests, type checks and linters. Your AI instructions? Vibes.
Reporails helps with that.
claude mcp add reporails -- uvx --from reporails-cli ails-mcp
Then ask:
───────────────────────────────────────────────────────────────────
❯ what ails claude?
───────────────────────────────────────────────────────────────────
Runs deterministic checks and semantic validations. Produces actionable fixes Claude can apply.
Just run
───────────────────────────────────────────────────────────────────
❯ fix the duplicate
───────────────────────────────────────────────────────────────────
... and observe:
● I'll remove the duplicate from writing-rules.md since instruction-file-style.md already covers the "actionable content" requirement for .claude/rules/**.
● Update(.claude/rules/writing-rules.md)
⎿ Removed 1 line
26 - Use descriptive filenames (`api-validation.md` not `rules1.md`)
27 - Add `paths` frontmatter to reduce noise when not relevant
28 - No paths = loads globally for all files
29 -- Content MUST be actionable, not explanatory
● Done. Removed the duplicate "Content MUST be actionable, not explanatory" from writing-rules.md:29 — this is already covered by instruction-file-style.md:12 ("Every line
MUST be actionable or informative") which applies to the same scope.
The result
No more vibes. No more gluing together best practices blog posts.
● Semantic Evaluation
I already have context from the previous read. Evaluating the 9 candidates:
M4 (Contradictions): 2 candidates - all passed
C6 (Duplicates): 6 candidates - all passed (the duplicate I fixed is no longer flagged)
G3 (Security ownership): 1 candidate - passed (organizational guidance, not a security rule)
---
Final Score
┌────────────┬─────────────────────┐
│ Metric │ Value │
├────────────┼─────────────────────┤
│ Score │ 8.3↑ / 10(complete) │
├────────────┼─────────────────────┤
│ Capability │ Governed (L5+) │
├────────────┼─────────────────────┤
│ Violations │ 21 (↓2 from 23) │
└────────────┴─────────────────────┘
The C6 duplicate between instruction-file-style.md and writing-rules.md is resolved.
✻ Cogitated for 32s
Reporails v0.0.1
What took hours now takes minutes.
42 rules. Documented. Open source. Easy to extend.
CLAUDE.md is just the start. More agents coming soon.
Top comments (0)