config-audit/skills/config-hierarchy/references/rules-directory.md

.claude/rules/ Directory Reference

Purpose

The .claude/rules/ directory allows modular organization of instructions with optional path scoping.

Location

project/
├── .claude/
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── api.md
└── CLAUDE.md

File Format

Each rule file is a markdown file with optional frontmatter:

---
paths: ["src/**/*.ts", "src/**/*.tsx"]
description: TypeScript code style rules
---

# TypeScript Rules

## Formatting
- Use 2-space indentation
- Prefer single quotes

## Types
- Always use explicit types for function parameters
- Avoid `any` type

Frontmatter Options

paths (Official) / globs (Legacy)

Array of glob patterns that scope when this rule applies.

Official field name: paths: (as per Claude Code documentation) Legacy/alternative: globs: (also supported for backwards compatibility)

Both fields behave identically - use paths: for new rules:

---
paths: ["src/**/*.ts"]  # Official - Only for TypeScript in src/
---

---
globs: ["src/**/*.ts"]  # Legacy - Still works, but prefer paths:
---

---
paths: ["tests/**/*", "**/*.test.ts"]  # Test files anywhere
---

If no paths/globs specified, rule applies everywhere.

Note: Config-audit normalizes both to patterns internally and tracks which field was used via pattern_source.

description

Brief description of what the rule covers:

---
description: Code formatting and style preferences
---

alwaysApply

Force rule to always be included regardless of current file:

---
alwaysApply: true
---

Loading Behavior

1. Rules are loaded when entering relevant directories
2. Glob patterns are matched against current file/directory
3. Matching rules are included in context
4. Non-matching rules are not loaded

Example Rules

code-style.md

---
paths: ["src/**/*"]
description: Source code style
---

# Code Style

- TypeScript > JavaScript
- Explicit types for public API
- Document exported functions

testing.md

---
paths: ["tests/**/*", "**/*.test.ts", "**/*.spec.ts"]
description: Testing guidelines
---

# Testing

- Use Jest for unit tests
- Descriptive test names
- Arrange-Act-Assert pattern

api.md

---
paths: ["src/api/**/*", "src/routes/**/*"]
description: API development rules
---

# API Guidelines

- RESTful conventions
- Validate all inputs
- Consistent error responses

Best Practices

1. Split by concern: One rule file per topic
2. Use specific globs: Avoid overly broad patterns
3. Keep rules focused: 200-500 words per file
4. Document purpose: Use description frontmatter
5. Review periodically: Remove outdated rules

Migration from CLAUDE.md

To convert from monolithic CLAUDE.md to rules:

1. Identify distinct sections in CLAUDE.md
2. Create rule file for each section
3. Add appropriate globs
4. Remove sections from CLAUDE.md
5. Test that rules load correctly

Debugging

To see which rules are loaded:

• Check Claude Code logs
• Rules appear in context when relevant files are active