Claude Rules Authoring

Create reusable instruction files in .claude/rules/ for project conventions.

Rules vs CLAUDE.md

Aspect	CLAUDE.md	.claude/rules/
Loading	Automatic at session start	On-demand via reference
Content	Project setup, key commands	Reusable conventions
Size	Concise (~200-500 lines)	Can be detailed
Scope	This specific project	Patterns across files

Put in CLAUDE.md: One-off instructions, project-specific commands, key file locations.

Put in rules/: Formatting conventions, architecture patterns, workflow guidelines, commit standards.

File Conventions

Naming

UPPERCASE.md - All caps with .md extension
Topic-focused - One concern per file
Kebab-case for multi-word - API-PATTERNS.md, CODE-REVIEW.md

Good: FORMATTING.md, TESTING.md, COMMITS.md Bad: formatting.md, MyRules.md, everything.md

Structure

.claude/rules/
├── FORMATTING.md      # Code style, output conventions
├── TESTING.md         # Test patterns, coverage requirements
├── COMMITS.md         # Commit message format, PR conventions
├── ARCHITECTURE.md    # Component structure, file organization
└── SECURITY.md        # Security guidelines, auth patterns

Content Structure

Rules files should be scannable and actionable:

# Topic Name

Brief description of what this covers.

## Section 1

| Pattern | Example | Notes |
|---------|---------|-------|
| ... | ... | ... |

## Section 2

**Do:**
- Specific guideline

**Don't:**
- Anti-pattern to avoid

## Examples

{ concrete examples }

Referencing Rules

From CLAUDE.md

Reference rules explicitly - they're not auto-loaded:

# CLAUDE.md

## Code Style
Follow `.claude/rules/FORMATTING.md` for all code conventions.

## Testing
See `.claude/rules/TESTING.md` for TDD patterns.

Cross-file References

Use @ syntax to include content from other files:

# .claude/rules/FORMATTING.md

@./project-specific/FORMATTING.md

This keeps rules DRY by pointing to authoritative sources.

Plugin Shared Rules

Plugins can organize shared rules internally:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md      # Can reference ../../rules/FORMATTING.md
└── rules/
    ├── FORMATTING.md
    └── PATTERNS.md

Important limitation: Shared rules only work WITHIN a single plugin. When plugins are installed, Claude Code copies them to a cache directory. Paths that traverse outside the plugin root (like ../other-plugin/rules/) won't work after installation.

For cross-plugin patterns: Use skill invocation instead of file references. Reference related skills by name (e.g., "load the outfitter:formatting skill") rather than file paths.

Quick Start

Create a New Rule

Identify the convention scope (formatting, testing, commits, etc.)
Create TOPIC.md in .claude/rules/
Write scannable content with tables, do/don't lists
Reference from CLAUDE.md

Validate a Rule

Filename is UPPERCASE.md
Single focused topic
Scannable structure (tables, lists)
Referenced from CLAUDE.md
No duplicate content with CLAUDE.md

Anti-Patterns

Don't:

Create rules for one-off instructions (use CLAUDE.md)
Duplicate content between CLAUDE.md and rules/
Create catch-all files like EVERYTHING.md
Expect rules to auto-load (they must be referenced)

Do:

Keep each rule file focused on one topic
Use tables and lists for scannability
Reference shared rules via @ when available
Document why, not just what

Related Skills

claude-code-configuration - CLAUDE.md and settings.json
claude-plugin-development - Plugin structure including rules/

claude-rules