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](https://github.com/drona23/claude-token-efficient) (MIT).