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