Claude Code is a game-changing piece of techology but just having Claude Code installed isn't enough. It's like having the world's best sous chef but giving them no context about your kitchen, your recipes, or how you like things done. The magic happens when you structure your documentation and automation properly. This guide combines our lessons learned from months of iteration with Claude Code at Kasava, where we went from 0 to 87 CLAUDE.md files and built a system that actually works.

———

Part 1: Structuring and Maintaining CLAUDE.md Files

The Three-Tier System

1. Root CLAUDE.md- The project manifesto

2. Service-level CLAUDE.md - The domain expert

3. Component-level CLAUDE.md - The implementation guide

Root CLAUDE.md: The North Star

Your root CLAUDE.md is Claude's entry point to understanding your entire project. Think of it as the onboarding document for a new senior engineer. Here's the structure that works:

# Project Overview
[2-3 paragraphs max - what is this project and why does it exist]
## Technology Stack
[Bullet points - be specific about versions]
## Getting Started
[Quick setup commands - the "copy-paste to get running" section]
## Development Commands
[The commands developers run 20 times a day]
## Project Structure
[High-level directory overview - not every file]
## Key Features
[What makes this project special]
## Best Practices
[The non-negotiables for this codebase]
## Important Notes
[The gotchas that cost us hours to figure

Key insight: Keep it under 300 lines. Claude references the root file constantly but rarely needs encyclopedic detail there.

Service-Level CLAUDE.md: Where the Magic Happens

Instead of cramming everything into one file, create CLAUDE.md files for each major service or domain area:

• backend/src/processing/services/embeddings/CLAUDE.md

• backend/src/mastra/workflows/CLAUDE.md

• frontend/src/components/chat/CLAUDE.md

Each service-level file follows this pattern:

# Service Overview
[What this service does and why]
## Architecture
[How it fits into the larger system]
## Key Components
[The main classes/functions and their responsibilities]
## Usage Examples
[Real code examples from the codebase]
## Testing
[How to test this service]
## Common Issues
[The bugs we've hit and how to fix them]
## Performance Considerations
[What to watch out for at

Pro tip: Include actual file paths and line numbers for complex logic:

## Key Components
### EmbeddingService
Main orchestrator for all embedding operations
- Location: `src/processing/services/embeddings/EmbeddingService.ts`
- Key method: `generateEmbeddings()` (line 127) 
- handles batching
- Performance: Processes ~1000 embeddings/second with batching

Real-World Impact

Before structured CLAUDE.md:

• Me: "Add authentication to the chat endpoint"

• Claude: [Implements custom JWT logic]

• Me: "We already have auth middleware..."

• Time wasted: 15 minutes

After structured CLAUDE.md:

• Me: "Add authentication to the chat endpoint"

• Claude: "I'll use the existing auth middleware from middleware/auth.ts as documented"

• Time saved: 15 minutes

Anti-Patterns to Avoid

1. The Kitchen Sink - Don't dump your entire README, CONTRIBUTING, and wiki into CLAUDE.md

2. The Never-Updated Manifesto - Outdated context is worse than no context

3. The Novel - Bullet points and code examples beat lengthy descriptions

Pro Tips from the Trenches

1. Use IMPORTANT tags sparingly but effectively**

   IMPORTANT: Never call the database directly from routes - always use service layer

2. Include anti-patterns explicitly**
   

   ## DO NOT:
   - Import types from dist/ directory   
   - Use .forEach() for async operations   
   - Call external APIs without retry logic
   
   

3. Link related CLAUDE.md files
   
   

   ## Related Documentation
   - Database patterns: [`backend/src/db/CLAUDE.md`](../../db/CLAUDE.md)   
   - API routes: [`backend/src/routes/api/CLAUDE.md`](../../routes/api/CLAUDE.md)
   
   

4. Add performance benchmarks

     ## Performance Baselines
     - Repository indexing: ~10 files/second 
     - Embedding generation: ~1000/second with batching   
     - Database bulk insert: ~5000 records/second 
   
   

The CLAUDE_FILES_INDEX.md and Organization

The Master Index That Changes Everything

Having CLAUDE.md files scattered everywhere is great for context but terrible for discovery. Claude would sometimes miss critical documentation simply because it didn't know it existed. Enter the CLAUDE_FILES_INDEX.md.

The Index Structure

This single file revolutionized how Claude navigates our codebase. Think of it as Google's search index, but for your project's AI context:

The Automation That Saved Our Sanity

We implemented a system that doesn't just index CLAUDE.md files - it actively maintains them. When you use the /update command in Claude, the system automatically:

1. Scans for stale documentation - Identifies CLAUDE.md files that haven't been updated recently

2. Updates timestamps automatically- Refreshes the "Updated At" field in both files and index

3. Triggers content review - Flags files that may need content updates

4. Maintains index consistency - Ensures the index always reflects current state

This automated maintenance means documentation stays current without manual overhead. Claude always knows exactly where to look for context, and that context is always fresh.

Specialized Index Patterns

Beyond the basic file index, we've developed specialized indices:

The Feature Index

The Error Resolution Index

These specialized indices turn Claude from a code generator into a problem solver.

———

Key Takeaways

Documentation Best Practices

1. Hierarchy is King - Root → Service → Component structure mirrors how developers think

2. Keep it Concise - Root under 300 lines, service files focused on their domain

3. Real Examples Win - Include actual file paths, line numbers, and code snippets

4. Anti-patterns Matter - Explicitly state what NOT to do

5. Performance Context - Include benchmarks and baselines

Index and Organization

1. Central Index is Essential - CLAUDE_FILES_INDEX.md is your navigation hub

2. Automation is Non-negotiable - Manual index maintenance doesn't scale

3. Specialized Indices Add Value - Feature, error, and pattern indices solve specific problems

4. Timestamps Track Freshness - Know when documentation needs updating

The Bottom Line

Just like tests, CLAUDE.md files should be treated as living documents. It's not about writing more documentation - it's about writing the right documentation in the right places, where it is most relevant.
Start with your root CLAUDE.md. Keep it concise. Add service-level files as you work on different areas. Update them with your PRs. Automate your index. Build specialized indices as patterns emerge.
Most importantly, remember that these files aren't for you - they're for Claude to help you better. Every minute spent on proper documentation saves ten minutes of Claude going down the wrong path.

———

Based on real-world experience building [Kasava](https://kasava.ai) with a team that went from 0 to 87 CLAUDE.md files and lived to tell the tale.