Claude Code Rules: Stop Dumping Everything Into One Giant CLAUDE.md

Picture your CLAUDE.md file. It started small. Then someone added testing conventions. Then API patterns. Then deployment steps, then database schema notes, then a list of anti-patterns to avoid. Six months later it's 500+ lines, and Claude reads every single one of them on every single session — whether the task in front of it touches testing, deployment, or none of the above.

Worse: if your team has people running Claude, Codex, and whatever else, each with their own instruction file, you get drift. Nobody actually knows which instructions apply where anymore.

Rules fix the growth problem. Instead of one file that loads in full every time, you get a folder of small, path-scoped markdown files that only load when the current task actually touches that path.

How it actually works#

Rules live in .claude/rules/. Each file's frontmatter defines when it should load — most commonly a paths pattern, glob-style, the same syntax you'd recognize from .gitignore. Touch a file under api/ with a .ts extension, and the matching rule loads. Touch something under frontend/, and a different rule loads instead. You can nest rules in subdirectories too — rules are discovered recursively, so backend rules can live in backend/, frontend rules in frontend/, and each only surfaces when relevant.

The result: your CLAUDE.md stays short — the stable, always-true stuff — and everything situational lives in a rule that loads on demand instead of polluting every context from the start.

In the video#

• 00:00 — The mess: everyone on the team running different agents with different, drifting instructions
• 01:48 — What a Rules folder actually is (.claude/rules/)
• 03:32 — The frontmatter format: paths, and how pattern matching works
• 04:44 — Live demo: splitting a 532-line CLAUDE.md into Rules
• 05:40 — The result: ~35 lines left in CLAUDE.md, the rest split by topic
• 06:33 — Testing it: creating a new API endpoint, watching the right rule load
• 06:56 — Team workflow: locking CLAUDE.md to codeowners, proposing new rules via PR

Splitting a 532-line file for real#

In the video, the starting point is a real CLAUDE.md for a course project: 532 lines, loaded in full on every session. Claude is asked to analyze it and propose how to split it into Rules — and comes back with a plan: keep roughly 35 lines in CLAUDE.md (core architecture, anti-patterns), and split the rest into path-scoped rules — one for the database schema and types, one for services, one for API routes.

Each rule gets a paths pattern pointing at the code it actually governs. Restart the session, create a new API endpoint, and you see it confirmed directly in the transcript: the API-routes rule loads, and only that one.

Making it a team process#

Once Rules exist, you can lock down CLAUDE.md itself so only codeowners can touch it, and route every new Rule through a pull request — someone proposes a new rule, the codeowners review it, it either merges or it doesn't. That's a real review process for what your AI assistant is allowed to assume, instead of every developer silently editing a shared instruction file.

There's also a neat idea worth trying: have the agent evaluate itself at the end of a session and ask "what did I just do that could have been a Rule?" — that's not built-in tooling, just a prompt you can add yourself, but it turns your rule set into something that grows from real usage instead of upfront guessing.

The actual point#

CLAUDE.md should stay short — the two or three paragraphs that are always true, no matter what you're working on. Everything else — the testing conventions, the deployment steps, the schema quirks — belongs in a Rule that only shows up when the task actually needs it. A file that grows forever isn't documentation. It's noise your agent has to wade through on every single run.