How to Use Claude Code Rules | Differences and Use Cases vs. CLAUDE.md

1. What "claude rule" Actually Is — The .claude/rules/ Feature in Claude Code

The main result for the search term "claude rule" is the rule files that Claude Code loads from the .claude/rules/ directory in your project. At the start of a session, Claude Code automatically discovers .md files in this directory and begins work with your project-specific conventions already in context.

The official documentation (code.claude.com/docs/en/memory) describes rules as a mechanism for "modularizing instructions and making them easier for teams to maintain." Like CLAUDE.md, rules are loaded into context at the beginning of each session, but they are "context" rather than enforced configuration — a point they share with CLAUDE.md. Operations you want to block unconditionally should be implemented on the PreToolUse hook side; that is the intended division of responsibility.

In short, "claude rule" refers to the rule-definition mechanism in Claude Code, and its concrete form is the .claude/rules/ directory.

2. Differences Between CLAUDE.md and Rules — When to Use Which

The most common question is: "If I already have CLAUDE.md, why do I need rules?" The differences boil down to three points:

1. Format: CLAUDE.md is a single file placed at the project root. .claude/rules/ is a directory where you can place multiple .md files, one per topic.
2. Scope: CLAUDE.md applies broadly to the whole project. Rules with paths can be scoped to specific file paths only.
3. Load timing: Rules without paths are always loaded at startup. Rules with paths are loaded only when a matching file is opened.

Practical guides also describe rules as "a mechanism to eliminate the need to repeat the same explanations every time." The recommended approach is a hybrid operation: keep fundamental project-wide rules in CLAUDE.md and put per-domain detailed rules in .claude/rules/. Since the official documentation explicitly states the goal is to keep CLAUDE.md under 200 lines, using rules as the overflow container is the standard pattern.

3. How to Set Up .claude/rules/ and Structure the Directory

The setup is simple. Follow these steps:

1. Create a .claude/rules/ directory at the project root.
2. Place .md files with descriptive names for each topic (code-style.md, testing.md, security.md, etc.).
3. For larger projects, organize with subdirectories like frontend/ and backend/ (.md files are discovered recursively).
4. When you start a session, rules without paths are loaded at startup.

The typical layout shown in the official documentation is as follows:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style conventions
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

Rules without paths are loaded at startup with the same priority as .claude/CLAUDE.md. This means you can freely place general rules you want applied everywhere directly in .claude/rules/.

4. Narrowing Scope with paths Frontmatter (Path-Specific Rules)

The real power of the rules feature lies in the paths frontmatter. By writing paths in YAML frontmatter, a rule is applied only when Claude is working with files that match the specified pattern.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Add documentation comments for OpenAPI

Glob patterns support extensions, directories, and combinations thereof; brace expansion lets you specify multiple extensions at once.

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

The meaning of common patterns: **/*.ts matches all TypeScript files in any directory; src/**/* matches everything under src/; *.md matches Markdown files directly at the root. Rules without paths apply unconditionally to all files. The behavior described as "dynamically loading rules" (zenn.dev) is exactly this path-specific rule loading. It lets you avoid adding frontend conventions to the context while you are working on backend code.

5. User Rules and Sharing — ~/.claude/rules/ and Symlinks

Personal preferences that should apply across all projects can be placed in ~/.claude/rules/ under your home directory. Rules placed here apply to every project on the machine and are loaded before project rules (meaning project-side rules take priority).

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

If you want to distribute a shared set of rules to your team, symlinks work well. .claude/rules/ resolves links and reads them normally, and it also detects circular links and handles them safely.

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

This lets multiple projects reference a single rule set managed in a shared repository, freeing you from the copy-paste maintenance cycle.

6. Writing Effective Rules — Best Practices to Follow

Rules do not simply "work by being written." Here are the key points for making rules take effect, drawn from official guidance and real-world experience:

1. Be specific: Instead of "format appropriately," write "2-space indentation." Instead of "write tests," write "run npm test before committing" — make it verifiable.
2. One file, one topic: Put testing conventions in testing.md, security rules in security.md. Mixing topics reduces compliance.
3. Pair prohibitions with alternatives: Don't just say "don't touch this" — also say "do this instead."
4. Avoid contradictions: When multiple files contain conflicting instructions, Claude will arbitrarily follow one of them. Periodically audit your rules.

Short, specific rules have higher compliance rates — the same principle that applies to CLAUDE.md. Just because you've split things into .claude/rules/ doesn't mean you should pack too much into one file; doing so buries important rules in noise.

7. Troubleshooting When Settings Don't Take Effect

If you feel a rule isn't being applied, the first step is to run the /memory command. This displays all the CLAUDE.md, CLAUDE.local.md, and rule files currently loaded in the session, so you can check whether your target file appears in the list. If it doesn't, Claude is not reading that file.

Points to check:

1. Is the file a .md file directly under .claude/rules/ (or a subdirectory)?
2. For rules with paths, does the file you currently have open match the glob? (If not, the rule won't be loaded.)
3. Are there any conflicting instructions in other rules or CLAUDE.md?

For deeper investigation, the official InstructionsLoaded hook lets you log "which instruction file was loaded, when, and why" (code.claude.com/docs/en/memory). This is useful for debugging path-specific rules and lazy loading from subdirectories. Note that for operations you want to ensure are always executed at a specific point (such as before a commit), a hook is more reliable than a rule.

8. Summary — Preventing CLAUDE.md Bloat with Rules

.claude/rules/ is a feature that structurally solves the problem of a bloated CLAUDE.md. Keep the basic overall rules in CLAUDE.md, split per-domain details into rules, and use paths to apply each rule only to the files that need it — this three-layer approach is the practical standard as of 2026. Personal preferences go in ~/.claude/rules/; shared standards can be distributed via symlinks, keeping team maintenance manageable. The fastest path to getting started is to extract just one file — say, testing.md — and then verify it loads with /memory as you build from there.

Sources: Claude Code Official Documentation "How Claude Remembers Your Project" / Samurai Engineer / SIOS Tech.Lab / Zenn (tmasuyama1114) / note (masao)