122 lines
2.7 KiB
Markdown
122 lines
2.7 KiB
Markdown
# Community Best Practices
|
||
|
||
Field-tested recommendations from practitioners. These are suggestions, not requirements.
|
||
|
||
## Size Recommendations
|
||
|
||
### Target Range
|
||
- **Optimal**: 100-300 lines
|
||
- **Acceptable**: Up to 500 lines with @imports
|
||
- **Warning**: > 500 lines indicates need for splitting
|
||
|
||
### Token Budget
|
||
- **Recommended**: < 3,000 tokens
|
||
- **Maximum**: 5,000 tokens before significant context cost
|
||
- **Measure**: Use `wc -w` as rough estimate (tokens ≈ words × 1.3)
|
||
|
||
## Content Organization
|
||
|
||
### 80/20 Rule
|
||
- 80% essential, immediately-applicable guidance
|
||
- 20% supporting context and edge cases
|
||
|
||
### Section Priority
|
||
1. **Critical** (MUST follow): Security, breaking patterns
|
||
2. **Important** (SHOULD follow): Core standards, conventions
|
||
3. **Recommended** (COULD follow): Optimizations, preferences
|
||
|
||
### Header Hierarchy
|
||
```markdown
|
||
# Project Name
|
||
## Build Commands (most used first)
|
||
## Architecture Overview
|
||
## Coding Standards
|
||
## Testing Requirements
|
||
## Common Patterns
|
||
```
|
||
|
||
## Import Strategies
|
||
|
||
### When to Import
|
||
- Detailed documentation > 50 lines
|
||
- Shared standards across projects
|
||
- Frequently updated content
|
||
|
||
### Import Organization
|
||
```markdown
|
||
## Core Standards
|
||
@standards/typescript.md
|
||
@standards/testing.md
|
||
|
||
## Project-Specific
|
||
@docs/architecture.md
|
||
@docs/api-patterns.md
|
||
```
|
||
|
||
## Version Control Practices
|
||
|
||
### Commit Discipline
|
||
- Commit CLAUDE.md changes separately
|
||
- Use descriptive messages: "docs: update testing standards in CLAUDE.md"
|
||
- Review in PRs like any other code
|
||
|
||
### Change Tracking
|
||
```markdown
|
||
---
|
||
**Last Updated**: 2025-10-26
|
||
**Version**: 1.2.0
|
||
**Changes**: Added memory retrieval patterns
|
||
---
|
||
```
|
||
|
||
## Maintenance Cadence
|
||
|
||
### Regular Reviews
|
||
- **Weekly**: Check for outdated commands
|
||
- **Monthly**: Review against actual practices
|
||
- **Quarterly**: Full audit and optimization
|
||
|
||
### Staleness Indicators
|
||
- Commands that no longer work
|
||
- References to removed files
|
||
- Outdated dependency versions
|
||
- Patterns no longer used
|
||
|
||
## Multi-Project Strategies
|
||
|
||
### Shared Base
|
||
```
|
||
~/.claude/CLAUDE.md # Personal defaults
|
||
~/.claude/standards/ # Shared standards
|
||
├── typescript.md
|
||
├── testing.md
|
||
└── security.md
|
||
```
|
||
|
||
### Project Override
|
||
```markdown
|
||
# Project CLAUDE.md
|
||
|
||
## Override user defaults
|
||
@~/.claude/standards/typescript.md
|
||
|
||
## Project-specific additions
|
||
...
|
||
```
|
||
|
||
## Anti-Pattern Avoidance
|
||
|
||
### Don't Duplicate
|
||
- If it's in official docs, don't repeat it
|
||
- If it's in your codebase comments, reference don't copy
|
||
|
||
### Don't Over-Specify
|
||
- Trust Claude's knowledge
|
||
- Focus on YOUR project's quirks
|
||
- Specify deviations from standards, not standards themselves
|
||
|
||
### Don't Neglect Updates
|
||
- Outdated CLAUDE.md is worse than none
|
||
- Schedule regular maintenance
|
||
- Delete rather than leave stale
|