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

## 快速使用

在 CLAUDE.md 中添加高级模式：目录范围规则、自动运行命令、架构决策记录。

## 什么是高级 CLAUDE.md 模式？

超越基础配置的 CLAUDE.md 进阶技巧，让 Claude Code 成为了解项目上下文的团队成员。

**一句话总结**：CLAUDE.md 进阶模式，目录范围规则 + 自动运行命令 + 错误上下文 + 架构决策 + 团队工作流 + 项目领域知识。

## 模式列表

1. 目录范围规则 — 不同目录不同规范
2. 自动运行命令 — 代码变更后自动检查
3. 错误上下文 — 常见错误的解决方案
4. 架构决策 — 为什么选了这个技术栈
5. 代码模式库 — 统一的代码结构模板
6. 团队工作流 — PR 和审查规则
7. 项目领域知识 — 业务概念定义

## 常见问题

**Q: 该有多少个 CLAUDE.md？**
A: 根目录一个全局的，子目录只在规范真的不同时加。

## 来源与致谢

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

---
Source: https://tokrepo.com/en/workflows/69b3cd5c-671c-4a2c-ae6b-5104bcc33465
Author: Skill Factory