# Rules Management

> This skill provides guidance on organizing CLAUDE.md rules, category structures, and rule file best practices. Use when the user asks about 'how to organize Claude rules', 'CLAUDE.md structure', 'rule categories', 'rules best practices', or needs help understanding the rules system.

- Skill: `francisvarga/rules-management` (Agent Skill)
- Install (CLI): `npx skillmds@latest add francisvarga/rules-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/francisvarga/rules-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: FrancisVarga (https://skillmd.com/u/francisvarga)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/francisvarga/rules-management

---


# 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)

```markdown
# 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

```markdown
# [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)
```markdown
# 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)
```markdown
# 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 |