writing-claude-directives

# Writing Claude Directives

## Core Principles

**1. Claude is smart.** Only write what it doesn't already know. Challenge each line: does this justify its token cost?

**2. Positive > Negative framing.** "Don't do X" triggers thinking about X (pink elephant problem). Say what TO do, not what to avoid.

```markdown
# Bad: triggers the behavior
Don't create duplicate files

# Good: directs to correct behavior
Update existing files in place
```

**3. Context motivates compliance.** Explain WHY, not just WHAT. Claude generalizes from motivation.

```markdown
# Less effective
NEVER use ellipses

# More effective
Your response will be read aloud by a text-to-speech engine, so never use ellipses since the TTS engine cannot pronounce them.
```

**4. Placement matters.** Instructions at prompt start and end receive higher attention. Critical rules go at boundaries.

**5. ~150 instruction limit.** More instructions = uniform degradation across ALL rules. Prune ruthlessly.

**6. Repetition enforces critical rules.** For high-stakes requirements, repeat with different framings.

## Token Efficiency

**Targets:**
- Frequently-loaded directives: <200 words
- Skills/CLAUDE.md: <500 lines total
- Reference --help instead of documenting flags
- Cross-reference other skills instead of repeating

**Progressive disclosure:** Main file is overview + links. Reference files load on-demand.

## Discovery (for Skills)

The `description` field determines if Claude finds your skill.

**Format:** Start with "Use when..." + specific triggers + what it does.

**Write in third person.** Injected into system prompt.

```yaml
# Bad: vague, first person
description: I help with async testing

# Good: triggers + action, third person
description: Use when tests have race conditions or timing dependencies - replaces arbitrary timeouts with condition polling
```

**Keywords:** Include error messages, symptoms, tool names Claude might search for.

## Compliance Techniques

Claude 4.x models are highly