# Claude Code Implementation

> Claude Code-specific token optimization strategies including compaction guidance, subagent routing, and session hygiene practices

- **Category**: optimizing-token-usage-practices

- **Canonical URL**: https://designpattern.fyi/optimizing-token-usage-practices/part-i-claude-code/

---

## Description
Claude Code-specific token optimization strategies including compaction guidance, subagent routing, and session hygiene practices








## Additional Notes

## Claude Code Token Optimization

### Layer 1 — Platform Mechanics

Keep `CLAUDE.md` content stable across a project so it doesn't need reprocessing every session; put task-specific instructions in Skills (`~/.claude/skills/`) instead of inline in `CLAUDE.md`, so they only enter context when matched. Assign subagents by tier: Haiku for test/log/doc-retrieval work, Sonnet as default, Opus reserved for architecture calls. Cap reasoning spend with `/effort` or `MAX_THINKING_TOKENS`.

**Key Strategies:**
- **Stable Core Content**: Keep project-level `CLAUDE.md` stable to avoid reprocessing overhead
- **Progressive Disclosure**: Move task-specific instructions to Skills that load on-demand
- **Tiered Subagent Routing**: Route subagents by complexity tier
  - Haiku: Test runs, log triage, doc lookups
  - Sonnet: Default for code generation
  - Opus: Architecture-level decisions only
- **Reasoning Spend Control**: Use `/effort` settings or `MAX_THINKING_TOKENS` to cap spend

### Layer 2 — Agent Operation

Write explicit compaction guidance into `CLAUDE.md` (what to keep, what to drop) so `/compact` doesn't guess. Treat `/clear` as the default when switching to an unrelated task, not just `/compact`. Audit MCP servers regularly — an idle server still costs prefix tokens every turn.

**Operational Best Practices:**
- **Explicit Compaction Rules**: Define what to preserve vs. discard in `/compact`
  - Preserve: Failing test output, diffs, open TODOs, acceptance criteria
  - Discard: Exploratory file reads that didn't lead to changes
- **Session Hygiene**: Default to `/clear` when switching tasks, not `/compact`
- **MCP Server Auditing**: Regular audit and removal of unused MCP servers
  - Idle servers still cost prefix tokens every turn
  - Flag servers unused for 2+ weeks for removal

### Layer 3 — Codebase Architecture

Keep the SRP/coupling/file-size rule in the shared `AGENTS.md`, which Claude Code now reads alongside `CLAUDE.md`.

**Architecture Rules:**
- **Single Responsibility Principle**: One responsibility per function/class/file
- **File Size Limits**: Split files exceeding ~300 lines before adding more
- **Dependency Management**: Keep dependency fan-out low
- **Shared Rules**: Maintain architecture rules in shared `AGENTS.md`

## Claude Code-Specific Features

### Plan Mode
Claude Code's Plan mode provides a built-in planning gate that separates exploration from implementation. Use this for non-trivial tasks to prevent uncontrolled editing during exploration.

### Skills System
Claude Code's Skills system (`~/.claude/skills/` or `.claude/skills/`) provides progressive disclosure:
- Skills load only when matched to the task
- Reduces always-loaded token overhead
- Ideal for task-specific procedures and domain knowledge

### Subagent Model Routing
Per-subagent model definition allows fine-grained cost control:
- Define model tier per subagent in subagent configuration
- Reserve expensive models (Opus) for high-value tasks
- Use cheaper models (Haiku) for routine operations