Advanced CLAUDE.md Patterns

Beyond the basic CLAUDE.md covered in Context Awareness, there are advanced patterns for larger projects and teams.

Nested CLAUDE.md Files

Claude reads CLAUDE.md files hierarchically. When working in a subdirectory, Claude sees:

1. Root CLAUDE.md
2. Any CLAUDE.md in parent directories
3. The CLAUDE.md in the current directory

• CLAUDE.md (root - project overview)
• Directoryapp/

  • CLAUDE.md (app-specific patterns)
  • Directorymodels/

    • CLAUDE.md (model conventions)
  • Directoryroutes/

    • …
• Directorytests/

  • CLAUDE.md (testing patterns)

When to Use Nested Files

Use nested CLAUDE.md files when:

• A directory has unique conventions
• A subsystem has complex patterns
• Different team members own different parts
• You want to keep the root file small

Example: Nested Structure

Root CLAUDE.md:

# MyProject
E-commerce platform with microservices architecture.

Tech Stack: Python 3.11, FastAPI, PostgreSQL, Redis
Structure: services/ (microservices), web/ (frontend), shared/ (libraries)

services/CLAUDE.md:

# Services
Each service: app/, tests/, Dockerfile, requirements.txt
Use gRPC for sync calls, RabbitMQ for async
Database migrations: `alembic upgrade head`

services/payments/CLAUDE.md:

# Payments Service ⚠️
Handles money - extra care required.

Stripe: Verify webhook signatures, use idempotency keys
Testing: Stripe test mode, mock external calls
Security: Never log card numbers, PCI compliance required

Dynamic Content

You can include dynamic information that Claude should know about:

# Current Sprint

## Active Work
- [ ] Implement rate limiting (#234)
- [ ] Fix payment webhook retry (#256)
- [x] Add user export feature (#201)

## Do Not Touch
- `legacy/` folder - deprecated, being removed Q2
- `services/auth/` - being refactored by Auth team

## Recent Decisions
- 2026-01-03: Switched from REST to gRPC for internal calls
- 2026-01-01: Adopted Pydantic v2 for all new models

Tips for Effective CLAUDE.md Files

1. Keep It Current

Stale documentation is worse than none. Update when:

• Architecture changes
• New conventions are adopted
• Problems are discovered

2. Be Prescriptive

Good ✓

## Error Handling
All API endpoints must return errors as:
```json
{"error": "message", "code": "ERROR_CODE"}

Use exceptions from app.exceptions.

</TabItem>
<TabItem label="Bad ✗">
```markdown
## Error Handling
Handle errors appropriately.

3. Explain the Why

## Why We Don't Use ORMs for Reports

Report queries are complex and performance-critical.
Raw SQL gives us:
- Better query optimization
- Easier debugging
- No ORM overhead

Use SQLAlchemy for CRUD, raw SQL for reports.

4. Include Non-Obvious Patterns

## Soft Deletes

We use soft deletes for compliance. Never use DELETE:

  # Wrong
  db.session.delete(user)

  # Right
  user.deleted_at = datetime.utcnow()

All queries must filter: where deleted_at IS NULL

.claude/ Directory

For more complex configurations, use a .claude/ directory:

• Directory.claude/

  • settings.json (Claude Code settings)
  • Directorycommands/ (custom slash commands)

    • deploy.md
    • review.md

Note

We’ll cover custom slash commands in the Slash Commands guide.

Organizing Rules with .claude/rules/

For larger projects, organize memory into multiple rule files:

.claude/
├── CLAUDE.md              # Main project memory
└── rules/
    ├── api-conventions.md
    ├── testing-standards.md
    ├── security-rules.md
    └── frontend-patterns.md

All .md files in .claude/rules/ are automatically loaded. This separates concerns, simplifies maintenance, and makes code review easier.

Path-Scoped Rules

Apply rules only to specific files using YAML frontmatter:

---
paths:
  - src/components/**/*.py
---

# Component Rules

- Use class-based components
- Define type hints for all parameters
- Follow project naming conventions

Patterns use glob syntax: src/**/*.py matches all Python files under src/, tests/** matches everything under tests/, etc.

Example: Backend vs Frontend Rules

.claude/rules/backend.md:

---
paths: [src/api/**, src/services/**]
---

# Backend Rules
- Use dependency injection
- Require authentication middleware
- Return standardized errors

.claude/rules/frontend.md:

---
paths: [src/components/**, src/pages/**]
---

# Frontend Rules
- Use React Query for data fetching
- Implement loading and error states
- Use CSS modules

Rules only apply when editing files matching their paths.

Importing External Files

Reference other markdown files using the @ import syntax:

CLAUDE.md

@docs/api-reference.md
@docs/database-schema.md
@shared/company-standards.md

Paths are relative to the importing file. Imported files can import others (circular imports are prevented).

Note

External imports require approval before loading into context.

Quick Memory Additions

Add temporary notes to session memory by starting your input with #:

# Remember: the auth service is currently broken, work around it

Now implement the user profile feature

Use this for temporary workarounds (# The staging API is down), session context (# Working on JIRA-123), or quick reminders (# Don't modify legacy/). Persists for current session only.

CLAUDE.md vs Other Documentation

Document	Purpose	Audience
CLAUDE.md	Claude-specific context	Claude Code
README.md	Project introduction	Humans (new developers)
CONTRIBUTING.md	How to contribute	Human contributors
docs/	Full documentation	Everyone

CLAUDE.md can reference other docs:

## Architecture
See `docs/architecture.md` for full details.
For Claude: focus on the service layer pattern.