Writing Best Practices

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

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

Red Flags - STOP

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