CLAUDE.md Best Practices — Advanced Patterns

Auto-Run After Changes

After modifying any .ts file, run: npm run typecheck After modifying any test file, run: npm test -- --related

Context-Aware Rules

When working in /api/: Follow REST conventions, always validate input with Zod When working in /components/: Use Tailwind only, no CSS modules When working in /db/: Never modify migrations, always create new ones

## What Are Advanced CLAUDE.md Patterns?

Beyond basic project configuration, CLAUDE.md supports sophisticated patterns that make Claude Code behave like an expert team member. This guide covers conditional rules, hook integration, multi-file organization, team workflows, and project-specific intelligence that dramatically improves AI code generation quality.

**Answer-Ready**: Advanced CLAUDE.md patterns for Claude Code power users. Covers directory-scoped rules, auto-run commands, hook integration, team workflows, and project intelligence. Goes beyond basic config to make Claude Code a context-aware team member.

**Best for**: Claude Code power users optimizing their workflow. **Works with**: Claude Code (all versions).

## Pattern 1: Directory-Scoped Rules

```markdown
# Root CLAUDE.md
Global rules apply everywhere

# src/api/CLAUDE.md
When in this directory:
- All handlers must use the ApiResponse<T> wrapper
- Always validate request body with Zod schemas from /schemas/
- Log all errors with structuredLog()

# src/components/CLAUDE.md
When in this directory:
- Export components as named exports from index.ts barrel
- Every component needs a Storybook story
- Use cn() from @/lib/utils for conditional classes

Pattern 2: Auto-Run Commands

## Verification Commands

After ANY code change, run: `pnpm typecheck`
After changing test files, run: `pnpm test -- --related`
After changing API routes, run: `pnpm test:api`
After changing DB schema, run: `pnpm db:generate`

Pattern 3: Error Context

## Common Errors

If you see "Module not found @/...": Check tsconfig paths, we use @ for src/
If you see "EPERM" on Windows: File is locked by another process, retry
If tests fail with "connection refused": Run `docker compose up -d` first

Pattern 4: Architecture Decisions

## Why We Made These Choices

- tRPC over REST: Type safety across client/server boundary
- Drizzle over Prisma: Better raw SQL escape hatch, smaller bundle
- Zustand over Redux: Less boilerplate for our scale
- Date-fns over Day.js: Tree-shakeable, better TypeScript support

DO NOT suggest switching any of these without discussion.

Pattern 5: Code Patterns Library

## Patterns to Follow

### API Route Pattern
Every API route follows this structure:
1. Validate input (Zod)
2. Check auth (getSession)
3. Business logic
4. Return ApiResponse

### Component Pattern
Every component follows:
1. Props interface (exported)
2. Component function (named export)
3. Sub-components in same file if <30 lines
4. Extract to separate file if >30 lines

Pattern 6: Team Workflow

## Team Rules

- PRs must have tests for new features
- Breaking API changes need migration guide in PR description
- Database migrations require review from @backend-team
- Component changes need Storybook screenshot in PR

## Review Checklist for Claude

Before suggesting a PR is ready:
- [ ] All tests pass
- [ ] No TypeScript errors
- [ ] No new dependencies added without discussion
- [ ] Follows existing patterns in codebase

Pattern 7: Project Intelligence

## Domain Knowledge

- "User" in our system means the organization, not individual people
- "Credits" are consumed per API call, not per token
- "Workspace" is a logical grouping, not a separate database
- Price is always stored in cents (integer), displayed as dollars

Anti-Patterns (What NOT to Put)

# DON'T: Obvious things derivable from code
"We use TypeScript" — Claude can see tsconfig.json

# DON'T: Ephemeral task details
"Currently working on auth refactor" — use git branch for this

# DON'T: Documentation-length explanations
Keep it under 100 lines. Link to docs for details.

# DON'T: Contradictory rules
"Always use async/await" + "Use callbacks for performance"

FAQ

Q: How many CLAUDE.md files should I have? A: One in root for global rules. Add subdirectory ones only when that directory has genuinely different conventions.

Q: Do hooks replace CLAUDE.md rules? A: No, they complement. CLAUDE.md is instructions Claude reads. Hooks are shell commands the harness executes on events. Use hooks for enforcement, CLAUDE.md for guidance.

Q: Should I version control CLAUDE.md? A: Yes, always. It is a team asset that should evolve with the codebase.