claudecode-rules-organizing

Claude Rules Organizer

Extract file-type specific rules from CLAUDE.md into .claude/rules/ with dynamic loading via paths frontmatter for context optimization.

When to Use This Skill

• CLAUDE.md has file-type specific rules that can use dynamic loading
• Context optimization needed (large projects with many rules)
• Want to load API/frontend/testing rules only when relevant files are accessed
• Migrating from monolithic CLAUDE.md to dynamic rule loading

Note: If rules are universal (code style, git, build commands), keep them in CLAUDE.md. Only use .claude/rules/ for rules with paths for dynamic loading.

Core Concepts

Three Rule Methods (Priority Order)

Important: Context Consumption

Rules without paths consume context at startup, same as CLAUDE.md.

Key insight: Splitting rules into .claude/rules/ without paths provides no context savings. Only use rules/ for dynamic loading.

Dynamic Loading with paths

Rules with paths frontmatter load only when matching files are accessed:

---
paths: src/api/**/*.ts
---

# API Rules
- Input validation required
- Use standard error format

Reorganization Workflow

Step 1: Analyze Current CLAUDE.md

Categorize content:

Keep in CLAUDE.md (universal, always needed):

• Project overview
• Coding standards
• Git conventions
• Build commands

Move to rules/ (file-type specific, use paths):

• API conventions → rules/api.md (paths: src/api/**)
• Frontend rules → rules/frontend.md (paths: **/*.tsx)
• Testing rules → rules/testing.md (paths: **/*.test.ts)

Step 2: Create Modular Structure

.claude/
├── CLAUDE.md              # Overview + universal rules (code style, git, etc.)
└── rules/
    ├── api.md             # paths: src/api/**/* → dynamic
    ├── frontend/
    │   ├── react.md       # paths: **/*.tsx → dynamic
    │   └── styles.md      # paths: **/*.css → dynamic
    ├── testing.md         # paths: **/*.test.ts → dynamic
    └── backend/
        └── database.md    # paths: src/db/**/* → dynamic

Note: Universal rules (code style, git conventions) stay in CLAUDE.md. Only file-type specific rules go to rules/.

Step 3: Determine Where to Place Rules

Principle: Only move to .claude/rules/ if you can specify paths for dynamic loading.

Step 4: Migrate Content

For each topic:

1. Create new rule file with frontmatter
2. Move relevant content from CLAUDE.md
3. Add paths if file-type specific

Note: Do NOT add rule file references to CLAUDE.md. Dynamic rules with paths load automatically when matching files are accessed. Listing them in CLAUDE.md is redundant and wastes context.

Output Templates

Minimal CLAUDE.md Template

# Project Name

Brief project description.

## Quick Reference

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Key Files

| Purpose | Path |
|---------|------|
| Entry | src/index.ts |
| Config | config/ |

Important: Do NOT list .claude/rules/ files in CLAUDE.md. They load automatically via paths frontmatter. Adding references wastes startup context.

Rule File Template (Always use paths)

---
paths: src/api/**/*.ts
---

# API Development Rules

## Overview
Rules for API endpoint development.

## Standards

### Request Handling
- Validate all inputs
- Use typed request/response

### Error Handling
- Use standard error format
- Include error codes

Best Practices

DO

1. Keep universal rules in CLAUDE.md - Code style, git, build commands
2. Only use rules/ for dynamic loading - Always specify paths
3. One topic per rule file - api.md, react.md, not generic rules.md
4. Use descriptive filenames - Content should be obvious from name
5. Use subdirectories - Group related rules (frontend/, backend/)

DON'T

1. Don't split without paths - No context benefit, adds complexity
2. Don't over-fragment - 3-10 rule files is ideal
3. Don't duplicate - Reference shared rules, don't copy
4. Don't nest too deep - Max 2 levels of subdirectories

Verification

After reorganization:

1. Check startup load: Run claude and use /memory to verify only intended rules load
2. Test dynamic load: Read a file matching a paths pattern, confirm rule loads
3. Verify no duplicates: Second read of same file type should not reload rules
4. Check context: Use /context before and after to measure improvement

AI Assistant Instructions

When this skill is activated:

Analysis Phase

1. Read current CLAUDE.md completely
2. Identify topics: List distinct sections/concerns
3. Measure size: Count lines, estimate tokens
4. Check for @imports: Note external references
5. Present analysis to user with recommendations

Planning Phase

1. Propose structure: Show target file tree
2. Categorize rules:
   • Universal → Keep in CLAUDE.md
   • File-type specific → rules/ with paths
   • Directory-specific → rules/ with paths
3. Estimate impact: Context savings from dynamic loading
4. Get user approval before proceeding

Execution Phase

1. Create directories: .claude/rules/ and subdirs
2. Create rule files: One topic at a time
3. Update CLAUDE.md: Strip moved content only (do NOT add rule references)
4. Preserve @imports: Keep external references working
5. Show diff summary: What moved where

Verification Phase

1. List created files with line counts
2. Show new CLAUDE.md content
3. Provide test commands for verification
4. Suggest next steps if further optimization possible

Always

• Preserve all existing rules (no content loss)
• Maintain team compatibility (git-friendly)
• Use English for file contents
• Follow glob pattern standards
• Create backup recommendation before major changes

Never

• Delete rules without user confirmation
• Change rule semantics during migration
• Create circular @imports
• Create rule files without paths (use CLAUDE.md instead)
• Over-fragment into too many small files

Additional Resources

• Detailed Reference - Glob patterns, edge cases, troubleshooting
• Templates - Ready-to-use rule file templates