| name | writing-claude-directives |
| description | Use when writing or revising any instruction Claude will read - skills, CLAUDE.md files, agent prompts, system prompts, hook output. Covers token efficiency, compliance techniques, discovery, and per-format templates. |
Writing Claude Directives
Universal principles for any instruction Claude will read. For format-specific guidance, see:
- Skills: skills.md — naming, types, SKILL.md template, discovery
- CLAUDE.md: claude-md-files.md — top-level vs subdirectory, templates,
freshness dates
When the directive will involve shell commands, env vars, credentials, or git, also apply
prompt-security-hardening.
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.
# 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.
# Less effective
NEVER use ellipses.
# More effective
Your response will be read aloud by a TTS engine, which can't pronounce ellipses. Don't use them.
4. Placement matters. Instructions at prompt start and end receive higher attention. Critical
rules go at the 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
- Frequently-loaded directives: <200 words.
- Skills / CLAUDE.md: <500 lines total; subdirectory CLAUDE.md <100 lines.
- Reference
--help output instead of re-documenting flags.
- Cross-reference other skills instead of duplicating content.
- Progressive disclosure: main file is overview + links; reference files load on-demand.
Compliance Techniques
Claude 4.x is highly responsive to instructions. Lead with context and motivation; reserve
imperatives for true boundaries.
Primary: Context + Motivation
# Raw authority — easy to rationalize past
You MUST run tests before committing.
# Motivation — Claude generalizes
Run tests before committing. Untested commits break CI for the whole team and block other developers
from merging.
Secondary: Structural Enforcement
Make compliance the path of least resistance.
| Pattern | Example |
|---|
| Workflow steps | Numbered steps with verification gates |
| Task tracking (TaskCreate / TodoWrite) | Checklists without tracking get skipped |
| Forced commitment | "Announce: I'm using [skill]" |
| Explicit blocking | "If X happens, stop and do Y instead" |
Escalation: Imperatives — Sparingly
For Claude 4.x, aggressive language ("YOU MUST", "CRITICAL") can cause overtriggering. Reserve for
true boundaries:
# Often sufficient
Use this tool when searching for files.
# Reserve imperatives for hard boundaries
Never commit secrets to version control.
By Directive Type
| Type | Approach |
|---|
| Discipline (TDD, verification) | Context + structural enforcement + loophole closure |
| Technique (patterns, how-to) | Clear steps, "we want quality" framing |
| Reference (documentation) | Clarity only; no persuasion needed |
Structure Patterns
XML for Multi-Part Directives
Claude parses XML effectively — use it for multi-part directives:
<task>What to accomplish</task>
<constraints>Hard requirements</constraints>
<output_format>Expected structure</output_format>
<examples>Input/output pairs</examples>
XML also works as a format indicator:
<smoothly_flowing_prose>Write report sections here</smoothly_flowing_prose>
<structured_data>JSON or tables here</structured_data>
XML outperforms markdown, JSON, and YAML for rule preservation in long prompts.
Match Prompt Style to Desired Output
The formatting style in your prompt influences Claude's response. Include markdown if you want
markdown output; remove it for plain text.
Workflows and Feedback Loops
Break complex tasks into checkable steps:
- [ ] Step 1: Analyze inputs
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
Validate → fix → repeat:
1. Generate output
2. Run validator
3. If errors: fix and go to step 2
4. Only proceed when validation passes
Degrees of Freedom
Match specificity to fragility.
| Task type | Freedom | Style |
|---|
| Fragile operations | Low | Exact scripts, no modifications |
| Preferred patterns | Medium | Templates with parameters |
| Context-dependent | High | Principles and heuristics |
Action Bias Templates
<default_to_action>
By default, implement changes rather than only suggesting them. If the user's intent is unclear, infer the most useful likely action and proceed, using tools to discover any missing details instead of guessing.
</default_to_action>
<do_not_act_before_instructions>
Do not jump into implementation or change files unless clearly instructed. When the user's intent is ambiguous, default to providing information, doing research, and providing recommendations rather than taking action. Only proceed with edits when the user explicitly requests them.
</do_not_act_before_instructions>
Overengineering Prevention
Claude 4.x tends to overengineer. Drop this in when needed:
Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep
solutions simple and focused.
Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't
need surrounding code cleaned up. A simple feature doesn't need extra configurability.
Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal
code and framework guarantees. Only validate at system boundaries (user input, external APIs).
Don't create helpers, utilities, or abstractions for one-time operations. Don't design for
hypothetical future requirements. Reuse existing abstractions where possible.
Testing Directives (RED-GREEN-REFACTOR)
Writing directives is TDD applied to process documentation: write the failing test first, then the
directive, then close loopholes.
RED — baseline: run a pressure scenario WITHOUT the directive (combine pressures: time + sunk
cost + exhaustion). Document violations and rationalizations verbatim.
GREEN — minimal directive: address the specific baseline failures. Re-run scenarios WITH the
directive. Verify compliance.
REFACTOR — close loopholes: find new rationalizations that emerge under the directive. Add
explicit counters. Re-test until bulletproof.
| Type | Test approach | Success criterion |
|---|
| Discipline | Pressure scenarios, combined stressors | Follows rule under maximum pressure |
| Technique | Application scenarios, edge cases | Successfully applies to new scenario |
| Pattern | Recognition + counter-examples | Knows when/how AND when NOT to apply |
| Reference | Retrieval + application tests | Finds and correctly uses information |
Anti-Rationalization
For discipline-enforcing directives, anticipate excuses:
## Red Flags — STOP
If you find yourself reasoning any of these, you're rationalizing:
- "This is simple enough to skip"
- "I already tested manually"
- "The spirit not the letter"
- "This case is different"
All mean: follow the process.
Common Mistakes
| Mistake | Fix |
|---|
| Verbose explanations | Claude knows the basics — omit |
| Multiple valid approaches | Pick one default, escape hatch for edge cases |
| Vague triggers | Specific symptoms: "tests flaky", "race condition" |
| Deeply nested references | Keep one level deep from main file |
| Windows paths | Always forward slashes |
| Aggressive language for 4.x | Lead with context, reserve imperatives for boundaries |
| Narrative examples ("In session 2025-10-03 we found...") | Too specific, not reusable |
Multi-language dilution (example-js.js, example-py.py) | Pick one language, do it well |
| Code in flowcharts | Can't copy-paste; use code blocks |
Generic labels (helper1, step3) | Use semantic names |
Model-Specific Notes
Opus 4.5 — "think" sensitivity: when extended thinking is disabled, Opus 4.5 is sensitive to the
word "think" and variants. Replace with:
- "consider" instead of "think about"
- "evaluate" instead of "think through"
- "determine" instead of "think whether"
Checklist
Before publishing any directive:
For skills, also see skills.md. For CLAUDE.md, also see
claude-md-files.md.
