# CLAUDE.md Best Practices — Advanced Patterns

> Advanced CLAUDE.md patterns for Claude Code power users. Covers hook integration, multi-directory configs, conditional rules, and team workflow optimization techniques.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

Add these advanced patterns to your `CLAUDE.md`:

```markdown
# Advanced CLAUDE.md 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

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

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

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

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

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

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

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

## Source & Thanks

> - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
> - Community patterns from [awesome-claude-md](https://github.com/anthropics/claude-code)

<!-- ZH -->

## Quick Use

Add advanced patterns to CLAUDE.md: directory-scoped rules, auto-run commands, architecture decision records.

## What Are Advanced CLAUDE.md Patterns?

Patterns that go beyond basic config, turning Claude Code into a team member who understands the project's context.

**TL;DR**: Advanced CLAUDE.md patterns. Directory-scoped rules + auto-run commands + error context + architecture decisions + team workflows + project domain knowledge.

## Pattern List

1. Directory-scoped rules — different conventions per directory
2. Auto-run commands — automatic checks after code changes
3. Error context — solutions to common errors
4. Architecture decisions — why this stack was chosen
5. Code-pattern library — unified code-structure templates
6. Team workflows — PR and review rules
7. Project domain knowledge — business concept definitions

## FAQ

**Q: How many CLAUDE.md files should I have?**
A: One global at the root; add subdirectory ones only when conventions truly differ.

## Source & Thanks

> [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code)

---
Source: https://tokrepo.com/en/workflows/claude-md-best-practices-advanced-patterns-69b3cd5c
Author: Anthropic