Create Rule

# 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 relate