Best practices for Claude Code rules files

Why rules files exist

Once your CLAUDE.md grows past a screen or two, cramming every convention into it stops working. The security rules blur into the CSS rules, the model skims, and nothing gets followed well. Claude Code lets you split conventions into separate rule files under .claude/rules/ — one file per domain — so each stays focused and easy to maintain.

Think of the root CLAUDE.md as the table of contents and the rule files as the chapters.

One domain per file

The winning pattern is a file per concern:

.claude/rules/
  testing.md
  security.md
  typescript.md
  databases.md
  nextjs.md
  app_layout_ui.md

When you edit the security rules, you're not scrolling past component conventions. When the agent works on a Server Action, the security and TypeScript rules are what matter — and they read cleanly because they aren't interleaved with everything else.

Make every rule actionable

A rule the agent can't act on is noise. Anchor each one to a concrete behaviour, ideally with a code example showing the wrong way and the right way:

Vague: "Write secure database code."
Actionable: "Enable RLS on every table. Never prefix the service role key with NEXT_PUBLIC_."

The best rule files read like a checklist a reviewer would run, not a philosophy essay.

Use "always" and "never" for non-negotiables

Reserve sharp imperative language for the rules that must never break. These are the ones that cause real damage when ignored:

Never run supabase db reset against an instance holding pipeline data.
Always validate Server Action input with Zod before using it.
Never import a server-only type into a client component.

Soft phrasing like "prefer" or "try to" gets deprioritized when the task gets hard. Save "never" for the things that are genuinely never okay.

Show the pattern, don't just describe it

Rules with a before/after example are followed far more reliably than prose. A three-line snippet of the correct shape teaches the convention faster than a paragraph explaining it:

// Bad — desktop-first, forbidden
<div className="w-1/3 lg:w-full">

// Good — mobile-first
<div className="w-full md:w-1/2 lg:w-1/3">

The agent pattern-matches on examples. Give it the pattern.

Keep them current

Rule files drift. A rule that points to a file, flag, or command that no longer exists is worse than no rule — it sends the agent down a dead end confidently. When you rename a module or change a workflow, update the rule that mentions it in the same commit. Treat the rules directory as part of the code, not documentation that rots in a corner.

Thanks for reading — more soon.