Rules Management Skill

Rules Management Skill

Comprehensive guidance for managing CLAUDE.md user-specific rules with context-based loading for optimal performance.

Core Principle: Load What's Relevant

Claude Code loads CLAUDE.md on every interaction. To avoid loading all rules upfront:

1. Critical rules → Keep directly in CLAUDE.md (always loaded)
2. Context-specific rules → Move to .claude/rules/ with trigger hints (loaded on-demand)

Directory Structure

.claude/
├── CLAUDE.md                    # Critical rules + context hints
└── rules/                       # Domain-specific rules (loaded when relevant)
    ├── python.md
    ├── typescript.md
    ├── docker.md
    ├── react.md
    └── security-advanced.md

CLAUDE.md Structure (Always Loaded)

# Project Name

Brief project description.

## Critical Rules (Always Apply)

### Security
- Never commit secrets, API keys, or credentials
- Never disable security middleware or authentication checks
- Sanitize all user input before database operations

### Git Workflow
- Feature branches only, never commit directly to main
- Always run tests before committing

## Context (Read When Relevant)

Load context files based on what you're working on:

| Working On | Read |
|------------|------|
| Python/FastAPI backend | `.claude/rules/python.md` |
| React/TypeScript frontend | `.claude/rules/typescript.md` |
| Docker/containers | `.claude/rules/docker.md` |
| Authentication/security | `.claude/rules/security.md` |

What Goes Where?

Critical Rules (in CLAUDE.md)

Keep rules that are always relevant regardless of task:

• Security fundamentals (secrets, auth, input sanitization)
• Git workflow (branching, commits)
• Core project conventions (naming, structure)
• Communication preferences

Characteristics:

• Short and actionable
• Apply to 80%+ of tasks
• Safety-critical
• Never need context to understand

Context Files (in .claude/rules/)

Move rules that are domain-specific:

• Language-specific patterns (Python, TypeScript, Go)
• Framework conventions (React, FastAPI, Next.js)
• Tool configurations (Docker, Terraform, CI/CD)
• Detailed security practices

Characteristics:

• Only relevant for specific file types/tasks
• May be lengthy with examples
• Require specialized knowledge
• Not needed for every interaction

Context File Template

# [Technology/Domain] Context

Rules for [technology] development in this project.

## Key Patterns

- [Specific pattern or convention]
- [Another pattern]

## Examples

### Recommended
​```python
# Good example with explanation
​```

### Avoid
​```python
# Bad example with explanation why
​```

## Integration Points

- Related to: `.claude/context/[related].md` (when working with both)

Trigger Hints

The CLAUDE.md table tells Claude when to load context files from .claude/rules/:

Trigger Keywords	Context File
.py, Python, FastAPI, Pydantic	python.md
.ts, .tsx, React, Next.js	typescript.md
Docker, container, Dockerfile	docker.md
auth, JWT, OAuth, security audit	security.md
.go, Go, Gin, Echo	golang.md
database, SQL, migrations	database.md

Migration Guide

Before (All Loaded)

# CLAUDE.md

@rules/frontend/react.md
@rules/frontend/typescript.md
@rules/backend/python.md
@rules/backend/fastapi.md
@rules/devops/docker.md
@rules/security/auth.md
@rules/general/standards.md

Problem: All 7 files loaded on every interaction

After (Verrueckt Rules)

# CLAUDE.md

## Critical Rules
- Never commit secrets
- Feature branches only
- Run tests before commit

## Context (Read When Relevant)
| Working On | Read |
|------------|------|
| Python backend | `.claude/rules/python.md` |
| TypeScript/React | `.claude/rules/typescript.md` |
| Containers | `.claude/rules/docker.md` |

Improvement: Only load what's needed per task

Rule Priority

1. CLAUDE.md critical rules → Always apply
2. Loaded context files → Apply when read
3. Default best practices → Fall back when no rule exists

Best Practices

For Critical Rules

• Keep under 20 lines total
• Use bullet points, not paragraphs
• Focus on "never do" and "always do"
• No examples needed (rules should be self-evident)

For Context Files

• One technology/domain per file
• Include examples for complex patterns
• Reference related context files
• Keep under 200 lines per file

For Trigger Hints

• Use file extensions as triggers (.py, .tsx)
• Use technology keywords (Python, React)
• Use task keywords (auth, deploy, test)
• Be specific enough to avoid false matches

Commands Reference

Command	Purpose
/coconut-rules:add-rule [desc]	Add rule with auto-placement (critical vs context)
/coconut-rules:list-rules	Show current structure and loading pattern
/coconut-rules:organize	Restructure rules to context-based pattern