/writing-rules

name: writing-rules
description: Creates scoped convention rules in .claude/rules/ that auto-inject into matching contexts. Use when adding project conventions or scoping guidelines. Use when user says 'add convention', 'scope guideline', 'add rule', 'create rule'.

Writing Rules

Overview

**Writing rules IS creating focused, path-scoped conventions that load only when they are relevant.**

`paths:` is a real load gate. Per the [official spec](https://code.claude.com/docs/en/memory#path-specific-rules): "Rules without a `paths` field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use." Rules without `paths:` load at launch with the same priority as `.claude/CLAUDE.md`; rules with `paths:` cost nothing until Claude touches a matching file.

**Core principle:** Rules = small, focused conventions, scoped with `paths:` so they stay out of context until needed. CLAUDE.md = top-level project identity, build commands, gotchas — always resident, so keep it under 200 lines. Hard rules that must never be bypassed = hooks (instruction compliance is ~70%, not 100%).

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 0. Fetch latest official rule/skill spec 1. Analyze requirements 2. RED - test without rule 3. GREEN - write rule file 4. Validate structure 5. REFACTOR - quality review 6. Test activation

Announce: "Created 7 tasks (0–6). Starting execution..."

Configuration Creation Process

| Phase | Focus | What You Do | |-------|-------|-------------| | **Analysis** | Understanding | Identify what convention needs enforcement | | **Scope Definition** | Targeting | Determine which files need this convention | | **Design** | Planning | Structure rule content and path patterns | | **Implementation** | Creation | Write clear, specific configuration rules | | **Optimization** | Refinement | Streamline scope and improve clarity |

Task 0: Fetch Latest Official Spec

**Goal:** Pull the current Anthropic spec for path-scoped rules / skill frontmatter before designing — never trust cached memory.

**Action:**

Skill tool: fetching-claude-docs
  component: memory
  question: "CLAUDE.md auto-loading behavior, .claude/rules/ directory loading,
             nested CLAUDE.md per directory, @ import syntax, token cost"

**Verification:** Received YAML with non-empty `spec_excerpt`. Use as authoritative reference. If the fetched spec contradicts anything in this SKILL, the fetched spec wins — record the contradiction so this SKILL can be corrected.

Task 1: Analyze Requirements

**Goal:** Understand what convention to encode and where it applies.

**Questions to answer, in order:**

• Is it a hard rule that must never be bypassed? → Use a hook, not a rule.
• Does it require multi-step procedure? → Use a skill, not a rule.
• Does it apply to a specific file glob? → Path-scoped rule file.
• Otherwise: does CLAUDE.md + all unscoped rules stay under 200 lines with this added? → Add to CLAUDE.md. If it would push over budget → unscoped rule file, split for readability.
• Does this rule already exist? (compare against auto-loaded rule content in context — do NOT Read or Grep rule files)

**Verification:** Can state the convention in one sentence, name the file glob it applies to (or justify why it is genuinely cross-cutting), and confirm it isn't a hard rule (which would belong in a hook).

Task 2: RED - Test Without Rule

**Goal:** Work on matching files WITHOUT the rule. Note where convention is forgotten.

**Process:** 1. Identify 2-3 files that would match the rule 2. Ask agent to modify those files 3. Observe if conventions are followed naturally 4. Document specific violations

**Verification:** Documented at least 1 instance where convention was not followed.

Task 3: GREEN - Write Rule File

**Goal:** Create rule file addressing the gaps you documented.

Rule Location

~/.claude/rules/             # User-level (applies to every project)
.claude/rules/               # Project-level (this project only)
├── code-style.md            # Unscoped (no paths:) — loads at launch, every session
├── api/
│   └── conventions.md       # paths: ["src/api/**"]  ← loads only on matching files
└── testing/
    └── guidelines.md        # paths: ["**/*.test.ts"]

All `.md` files are discovered recursively, so subdirectories are just organization.

Rule Format

---
paths:                        # Omit only for genuinely cross-cutting rules
  - "src/api/**/*.ts"
---

# Rule Title

- Constraint 1 (imperative: "MUST", "NEVER")
- Constraint 2

Loading Mechanism

• **Without `paths:`** — loaded at launch, every session, same priority as `.claude/CLAUDE.md`. Costs tokens in every conversation.
• **With `paths:`** — loaded when Claude reads a file matching the glob, not on every tool use. Costs nothing until then. This is the reason to scope aggressively.
• User-level `~/.claude/rules/` loads before project rules, giving project rules higher priority.
• Symlinks are supported for sharing rules across projects; circular symlinks are handled.
• For deterministic enforcement (hard-stop a tool call), use a hook — rules cannot enforce, only suggest.

Writing Rules

**Key constraints:**

• **< 50 lines** — long rules dilute adherence, and unscoped ones cost tokens every session
• **Imperative form** — "MUST use", not "try to use"
• **No procedures** — how-to belongs in skills
• **Scope with `paths:`** — this genuinely gates loading. Omit it only when the rule really applies to all work.

See [references/examples.md](references/examples.md) for good/bad rule examples by domain.

**Content validation checks:**

| Check | Fail condition | Action | |-------|---------------|--------| | Line count | > 50 lines | Must simplify or split | | Procedural content | Contains numbered steps, multi-line code blocks | Extr