writing-rules

Writing Claude Code rules

Rules = topic-scoped instruction files. Official memory feature. Get the loading model right or the rule either bloats every session or never fires.

Loading model (the thing that's easy to get wrong)

• File under .claude/rules/ (project) or ~/.claude/rules/ (user).
• No paths: frontmatter → loaded at session start, always-on, same priority as CLAUDE.md. Costs context every turn.
• paths: frontmatter (YAML list of globs) → lazy-loaded, injected only when a file matching a glob is read/edited. Zero cost until then.
• Precedence: user rules load first, project rules after (project wins).

Default to paths:-scoped. Omit paths: ONLY when the rule genuinely governs all work (rare — that's usually CLAUDE.md's job).

Frontmatter

• The only recognized key is paths:. No name, description, or alwaysApply — adding them does nothing.
• Globs: gitignore-style, relative to project root. Brace expansion ok.

---
paths:
  - "src/**/*.ts"
  - "src/**/*.tsx"
  - "tests/**/*.ts"
---

• Scope to the files the rule actually governs. A rule about the locator engine → src/locator-engine/** + the specific files it touches, not src/**.
• Want it always-on → emit NO frontmatter at all (not empty paths:).

Never @import a rule into CLAUDE.md

Forces it always-on, defeating lazy-load. Reference it in prose if needed (detail in .claude/rules/x.md), don't @import.

Rule vs CLAUDE.md vs skill

• CLAUDE.md — always-relevant core: commands, architecture map, project-wide conventions. Always loaded. Project copy lives at ./CLAUDE.md or .claude/CLAUDE.md; ancestor directories load too.
• Rule — instructions that only matter when touching a file area. Lazy-load via paths:.
• Skill — a task-specific procedure invoked on demand (only its description sits in context). Reach for a skill when it's a how-to-do-X workflow, not a constraint-on-area-Y.

When CLAUDE.md approaches ~200 lines, split area-specific detail out into path-scoped rules.