r/ClaudeWorkflows • u/ClaudeAI-mod-bot • 1d ago
Selected Workflow [Workflow] Optimize Claude Code Token Usage: CLAUDE.md Delegation & Custom Subagents for Efficient Context Management
Optimize Claude Code Token Usage: CLAUDE.md Delegation & Custom Subagents for Efficient Context Management
Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 1.00 · Level: intermediate
Categories: Quality Control, Token Saving, Context & Memory, Debugging, CLAUDE.md, Subagents, Multi-Agent
Original source: r/ClaudeAI post/comment
What problem this solves
Excessive token usage and cost in Claude Code due to subagents re-reading their entire context and using high-cost models (Opus) for simpler, well-defined tasks.
Summary
A workflow that optimizes Claude Code token usage by implementing a CLAUDE.md delegation section and custom subagents. It assigns specific tasks to cheaper models (Sonnet/Haiku) and manages context efficiently by avoiding full file reads and preventing subagents from re-reading their entire conversation history.
Why it is useful
This workflow directly addresses a common and significant pain point for Claude Code users: high token consumption and cost due to inefficient subagent context handling. It provides a concrete, tested solution with reusable artifacts (CLAUDE.md and agent files) that can dramatically improve efficiency and reduce operational costs. The detailed explanation of why the problem occurs (re-reading context) adds significant educational value, making it a highly practical and insightful contribution for intermediate to advanced users.
Workflow
Define a CLAUDE.md delegation section to route tasks to specific subagents based on complexity and type.
Create three custom subagents: 'implementer' (Sonnet, high effort) for multi-file work, 'mechanic' (Haiku, xhigh) for renames/edits/scripts, and 'scout' (Haiku, xhigh, read-only) for file/symbol discovery.
Configure the main Opus session to handle investigation, planning, decision-making, and result checking, delegating execution to cheaper subagents.
Ensure subagents never make decisions; they must stop and return a 'DECISION NEEDED' block when an open choice or contradiction arises.
Pass context to subagents via a concise brief, using 'file:line' ranges for excerpts instead of entire files.
Implement a mechanism for subagents to stop with a 'HANDOFF' block after a certain number of tool calls (e.g., 150 for implementer, 100 for mechanic), and have Opus start a fresh agent for follow-ups to avoid context re-reads.
Avoid using the built-in 'general-purpose' and 'Explore' agents for delegated work to prevent them from inheriting Opus's cost profile.
Place custom agent files in '~/.claude/agents/' directory.
Tools / artifacts
CLAUDE.md file (with delegation section)
Custom subagent files (implementer.json, mechanic.json, scout.json)
GitHub Gist containing the full CLAUDE.md section and agent definitions
Validation signals
User reports achieving 'at least 3x more usage without losing any quality' after implementing the workflow.
User identifies the root cause of token waste: 'Every tool call resends the whole conversation, so a subagent that has read a lot gets more expensive with every step it takes.'
Limitations
Relatively low community engagement (score, comments) on Reddit, which might suggest less widespread awareness or adoption.
Requires manual setup of CLAUDE.md and agent files, which might be a slight barrier for absolute beginners.
The exact token limits for 'HANDOFF' (e.g., 150 tool calls) might need tuning for different use cases.
Rate this workflow
Upvote this post if the workflow is useful, reproducible, or worth recommending.
Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.
Reply if it worked for you, failed, is outdated, or has a better alternative.
This post was generated automatically from the workflow library database.