Your AI Config is Full of Rules It Ignores

My CLAUDE.md grew to 3,550 lines.

I spent months adding rules, convinced that more instructions meant better compliance. Then I analyzed which rules Claude actually followed. The answer was devastating: text-based rules have near-zero enforcement rate.

I cut it down to ~400 lines, moved the real constraints into hooks (code-level enforcement), and turned the recurring anti-patterns into an open-source linter: ailint.

This post is about the five structural problems I found in my own file — and probably in yours too.

The Five Patterns That Kill Your Config

1. Vague Language

盡量寫乾淨的程式碼。
Try to keep responses concise.

"Try to" is a get-out-of-jail-free card. The AI can always claim it tried. This isn't a rule — it's a suggestion. Suggestions get ignored.

The fix: Replace every "try to" / "when possible" / "盡量" with a concrete condition or delete it entirely.

2. Contradictions

Section A: When you receive a task, just do it.
Section B: All changes require confirmation before execution.

By the time you write Section B, you've forgotten what Section A says. The AI picks whichever is more convenient — usually the one that requires less work.

The fix: Search your config for opposing keyword pairs. Or use ailint --deep to find semantic contradictions that keyword matching misses.

3. Redundancy

The same rule, written three different ways — once in "Safety", once in "Operations", once in "Guidelines". Each version eats context window tokens without adding any constraint.

The fix: If two sections are >70% similar, merge them.

4. Dead References

For deployment instructions, see rules/deploy-sop.md

That file was deleted three months ago. The AI sees the reference, can't find the file, and guesses.

The fix: Audit every file path in your config. Or let R004 do it automatically.

5. Bloat

The file keeps growing because nobody dares delete anything — "what if that rule is still needed?" The result: your important rules get diluted in a sea of "maybe useful" noise.

The fix: If your config is over 500 lines, something is wrong. If it's over 1,000 lines, most of it is being ignored.

ailint: A Linter for AI Config Files

I packaged these five patterns into a CLI tool that checks CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, and .windsurfrules.

pip install airulelint
ailint CLAUDE.md

CLAUDE.md:45:3  warning [R002] Vague phrase 'try to' is hard to enforce.
CLAUDE.md:89:1  warning [R003] Section 'Safe Operations' overlaps with 'Safety Rules' (0.78 similarity).
CLAUDE.md:167:5 error   [R004] Referenced path does not exist: rules/deploy-sop.md

✖ 3 problems (1 error, 2 warnings)

Five static rules, zero dependencies, runs in under a second. Add --deep for LLM-powered semantic contradiction detection.

Does It Actually Work?

I tested it on 7 real-world config files across different projects. The results from two rounds of testing:

The biggest improvement was in R004 (dead references) — the first version flagged version numbers like 1.1/1.2, GCP roles like roles/container.developer, and Chinese punctuation as "missing files." After filtering, only real dead links remain.

The Honest Take

If your config is under 100 lines, you don't need this tool. Just keep it short and review it occasionally.

ailint is for people who've already fallen into the bloat trap — configs that grew organically over months, accumulated contradictions, and became too long to review manually. If that sounds familiar, run it once. You might be surprised.

The deeper lesson isn't about the tool. It's this: the real enforcement mechanism for AI behavior is code, not text. Hooks that block bad actions beat rules that ask nicely. A linter that flags problems beats a paragraph that explains best practices.

Your config should be short, concrete, and enforceable. Everything else is noise.

GitHub: MakiDevelop/ailint
Install: pip install airulelint

I'm Maki (Chung-Chiao Chiang), an AI systems builder with roots in TPM and product management. I design multi-agent collaboration architectures and built ACA — the first open protocol for AI agent governance.