create-rule

What this skill does

# Create Rule

Guide for creating effective `.claude/rules` files with contrastive examples that improve agent accuracy.

## Overview

**Core principle:** Effective rules use contrastive examples (Incorrect vs Correct) to eliminate ambiguity. 

**REQUIRED BACKGROUND:** Rules are behavioral guardrails, that load into every session and shapes how agents behave across all tasks. Skills load on-demand. If guidance is task-specific, create a skill instead.

## About Rules

Rules are modular, always-loaded instructions placed in `.claude/rules/` that enforce consistent behavior. They act as "standing orders" — every agent session inherits them automatically.

### What Rules Provide

1. **Behavioral constraints** — What to do and what NOT to do
2. **Code standards** — Formatting, patterns, architecture decisions
3. **Quality gates** — Conditions that must be met before proceeding
4. **Domain conventions** — Project-specific terminology and practices

### Rules vs Skills vs CLAUDE.md

| Aspect | Rules (`.claude/rules/`) | Skills (`skills/`) | CLAUDE.md |
|--------|--------------------------|---------------------|-----------|
| **Loading** | Every session (or path-scoped) | On-demand when triggered | Every session |
| **Purpose** | Behavioral constraints | Procedural knowledge | Project overview |
| **Scope** | Narrow, focused topics | Complete workflows | Broad project context |
| **Size** | Small (50-200 words each) | Medium (200-2000 words) | Medium (project summary) |
| **Format** | Contrastive examples | Step-by-step guides | Key-value / bullet points |

## When to Create a Rule

**Create when:**

- A behavior must apply to ALL agent sessions, not just specific tasks
- Agents repeatedly make the same mistake despite corrections
- A convention has clear right/wrong patterns (contrastive examples possible)
- Path-specific guidance is needed for certain file types

**Do NOT create for:**

- Task-specific workflows (use a skill instead)
- One-time instructions (put in the prompt)
- Broad project context (put in CLAUDE.md)
- Guidance that requires multi-step procedures (use a skill)

## Rule Types

### Global Rules (no `paths` frontmatter)

Load every session. Use for universal constraints.

```markdown
# Error Handling

All error handlers must log the error before rethrowing.
Never silently swallow exceptions.
```

### Path-Scoped Rules (`paths` frontmatter)

Load only when agent works with matching files. Use for file-type-specific guidance.

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

# API Development Rules

All API endpoints must include input validation.
Use the standard error response format.
```

### Priority Rules (evaluator/judge guidance)

Explicit high-level rules that set evaluation priorities.

```markdown
# Evaluation Priorities

Prioritize correctness over style.
Do not reward hallucinated detail.
Penalize confident wrong answers more than uncertain correct ones.
```

## Rule Structure: The Contrastive Pattern

Every rule MUST follow the Description-Incorrect-Correct template. This structure eliminates ambiguity by showing both what NOT to do and what TO do.

### Required Sections

```markdown
---
title: Short Rule Name
paths:                          # Optional but preferable: when it is possible to define, use it!
  - "src/**/*.ts"
---

# Rule Name

[1-2 sentence description of what the rule enforces and WHY it matters.]

## Incorrect

[Description of what is wrong with this pattern.]

\`\`\`language
// Anti-pattern code or behavior example
\`\`\`

## Correct

[Description of why this pattern is better.]

\`\`\`language
// Recommended code or behavior example
\`\`\`

## Reference

[Optional: links to documentation, papers, or related rules.]
```

### Why Contrastive Examples Work

Researches shows that rules with both positive and negative examples are significantly more discriminative than rules with only positive guidance. The Incorrect/Correct pairing:

1. **Eliminates ambiguity** — the agent sees the exact boundary between acceptable and unacceptable
2. **Prevents rationalization** — harder to argue "this is close enough" when the wrong pattern is explicitly shown
3. **Enables self-correction** — agents can compare their output against both patterns

## Writing Effective Rules

### Rule Description Principles

Explicit, high-level guidance:

| Principle | Example |
|-----------|---------|
| **Prioritize correctness over style** | "A functionally correct but ugly solution is better than an elegant but broken one" |
| **Do not reward hallucinated detail** | "Extra information not grounded in the codebase should be penalized, not rewarded" |
| **Penalize confident errors** | "A confidently stated wrong answer is worse than an uncertain correct one" |
| **Be specific, not vague** | "Functions must not exceed 50 lines" not "Keep functions short" |
| **State the WHY** | "Use early returns to reduce nesting — deeply nested code increases cognitive load" |

### Incorrect Examples: What to Show

The Incorrect section must show a pattern the agent would **plausibly produce**. Abstract or contrived bad examples provide no value.

**Effective Incorrect examples:**

- Show the most common mistake agents make for this scenario
- Include the rationalization an agent might use ("this is simpler")
- Mirror real code patterns found in the codebase

**Ineffective Incorrect examples:**

- Obviously broken code no agent would produce
- Syntax errors (agents already avoid these)
- Patterns unrelated to the rule's concern

### Correct Examples: What to Show

The Correct section must show the minimal change needed to fix the Incorrect pattern. Large rewrites obscure the actual lesson.

**Effective Correct examples:**

- Show the same scenario as Incorrect, fixed
- Highlight the specific change that matters
- Include a brief comment explaining WHY this is better

**Ineffective Correct examples:**

- Completely different code from the Incorrect example
- Over-engineered solutions that add unnecessary complexity
- Patterns that require additional context not shown

### Token Efficiency

Rules load every session. Every token counts.

- **Target:** 50-200 words per rule file (excluding code examples)
- **One rule per file** — do not bundle unrelated constraints
- **Use path scoping** to avoid loading irrelevant rules
- **Code examples:** Keep under 20 lines each (Incorrect and Correct)

## Directory Structure

```
.claude/
├── CLAUDE.md                    # Project overview (broad)
└── rules/
    ├── code-style.md            # Global: code formatting rules
    ├── error-handling.md        # Global: error handling patterns
    ├── testing.md               # Global: testing conventions
    ├── security.md              # Global: security requirements
    ├── evaluation-priorities.md # Global: judge/evaluator priorities
    ├── frontend/
    │   ├── components.md        # Path-scoped: React component rules
    │   └── state-management.md  # Path-scoped: state management rules
    └── backend/
        ├── api-design.md        # Path-scoped: API patterns
        └── database.md          # Path-scoped: database conventions
```

**Naming conventions:**

- Use lowercase with hyphens: `error-handling.md`, not `ErrorHandling.md`
- Name by the concern, not the solution: `error-handling.md`, not `try-catch-patterns.md`
- One topic per file for modularity
- Use subdirectories to group related rules by domain

## Rule Creation Process

Follow these steps in order, skipping only when a step is clearly not applicable.

### Step 1: Identify the Behavioral Gap

Before writing any rule, identify the specific agent behavior that needs correction. This understanding can come from:

- **Observed failures** — the agent repeatedly makes a specific mistake
- **Codebase analysis** — the project has conventions not obvious from code alone
- **Evaluation findings** — a judge/meta-judge identified a quality gap
- **User feedback** — explicit correction of agent behavior

Document the ga