Initial commit

skills/claude-md-auditor/reference/best-practices.md

@@ -0,0 +1,121 @@
+# 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