Writing Best Practices
Create structured, maintainable best practices documentation that scales from quick reference to detailed guides.
Core Principle
Separate quick reference from comprehensive documentation.
When to Use
- Creating technical best practices guides
- Organizing reference documentation for teams or agents
- Building structured knowledge bases
- Documenting proven patterns and approaches
Don't use for:
- One-time documentation (use simple README)
- Project-specific notes (use CLAUDE.md)
- Narrative blog posts or tutorials
Quick Reference
| Topic | Rule File |
|---|---|
| Core structure and organization | structure |
| Frontmatter format | frontmatter |
| Impact levels | impact-levels |
| Validation and verification | validation |
| Writing individual rules | writing-rules |
| Code examples and patterns | code-examples |
| Quick reference tables | quick-reference |
| Maintenance and updates | maintenance |
| Common anti-patterns | anti-patterns |
Essential Structure
best-practice-name/
├── SKILL.md # Quick reference (human scan)
├── AGENTS.md # Full content (agent read)
└── rules/ # Modular rule files
├── rule-1.md
├── rule-2.md
└── ...
SKILL.md (2-3 pages):
- Overview and core principle
- When to use/not use
- Quick reference table
- Essential pattern code
- Red flags
- Link to full doc
AGENTS.md (complete compilation):
- All content in single document
- Generated or compiled from rules/
- Comprehensive with all details
rules/ (modular sections):
- One file per focused topic
- Mix of concept + examples
- Easy to update independently
Common Patterns
| Need | Pattern |
|---|---|
| Quick lookup | Table with rule file links |
| Deep understanding | AGENTS.md with all details |
| Specific topic | Individual rule file |
| Code variations | Tables instead of multiple examples |
Red Flags - STOP
| Anti-pattern | Fix |
|---|---|
| "Put everything in one file" | Use modular structure |
| "No need for quick reference" | Humans scan, agents read |
| "Five language examples" | One excellent example is enough |
| "Narrative style rules" | Use problem/solution format |
How to Use
Each rule file contains:
- Why the pattern matters
- ❌ Incorrect vs ✅ Correct examples
- Additional context and references
For the complete guide: AGENTS.md