# .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:

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

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

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

```yaml
---
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:

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

### alwaysApply

Force rule to always be included regardless of current file:

```yaml
---
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

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

# Code Style

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

### testing.md

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

# Testing

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

### api.md

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