version: "1.0.0" name: create-rule description: "Create Claude Code rules for persistent agent guidance. Use when adding coding standards, project conventions, security policies, workflow rules, or any guidance you want auto-loaded every session. Asks for missing scope/purpose, then writes a focused rule file to ~/.claude/rules/ (user-global) or .claude/rules/ (project)." context: fork model: sonnet allowed-tools: Read, Write, Edit, Glob, Grep

Creating Claude Code Rules

Rules are markdown files in ~/.claude/rules/ (user-global) or .claude/rules/ (project-scoped) that get auto-loaded into every session as guidance. They differ from skills (which load on-demand) by always being in context.

Use rules for principles, conventions, and policies that should be always-on. Use skills when behavior should be invoked deliberately.

Gather Requirements

Before creating a rule, determine:

1. Purpose: What principle, convention, or policy is being encoded?
2. Scope: User-global (applies to all your projects) or project-specific (this repo only)?
3. Override Behavior: Does this complement existing rules, or contradict them?
4. Evidence: What incident / pattern motivated this rule? (Helps prevent rule rot.)

Inferring from Context

If a recent conversation revealed a recurring mistake or validated approach, infer the rule from that. The strongest rules are those derived from real friction, not abstract principles.

Storage Locations

User-global rules are loaded for every session regardless of cwd. Project rules load only when working in that project.

Rule File Format

Rules are .md files with optional YAML frontmatter and Markdown body. The Claude Code rule format is simpler than Cursor's:

# Rule Name
 
> One-line description of what this rule governs.
 
## When This Applies
 
[Specific conditions, file types, workflow phases]
 
## The Rule
 
[The actual guidance — clear and specific]
 
## Examples
 
### ✅ Good

[concrete example of correct behavior]

 
### ❌ Bad

[concrete example of what to avoid]

 
## Rationale
 
[Why this rule exists — incident reference, evidence, principle]

Note: Unlike Cursor's .mdc rules with globs and alwaysApply, all Claude Code rules in rules/ always-apply. There's no file-pattern matching at the rule level. If you need conditional rules, use Skills with descriptions that include trigger conditions.

Naming Conventions

• Lowercase with hyphens: code-quality.md, security.md, tool-discipline.md
• One concern per file (avoid mega-rules)
• Group related sub-concerns within a file via ## headings

Length Guidelines

• Under 200 lines: Optimal — token cost stays low, agent can hold full context
• 200-400 lines: Acceptable for foundational rules (e.g., foundation.md)
• Over 400 lines: Split into focused sub-rules

The user's current ~/.claude/rules/ has 13 rules averaging ~150 lines each. Match that scale.

Writing Effective Rules

Lead with the Rule, Then Justify

## Rule
Read before Edit or Write. No exceptions for "I know the file."
 
**Why:** 50 "File has not been read yet" errors in the 30-day audit.
 
**How to apply:**
-Need to edit /path/file.ts → Read('/path/file.ts') first
-Creating new file → Write is fine without Read

NOT:

The user has experienced many issues with editing files...

Include Verifiable Examples

Vague rules don't change behavior. Show the diff:

## ✅ Use Read tool for file content
Read(file_path="/abs/path/file.ts")
 
## ❌ Don't use cat
Bash(cat file.ts)  # forbidden — use Read

Anchor in Evidence

Strong rules cite past incidents:

## Reason
"github_pat_*" plaintext file found on disk 2026-05-24 (5 months old).
See SECURITY-ACTIONS.md for incident details.

Without evidence, rules become "things the user once said" and decay.

Anti-Patterns

❌ Restating Generic Best Practices

# Code Quality
-Write clean code
-Use meaningful names
-Don't repeat yourself

This is noise. The agent already knows. Only write rules for things that are:

• Non-obvious
• Project-specific
• Counter to a common default
• Backed by an incident

❌ Time-Sensitive Information

# After August 2025, use the new auth library

Will rot. Instead:

# Auth library
Use @auth/v3. v2 deprecated; see ADR-0042 for migration.

❌ Mixed Concerns

A rule called everything.md covering security + style + git is unmaintainable. Split.

❌ Excessive Length

A 1000-line rule is no longer a rule — it's a manual. Either split or convert to a Skill.

Quality Checklist

• [ ] One concern per file
• [ ] Under 200 lines (or justified longer)
• [ ] Concrete examples (✅ / ❌)
• [ ] Rationale included (Why does this exist?)
• [ ] No time-sensitive info
• [ ] Specific enough that violations are detectable

Workflow

1. Verify need: Is this really a rule, or should it be:

• A Skill (on-demand behavior)?
• A Hook (programmatic enforcement)?
• A documentation note (one-time context)?

1. Pick scope (user vs. project)
2. Pick filename (kebab-case, single concern)
3. Write the rule (rule + why + how + examples)
4. Save to correct location
5. Verify auto-load (next session start should include it)

Auto-Load Verification

Rules in ~/.claude/rules/ are loaded via the auto-load mechanism (see CLAUDE.md reference to "13 auto-loaded rules"). When you add a new rule, the count in CLAUDE.md may need updating.

Examples From the User's Setup

Strong rules from ~/.claude/rules/:

• tool-discipline.md — Cites specific failure counts ("50 Edit-before-Read errors over 30 days")
• identity-config-check.md — References a hook (git-identity-check.sh) that enforces it
• api-cost-optimization.md — Backed by production evidence (a two-phase email triage pipeline)

The strongest rules in this codebase are derived from measured incidents, not abstract principles.

Related Skills

• [[create-skill]] — for behaviors that should load on-demand, not always
• [[create-hook]] — for programmatic enforcement (not just guidance)
• [[migrate-to-skills]] — for converting old rules-with-globs to Skills