token-efficiency

Token Efficiency

Reduce output token waste and prevent iteration cycles that consume context.

Trigger

Use when:

• Sessions feel expensive or slow
• Output is verbose with filler text
• Claude is re-reading files or iterating unnecessarily
• Setting up a new project for token-efficient work

Anti-Sycophancy Rules

These patterns waste 30-60% of output tokens:

| Pattern | Example | Fix | |---------|---------|-----| | Sycophantic opener | "Sure! Great question!" | Delete. Lead with answer. | | Prompt restatement | "You're asking about X..." | Delete. Answer directly. | | Closing fluff | "Let me know if you need anything!" | Delete. Stop after the answer. | | Unsolicited suggestions | "You might also want to..." | Delete unless asked. | | AI disclaimers | "As an AI model..." | Delete entirely. | | Verbose preambles | "I'll help you with that..." | Delete. Start with the action. |

Tool-Call Budgets

Set explicit budgets by task complexity:

| Task Type | Tool-Call Budget | Wrap-Up At | |-----------|-----------------|------------| | Quick fix / lookup | 20 calls | 15 | | Bug fix | 30 calls | 25 | | Feature (small) | 50 calls | 40 | | Feature (large) | 80 calls | 65 | | Refactor | 50 calls | 40 | | Exploration / research | 30 calls | 25 |

At the wrap-up threshold: commit progress, assess remaining work, decide whether to continue or start fresh.

One-Pass Coding Discipline

For simple-to-medium tasks:

1. Read all relevant files including tests first
2. Understand what tests assert before coding
3. Write complete solution in one pass — not incrementally
4. Run tests once — if pass, STOP immediately
5. If fail: read the error, fix once, retest
6. Never iterate more than twice on the same failure — rethink approach
7. Never refactor, improve, or polish passing code

Task Profiles

Switch profiles based on what you're doing:

Coding Profile

• Return code first, explanation after (only if non-obvious)
• Simplest working solution, no over-engineering
• Read file before modifying — always
• No docstrings on unchanged code
• No error handling for impossible scenarios
• State bug, show fix, stop

Agent/Pipeline Profile

• Structured output only: JSON, bullets, tables
• No prose unless targeting a human reader
• Every output must be parseable without post-processing
• Execute task, do not narrate actions
• Never invent file paths, API endpoints, or function names
• If unknown: return null or "UNKNOWN", never guess

Analysis Profile

• Lead with finding, context and methodology after
• Tables and bullets over prose
• Numbers must include units
• Never fabricate data points
• Summary first (3 bullets max), caveats last

Read-Before-Write Enforcement

Hard rules:

1. Never write a file you haven't read in this session
2. Never re-read a file already read unless it was modified
3. Read tests before coding — understand what passes before writing
4. Read error output carefully before attempting a fix

ASCII-Only Output

Use ASCII characters only in all output:

• -- not — (em dash)
• " not " " (smart quotes)
• ' not ' ' (curly apostrophes)
• No emoji unless explicitly requested
• No Unicode decorators or special characters

This ensures clean copy-paste for code and compatibility with downstream systems.

Measuring Impact

Track these metrics to measure token savings:

• Output length: average words per response (target: 30-50% reduction)
• Tool calls per task: should stay within budget tier
• Re-read count: should be near zero
• Write-without-read count: should be zero
• Iteration cycles: tests should pass in 1-2 attempts, not 5+

Attribution

Token efficiency patterns adapted from drona23/claude-token-efficient (MIT).