/create-rule

name: create-rule
description: Use when found gap or repetative issue, that produced by you or implemenataion agent. Esentially use it each time when you say "You absolutly right, I should have done it differently." -> need create rule for this issue so it not appears again.

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.

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

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