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

Document the gap as a concrete statement: "The agent does X, but should do Y."

Conclude this step when there is a clear, specific behavior to correct.

Step 2: Determine Rule Scope

Decide whether this rule should be:

1. Global (no paths frontmatter) — applies to all work in the project
2. Path-scoped (paths frontmatter with glob patterns) — applies only when working with matching files
3. User-level (~/.claude/rules/) — applies across all projects for personal preferences

Decision guide:

Is this project-specific?
  No  → User-level rule (~/.claude/rules/)
  Yes → Is it relevant to ALL files?
    Yes → Global rule (.claude/rules/rule-name.md)
    No  → Path-scoped rule (.claude/rules/rule-name.md with paths: frontmatter)

Step 3: Write Contrastive Examples

This is the most critical step. Write the Incorrect and Correct examples BEFORE writing the description.

1. Start with the Incorrect pattern — write the exact code or behavior the agent produces that needs correction
2. Write the Correct pattern — show the minimal fix that addresses the issue
3. Verify contrast is clear — the difference between Incorrect and Correct must be obvious and focused on exactly one concept

Quality check for contrastive examples:

Step 4: Write the Rule Description

Now write the 1-2 sentence description that connects the contrastive examples. The description must:

• State WHAT the rule enforces
• State WHY it matters (the impact or consequence)
• Use imperative form ("Use early returns" not "You should use early returns")

Step 5: Assemble the Rule File

Create the rule file following the structure template:

1. Add YAML frontmatter with title, impact, tags, and optionally paths
2. Write the heading and description
3. Add the Incorrect section with description and code
4. Add the Correct section with description and code
5. Optionally add a Reference section with links

Place the file in .claude/rules/ with a descriptive filename.

Step 6: Validate the Rule

Before finishing, verify:

1. File location — rule exists at .claude/rules/<rule-name>.md
2. Frontmatter — contains at minimum title and impact
3. Contrastive examples — both Incorrect and Correct sections present with code blocks
4. Token budget — description is 50-200 words (excluding code)
5. Path scoping — if paths is set, glob patterns match intended files
6. No overlap — rule does not duplicate guidance in CLAUDE.md or other rules

Step 7: Iterate Based on Feedback or Observations

After a rule is written, apply a Decompose → Filter → Reweight refinement cycle before finalizing:

7.1 Decompose Check

Consider splitting complex rules into multiple focused rules.

For rules that your written, ask yourself: "Is this rule trying to cover more than one concept?"

• If YES, split it into multiple focused rules, each addressing exactly one concept
• If the Incorrect example shows multiple distinct anti-patterns, create separate rules for each