Initial commit
This commit is contained in:
Zhongwei Li
544
skills/claude-md-auditor/reference/best_practices.md
Normal file
544
skills/claude-md-auditor/reference/best_practices.md
Normal file
@@ -0,0 +1,544 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user