Claude Rules Authoring

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

Rules vs CLAUDE.md

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

1. •Identify the convention scope (formatting, testing, commits, etc.)
2. •Create TOPIC.md in .claude/rules/
3. •Write scannable content with tables, do/don't lists
4. •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/