Create a Claude Code rule

A rule is a small markdown file in .claude/rules/ that loads into context as instructions — same priority as .claude/CLAUDE.md, but split out by topic so things stay tidy. A rule can also be path-scoped so it only loads when Claude touches matching files, which saves context.

Three quick steps.

Step 1 — Name the file by topic

One topic per file, descriptive name. It lives at .claude/rules/<topic>.md. Subfolders are fine (discovered recursively):

.claude/rules/
├── code-style.md
├── testing.md
├── security.md
└── frontend/
    └── components.md

Step 2 — Decide the scope

Ask one question: does this apply everywhere, or only to certain files?

• Everywhere → no frontmatter. The rule loads at the start of every session.
• Only certain files → add paths: frontmatter with glob patterns. The rule loads only when Claude reads a file that matches — keeping it out of context until it's relevant.

When in doubt, scope it. A path-scoped rule is the lighter choice, and it's the main reason to use a rule over CLAUDE.md.

Step 3 — Write it

Keep it like good CLAUDE.md content: short, specific, verifiable. Bullets over paragraphs. Aim well under ~50 lines.

Always-on rule (no frontmatter):

# Testing

- Run `npm test` before committing.
- Co-locate tests next to the source file as `*.test.ts`.
- Mock network calls; never hit live services in unit tests.

Path-scoped rule (paths: frontmatter):

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

# API rules

- Every endpoint validates its input.
- Use the standard error response format.
- Include OpenAPI doc comments on each handler.

That's it — Claude Code discovers the file automatically. No wiring, no restart.

Glob cheat sheet for paths:

Multiple patterns and brace expansion both work:

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

Writing tips

• Specific beats vague: "Use 2-space indentation" lands better than "format code nicely."
• No contradictions: if two rules (or a rule and CLAUDE.md) disagree, Claude may pick one at random. Skim existing rules before adding.
• Verify it loaded: run /memory in Claude Code — it lists every CLAUDE.md and rules file in the session.

Rule vs CLAUDE.md vs skill — quick pick

• Rule → a standing instruction, especially one that only matters for certain files. Loads automatically.
• CLAUDE.md → the few "always true everywhere" facts (build commands, layout, top conventions). Loads every session.
• Skill → a multi-step procedure or workflow you invoke. Loads on demand, not always in context.

If it's a procedure with steps, it's probably a skill. If it's a "do it this way" instruction, it's a rule.