545 lines
13 KiB
Markdown
545 lines
13 KiB
Markdown
# Community Best Practices for CLAUDE.md Configuration
|
|
|
|
> **Source**: Community wisdom, practitioner experience, and field-tested recommendations (not official Anthropic guidance)
|
|
|
|
This document contains best practices derived from the Claude Code community, real-world usage, and practical experience. While not officially mandated by Anthropic, these practices have proven effective across many projects.
|
|
|
|
---
|
|
|
|
## Size Recommendations
|
|
|
|
### Target Length: 100-300 Lines
|
|
|
|
**Rationale**:
|
|
- Represents approximately 1,500-4,500 tokens
|
|
- Accounts for roughly 1-2.5% of a 200K context window
|
|
- Small enough to avoid attention issues
|
|
- Large enough to be comprehensive
|
|
- Balances detail with context efficiency
|
|
|
|
**Community Consensus**:
|
|
- ✅ **Under 100 lines**: Potentially too sparse, may miss important context
|
|
- ✅ **100-300 lines**: Sweet spot for most projects
|
|
- ⚠️ **300-500 lines**: Acceptable for complex projects, but consider splitting
|
|
- ❌ **Over 500 lines**: Too verbose, consider using imports
|
|
|
|
**Note**: This is community-derived guidance, not an official Anthropic recommendation. Official guidance simply says "keep them lean."
|
|
|
|
### Token Budget Analysis
|
|
|
|
| CLAUDE.md Size | Tokens | % of 200K Context | Recommendation |
|
|
|----------------|--------|-------------------|----------------|
|
|
| 50 lines | ~750 | 0.4% | Too sparse |
|
|
| 100 lines | ~1,500 | 0.75% | Minimum viable |
|
|
| 200 lines | ~3,000 | 1.5% | Ideal |
|
|
| 300 lines | ~4,500 | 2.25% | Maximum recommended |
|
|
| 500 lines | ~7,500 | 3.75% | Consider splitting |
|
|
| 1000 lines | ~15,000 | 7.5% | Excessive |
|
|
|
|
---
|
|
|
|
## Content Organization
|
|
|
|
### Priority Positioning Strategy
|
|
|
|
Based on LLM research (not official Anthropic guidance), organize content by priority:
|
|
|
|
#### TOP Section (Highest Attention)
|
|
Place **mission-critical** standards here:
|
|
```markdown
|
|
# CRITICAL STANDARDS
|
|
|
|
## Security Requirements (MUST FOLLOW)
|
|
- Never commit secrets or API keys
|
|
- All authentication must use MFA
|
|
- Input validation required for all user inputs
|
|
|
|
## Code Quality Gates (MUST PASS)
|
|
- TypeScript strict mode enforced
|
|
- 80% test coverage minimum before PR merge
|
|
- No console.log in production code
|
|
```
|
|
|
|
#### MIDDLE Section (Lower Attention)
|
|
Place **nice-to-have** context and supporting information:
|
|
```markdown
|
|
## Nice-to-Have Practices
|
|
- Prefer functional components over class components
|
|
- Use meaningful variable names
|
|
- Keep functions under 50 lines when possible
|
|
```
|
|
|
|
#### BOTTOM Section (High Attention)
|
|
Place **important reference** information:
|
|
```markdown
|
|
## Key Commands (REFERENCE)
|
|
- npm run build: Build production bundle
|
|
- npm test: Run test suite
|
|
- npm run lint: Run linter
|
|
|
|
## Critical File Locations
|
|
- Config: /config/app.config.ts
|
|
- Types: /src/types/global.d.ts
|
|
```
|
|
|
|
**Rationale**: "Lost in the middle" research shows LLMs have U-shaped attention curves, with highest attention at the start and end of context.
|
|
|
|
---
|
|
|
|
## The 80/20 Rule for CLAUDE.md
|
|
|
|
### 80% Essential, 20% Supporting
|
|
|
|
**Essential (80%)** - Must-have information:
|
|
- Project-specific development standards
|
|
- Security requirements
|
|
- Testing requirements
|
|
- Critical file locations
|
|
- Common commands
|
|
- Non-obvious architectural decisions
|
|
|
|
**Supporting (20%)** - Nice-to-have context:
|
|
- Historical context
|
|
- Optional style preferences
|
|
- General best practices
|
|
- Team conventions
|
|
|
|
### Example Structure (200-line CLAUDE.md)
|
|
|
|
```markdown
|
|
# Project: MyApp
|
|
|
|
## CRITICAL STANDARDS (30 lines)
|
|
- Security requirements
|
|
- Must-follow coding standards
|
|
- Quality gates
|
|
|
|
## PROJECT CONTEXT (40 lines)
|
|
- Tech stack overview
|
|
- Architecture patterns
|
|
- Key dependencies
|
|
|
|
## DEVELOPMENT WORKFLOW (40 lines)
|
|
- Git workflow
|
|
- Testing requirements
|
|
- Deployment process
|
|
|
|
## CODE STANDARDS (30 lines)
|
|
- Language-specific rules
|
|
- Framework conventions
|
|
- Naming patterns
|
|
|
|
## COMMON ISSUES & SOLUTIONS (20 lines)
|
|
- Known gotchas
|
|
- Troubleshooting tips
|
|
|
|
## REFERENCE (40 lines)
|
|
- Common commands
|
|
- File locations
|
|
- Useful links
|
|
```
|
|
|
|
---
|
|
|
|
## Import Strategy
|
|
|
|
### When to Use Imports
|
|
|
|
#### Use Imports For:
|
|
- ✅ Lengthy architecture documentation (> 100 lines)
|
|
- ✅ Detailed API documentation
|
|
- ✅ Testing strategy documentation
|
|
- ✅ Deployment procedures
|
|
- ✅ Historical ADRs (Architecture Decision Records)
|
|
|
|
#### Keep in Main CLAUDE.md:
|
|
- ✅ Critical standards that must always be in context
|
|
- ✅ Common commands and workflows
|
|
- ✅ Project overview and tech stack
|
|
- ✅ Essential file locations
|
|
|
|
### Example Import Structure
|
|
|
|
```markdown
|
|
# CLAUDE.md (main file - 200 lines)
|
|
|
|
## Critical Standards (always in context)
|
|
- Security requirements
|
|
- Quality gates
|
|
- Testing requirements
|
|
|
|
## Project Overview
|
|
- Tech stack summary
|
|
- Architecture pattern
|
|
|
|
## Import Detailed Documentation
|
|
@docs/architecture/system-design.md
|
|
@docs/testing/testing-strategy.md
|
|
@docs/deployment/deployment-guide.md
|
|
@docs/api/api-documentation.md
|
|
@~/.claude/personal-preferences.md
|
|
```
|
|
|
|
**Benefits**:
|
|
- Keeps main CLAUDE.md lean
|
|
- Loads additional context on demand
|
|
- Easier to maintain separate documents
|
|
- Can reference external documentation
|
|
|
|
---
|
|
|
|
## Category Organization
|
|
|
|
### Recommended Section Structure
|
|
|
|
#### 1. Header & Overview (5-10 lines)
|
|
```markdown
|
|
# Project Name
|
|
Brief description of the project
|
|
Tech stack: React, TypeScript, Node.js, PostgreSQL
|
|
```
|
|
|
|
#### 2. Critical Standards (20-30 lines)
|
|
```markdown
|
|
## MUST-FOLLOW STANDARDS
|
|
- Security requirements
|
|
- Quality gates
|
|
- Non-negotiable practices
|
|
```
|
|
|
|
#### 3. Architecture (20-40 lines)
|
|
```markdown
|
|
## Architecture
|
|
- Patterns used
|
|
- Key decisions
|
|
- Module structure
|
|
```
|
|
|
|
#### 4. Development Workflow (20-30 lines)
|
|
```markdown
|
|
## Development Workflow
|
|
- Git branching strategy
|
|
- Commit conventions
|
|
- PR requirements
|
|
```
|
|
|
|
#### 5. Code Standards (30-50 lines)
|
|
```markdown
|
|
## Code Standards
|
|
- Language-specific rules
|
|
- Framework conventions
|
|
- Testing requirements
|
|
```
|
|
|
|
#### 6. Common Tasks (20-30 lines)
|
|
```markdown
|
|
## Common Tasks
|
|
- Build commands
|
|
- Test commands
|
|
- Deployment commands
|
|
```
|
|
|
|
#### 7. Reference Information (20-40 lines)
|
|
```markdown
|
|
## Reference
|
|
- File locations
|
|
- Environment setup
|
|
- Troubleshooting
|
|
```
|
|
|
|
---
|
|
|
|
## Version Control Best Practices
|
|
|
|
### Project-Level CLAUDE.md
|
|
|
|
#### Commit to Source Control
|
|
- ✅ **DO** commit `./CLAUDE.md` or `./.claude/CLAUDE.md` to git
|
|
- ✅ **DO** include in code reviews
|
|
- ✅ **DO** update alongside code changes
|
|
- ✅ **DO** document major changes in commit messages
|
|
|
|
#### Review Standards
|
|
```markdown
|
|
## PR Checklist for CLAUDE.md Changes
|
|
- [ ] Removed outdated information
|
|
- [ ] Added context for new features/patterns
|
|
- [ ] Updated commands if changed
|
|
- [ ] Verified no secrets committed
|
|
- [ ] Kept file under 300 lines
|
|
- [ ] Used imports for lengthy docs
|
|
```
|
|
|
|
### User-Level CLAUDE.md
|
|
|
|
#### Keep Personal Preferences Separate
|
|
- ✅ **DO** use `~/.claude/CLAUDE.md` for personal preferences
|
|
- ✅ **DO NOT** commit user-level files to project repos
|
|
- ✅ **DO** share useful patterns with team (move to project-level)
|
|
|
|
---
|
|
|
|
## Naming Conventions
|
|
|
|
### Section Headers
|
|
|
|
Use clear, action-oriented headers:
|
|
|
|
#### Good Examples:
|
|
```markdown
|
|
## MUST FOLLOW: Security Requirements
|
|
## How to Build and Deploy
|
|
## Common Troubleshooting Solutions
|
|
## File Structure Overview
|
|
```
|
|
|
|
#### Avoid:
|
|
```markdown
|
|
## Miscellaneous
|
|
## Other
|
|
## Notes
|
|
## TODO
|
|
```
|
|
|
|
### Emphasis Techniques
|
|
|
|
Use consistent emphasis for priority levels:
|
|
|
|
```markdown
|
|
## CRITICAL: [thing that must never be violated]
|
|
## IMPORTANT: [thing that should be followed]
|
|
## RECOMMENDED: [thing that's nice to have]
|
|
## REFERENCE: [lookup information]
|
|
```
|
|
|
|
---
|
|
|
|
## Maintenance Cadence
|
|
|
|
### When to Update CLAUDE.md
|
|
|
|
#### Update Immediately:
|
|
- New critical security requirements
|
|
- Major architecture changes
|
|
- New must-follow standards
|
|
- Breaking changes in workflow
|
|
|
|
#### Update During Sprint Planning:
|
|
- New features that introduce patterns
|
|
- Updated dependencies with new conventions
|
|
- Deprecated practices to remove
|
|
|
|
#### Update Quarterly:
|
|
- Remove outdated information
|
|
- Consolidate duplicate guidance
|
|
- Optimize length and structure
|
|
- Review for clarity
|
|
|
|
### Staleness Detection
|
|
|
|
Signs your CLAUDE.md needs updating:
|
|
- ⚠️ References to deprecated tools or frameworks
|
|
- ⚠️ Outdated command examples
|
|
- ⚠️ Broken file paths
|
|
- ⚠️ Conflicting instructions
|
|
- ⚠️ Information duplicated in multiple sections
|
|
|
|
---
|
|
|
|
## Multi-Project Strategies
|
|
|
|
### User-Level Patterns
|
|
|
|
For developers working across multiple projects:
|
|
|
|
```markdown
|
|
# ~/.claude/CLAUDE.md
|
|
|
|
## Personal Development Standards
|
|
- TDD approach required
|
|
- Write tests before implementation
|
|
- No console.log statements
|
|
|
|
## Preferred Tools
|
|
- Use Vitest for testing
|
|
- Use ESLint with recommended config
|
|
- Use Prettier with 2-space indent
|
|
|
|
## Communication Style
|
|
- Be concise and direct
|
|
- Provide context for decisions
|
|
- Flag breaking changes prominently
|
|
```
|
|
|
|
### Project-Level Focus
|
|
|
|
Each project's CLAUDE.md should:
|
|
- ✅ Override user-level preferences where needed
|
|
- ✅ Add project-specific context
|
|
- ✅ Define team-wide standards
|
|
- ❌ Avoid duplicating user-level preferences
|
|
|
|
---
|
|
|
|
## Testing Your CLAUDE.md
|
|
|
|
### Validation Checklist
|
|
|
|
#### Structure Test
|
|
- [ ] Under 300 lines (or using imports)
|
|
- [ ] Clear section headers
|
|
- [ ] Bullet points for lists
|
|
- [ ] Code blocks formatted correctly
|
|
|
|
#### Content Test
|
|
- [ ] No secrets or sensitive information
|
|
- [ ] Specific instructions (not generic)
|
|
- [ ] Project-specific context
|
|
- [ ] No outdated information
|
|
- [ ] No broken file paths
|
|
|
|
#### Effectiveness Test
|
|
- [ ] Start a new Claude Code session
|
|
- [ ] Verify standards are followed without re-stating
|
|
- [ ] Test that Claude references CLAUDE.md correctly
|
|
- [ ] Confirm critical standards enforced
|
|
|
|
---
|
|
|
|
## Advanced Techniques
|
|
|
|
### Conditional Instructions
|
|
|
|
Use clear conditions for context-specific guidance:
|
|
|
|
```markdown
|
|
## Testing Standards
|
|
|
|
### For New Features
|
|
- Write tests BEFORE implementation (TDD)
|
|
- Integration tests required for API endpoints
|
|
- Accessibility tests for UI components
|
|
|
|
### For Bug Fixes
|
|
- Add regression test that would have caught the bug
|
|
- Update existing tests if behavior changed
|
|
- Ensure fix doesn't break other tests
|
|
```
|
|
|
|
### Progressive Disclosure
|
|
|
|
Organize from high-level to detailed:
|
|
|
|
```markdown
|
|
## Architecture
|
|
|
|
### Overview
|
|
- Clean Architecture pattern
|
|
- Feature-based modules
|
|
- Hexagonal architecture for API layer
|
|
|
|
### Module Structure
|
|
├── features/ # Feature modules
|
|
│ ├── auth/ # Authentication feature
|
|
│ ├── dashboard/ # Dashboard feature
|
|
│ └── settings/ # Settings feature
|
|
├── lib/ # Shared libraries
|
|
└── infrastructure/ # Infrastructure layer
|
|
|
|
### Detailed Patterns
|
|
(Include or import detailed documentation)
|
|
```
|
|
|
|
---
|
|
|
|
## Anti-Patterns to Avoid
|
|
|
|
### Common Mistakes
|
|
|
|
#### ❌ Copy-Paste from Documentation
|
|
```markdown
|
|
## React Hooks
|
|
React Hooks allow you to use state and other React features
|
|
without writing a class...
|
|
[200 lines of React documentation]
|
|
```
|
|
**Problem**: Claude already knows this. Wastes context.
|
|
|
|
#### ❌ Excessive Detail
|
|
```markdown
|
|
## Git Workflow
|
|
1. First, open your terminal
|
|
2. Navigate to the project directory using cd
|
|
3. Type git status to see your changes
|
|
4. Type git add to stage files...
|
|
[50 lines of basic git commands]
|
|
```
|
|
**Problem**: Claude knows git. Be specific about YOUR workflow only.
|
|
|
|
#### ❌ Vague Instructions
|
|
```markdown
|
|
## Code Quality
|
|
- Write good code
|
|
- Make it clean
|
|
- Follow best practices
|
|
```
|
|
**Problem**: Not actionable. Be specific.
|
|
|
|
#### ✅ Better Approach
|
|
```markdown
|
|
## Code Quality Standards
|
|
- TypeScript strict mode: no `any` types
|
|
- Function length: max 50 lines
|
|
- Cyclomatic complexity: max 10
|
|
- Test coverage: minimum 80%
|
|
- No console.log in src/ directory (use logger instead)
|
|
```
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
### How to Know Your CLAUDE.md is Effective
|
|
|
|
#### Good Signs:
|
|
- ✅ Claude consistently follows your standards without prompting
|
|
- ✅ New team members onboard faster
|
|
- ✅ Fewer "why did Claude do that?" moments
|
|
- ✅ Code reviews show consistent patterns
|
|
- ✅ Standards violations caught early
|
|
|
|
#### Bad Signs:
|
|
- ❌ Constantly repeating yourself in prompts
|
|
- ❌ Claude ignores your standards
|
|
- ❌ Instructions are ambiguous
|
|
- ❌ Team members confused about standards
|
|
- ❌ CLAUDE.md conflicts with actual practices
|
|
|
|
---
|
|
|
|
## Real-World Examples
|
|
|
|
### Startup/Small Team (150 lines)
|
|
- Focus on essential standards
|
|
- Include critical workflows
|
|
- Prioritize speed over perfection
|
|
|
|
### Enterprise Project (250 lines + imports)
|
|
- Comprehensive security standards
|
|
- Detailed compliance requirements
|
|
- Links to additional documentation
|
|
- Multi-environment considerations
|
|
|
|
### Open Source Project (200 lines)
|
|
- Contribution guidelines
|
|
- Code review process
|
|
- Community standards
|
|
- Documentation requirements
|
|
|
|
---
|
|
|
|
**Document Version**: 1.0.0
|
|
**Last Updated**: 2025-10-26
|
|
**Status**: Community best practices (not official Anthropic guidance)
|
|
**Confidence**: Based on field experience and practitioner reports
|