Path Rules in Practice — Real-World Rule Design

Core 6 min +25 XP

💡

THE ANALOGY

Smart building access control. Different rooms have different access rules — the server room has stricter requirements than the cafeteria. Path-specific rules apply different Claude Code guidelines to different parts of your codebase automatically.

⚠️ EXAM TRAP — The Wrong Answer People Choose

Writing rules so broad they're equivalent to project-level CLAUDE.md, or so narrow they almost never activate. The power of path-specific rules is precision — the right guidance, at the right time, for the right files.

KEY POINTS

1 Rules should be as specific as possible — the more targeted, the more useful.

2 Multiple rules can apply to the same file if its path matches multiple patterns — all active rules are combined.

3 Rule files should be focused on the specific concerns of that file type — not general project conventions.

4 Test your glob patterns — a rule with a broken pattern never loads, and you won't know unless you test it.

5 Rules are additive — they supplement project-level CLAUDE.md, not replace it.

Three Focused Rules for a Next.js Project

# .claude/rules/api-routes.yaml
---
paths:
  - "app/api/**/*.ts"
  - "pages/api/**/*.ts"
description: "Next.js API route conventions"
---

# API Route Rules

- All routes must validate request body with Zod before processing
- Use NextResponse.json() for all responses, never Response directly
- Authentication check must be first action in every protected route
- Rate limiting applied via middleware, not in route handler
- Error responses always include: {error: string, code: string}
- Log all errors to structured logger before returning 500 response

# .claude/rules/react-components.yaml
---
paths:
  - "components/**/*.tsx"
  - "app/**/*.tsx"
  - "!app/api/**"              # Exclude API routes
  - "!**/*.test.tsx"           # Exclude test files
description: "React component conventions"
---

# React Component Rules

## Component Structure
- One component per file
- Named export, not default (except page components)
- Props interface defined directly above component

## State Management
- Local state: useState for UI state
- Server state: React Query for async data
- Global state: Zustand store (see stores/ directory)
- No Redux — we migrated away from it

## Accessibility
- All images have alt text
- Interactive elements are keyboard navigable
- Color is never the only information conveyor

# .claude/rules/migrations.yaml
---
paths:
  - "migrations/**/*.sql"
  - "migrations/**/*.ts"
  - "db/migrations/**"
description: "Database migration rules"
---

# Migration Rules — CRITICAL

## Never
- Never modify an existing migration file after it has been run in production
- Never use raw string concatenation in SQL
- Never drop columns without a separate migration with a grace period

## Always
- New migrations must be additive or have a rollback plan
- Include both UP and DOWN operations
- Test migration on a copy of production data before merging
- Get review from a senior engineer before merging any migration

## Naming Convention
YYYY_MM_DD_HHMM_description_of_change.sql
Example: 2024_11_22_1430_add_refund_amount_to_orders.sql

Testing Glob Patterns

Before deploying rules, verify patterns work:

# Test which files match your pattern
find . -path "./app/api/**/*.ts" | head -20
find . -name "*.test.tsx" | head -20

# Verify exclusion works
find . -path "./components/**/*.tsx" ! -path "./**/*.test.tsx" | head -20

Key Takeaways

Rules are focused — specific to the concerns of that file type
Rules are additive — they add to, not replace, project-level CLAUDE.md
Multiple rules can apply to one file — all matching patterns load
Test glob patterns before committing — broken patterns load silently
Exclusion patterns prevent overlap between rule types