name: managing-rules
description: Create, update, and organize Claude Code rules (.claude/rules/) following official best practices. Use when "create rule", "add rule", "ルール作成", "ルール追加", or configuring path-specific conventions.

Managing Claude Code Rules

Create and maintain rules that provide automatic, path-specific context to Claude.

When to Use

Automatically invoke when the user:
- Wants to "create a rule" or "add a rule"
- Says "ルール作成" or "ルール追加"
- Needs path-specific conventions (e.g., "rules for lib/ files")
- Wants to migrate from CLAUDE.md or skills to rules
- Mentions .claude/rules/

Recommended Architecture

Skills = Generic/Reusable, Rules = Project-Specific

.claude/
├── skills/                        # GENERIC (shareable across projects)
│   ├── nextjs-vibe-coding/
│   │   └── common/                # Reusable templates, patterns
│   ├── code-reviewing/
│   │   └── common/                # Reusable criteria, roles
│   └── managing-rules/            # This skill
│
└── rules/                         # PROJECT-SPECIFIC (auto-loaded)
    ├── tech-stack.md              # Versions for THIS project
    ├── lib-structure.md           # Structure rules for THIS project
    ├── server-actions.md          # Conventions for THIS project
    └── testing.md                 # Test patterns for THIS project

Why This Structure?

Migration from Skills project/ to Rules

Before (Skills project/ directory):

.claude/skills/nextjs-vibe-coding/
├── common/           # ✓ Keep (generic)
└── project/          # → Move to rules
    ├── reference/tech-stack.md
    ├── patterns/lib-structure.md
    └── issues/known-issues.md

After (Rules):

.claude/
├── skills/nextjs-vibe-coding/
│   └── common/       # Generic only
│
└── rules/            # Project-specific
    ├── tech-stack.md
    ├── lib-structure.md
    └── known-issues.md

Rules vs Skills vs CLAUDE.md

Use Rules when: Project-specific conventions that should auto-apply.
Use Skills when: Generic workflows reusable across projects.
Use CLAUDE.md when: Critical rules that must always apply.

Rule Structure

Basic Rule (No Path Filter)

# Code Style

- Use ES modules (import/export), not CommonJS
- Prefer const over let
- Use TypeScript strict mode

Loaded every session, applies to all files.

Path-Specific Rule

---
paths:
  - "lib/actions/**/*.ts"
  - "app/**/actions.ts"
---

# Server Actions Conventions

- Always verify authentication first
- Use CSRF protection
- Validate with Zod schemas
- Use revalidatePath after mutations

Only loaded when working with matching files.

Directory Structure

.claude/rules/
├── code-style.md          # Always loaded
├── testing.md             # Always loaded
├── server-actions.md      # paths: lib/actions/**
├── components.md          # paths: components/**
└── frontend/              # Subdirectories supported
    ├── react.md
    └── tailwind.md

User-Level Rules

~/.claude/rules/
├── preferences.md         # Personal coding preferences
└── workflows.md           # Personal workflows

User rules apply to all projects, loaded before project rules.

Workflow

Step 1: Determine Rule Type

Step 2: Choose Location

.claude/rules/
├── {topic}.md              # Single-topic rules
└── {category}/             # Related rules grouped
    └── {subtopic}.md

Naming: Use descriptive, kebab-case names.

Step 3: Write Rule Content

1. Read template:
   bash cat .claude/skills/managing-rules/templates/rule.md.template

2. Add frontmatter (if path-specific):
   ```yaml

paths:
- "src//*.ts"
- "lib//*.ts"

```

1. Write concise rules:
2. One topic per file
3. Bullet points preferred
4. Specific, actionable items
5. No verbose explanations

Step 4: Validate Glob Patterns

Step 5: Create File

mkdir -p .claude/rules
cat > .claude/rules/{name}.md << 'EOF'
---
paths:
  - "pattern/**/*.ext"
---

# Rule Title

- Rule 1
- Rule 2
EOF

Step 6: Verify

# List all rules
ls -la .claude/rules/

# Check rule content
cat .claude/rules/{name}.md

# View loaded rules in session
/memory

Glob Pattern Reference

Basic Patterns

Common Patterns

Best Practices

Do

• One topic per file: testing.md, api-conventions.md
• Use descriptive filenames: Name indicates content
• Be specific: "Use 2-space indentation" not "Format properly"
• Use paths sparingly: Only when rules truly apply to specific files
• Keep rules short: 10-30 lines per file

Don't

• Don't duplicate CLAUDE.md: Rules in both places cause confusion
• Don't overuse paths: Unconditional rules are simpler
• Don't write tutorials: Rules are reminders, not documentation
• Don't include temporary notes: Rules should be stable

Migration Guide

From CLAUDE.md to Rules

1. Identify file-specific sections in CLAUDE.md
2. Extract to separate rule files with appropriate paths
3. Keep global rules in CLAUDE.md
4. Test that rules load correctly

From Skill project/ to Rules

Current pattern:

.claude/skills/nextjs-vibe-coding/project/patterns/lib-structure.md

Better as rule:

.claude/rules/lib-structure.md

With frontmatter:

---
paths:
  - "lib/**/*.ts"
---

Symlinks for Sharing

Rules support symlinks for sharing across projects:

# Link shared rules directory
ln -s ~/shared-rules .claude/rules/shared

# Link individual rule
ln -s ~/company-standards/security.md .claude/rules/security.md

Quick Reference

# Create new rule
"create rule for {topic}"
"add rule for {file-pattern}"

# Path-specific rule
"create rule for Server Actions in lib/actions/"

# Migrate from CLAUDE.md
"extract testing rules from CLAUDE.md to rules/"

# List current rules
/memory

Templates

Notes

• Rules are loaded automatically - no invocation needed
• Path-specific rules only load when working with matching files
• User rules (~/.claude/rules/) load before project rules
• Subdirectories are recursively discovered
• Symlinks are resolved and loaded normally
• Use /memory to see what's currently loaded