claude-rules

# 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: ```markdown # 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: ```markdown # 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: ```markdown # .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/