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

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.

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

---
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.

# 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

---
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:

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