agent-token-optimization-patterns

// WRONG: verbose and hedging
const verbose = `
  I was wondering if you could help me take a look at the following code
  and maybe identify any potential issues that might be present in it.
  Please be thorough but also concise in your response if possible.
`;

// CORRECT: imperative, direct
const precise = `Review this code. List issues by severity (critical/high/medium/low). One line each.`;

def select_context(files: list[str], task_keywords: list[str]) -> list[str]:
    """Return only files that contain at least one task keyword."""
    relevant = []
    for path in files:
        content = read_file(path)
        if any(kw.lower() in content.lower() for kw in task_keywords):
            relevant.append(path)
    return relevant[:5]  # Hard cap: never inject more than 5 files per task

interface ContextSummary {
  type: "file" | "conversation" | "result";
  path?: string;
  summary: string;         // compressed representation
  tokenEstimate: number;   // approximate tokens saved
  fullContentAvailable: boolean;
}

function compressFileContext(path: string, content: string): ContextSummary {
  // Replace full content with: exports, function signatures, type definitions
  const lines = content.split("\n");
  const signatures = lines.filter(l =>
    l.match(/^(export|function|class|interface|type|const\s+\w+\s*=\s*(async\s*)?\()/)
  );
  return {
    type: "file",
    path,
    summary: signatures.join("\n"),
    tokenEstimate: content.length - signatures.join("\n").length,
    fullContentAvailable: true,
  };
}

Single agent (bad):  [security context] + [style context] + [perf context] + [code] → one agent
Isolated (good):     [security context] + [code] → agent A
                     [style context]    + [code] → agent B
                     [perf context]     + [code] → agent C

CACHE-FRIENDLY layout:
  [System prompt — never changes]
  [Tool definitions — rarely change]
  [Examples — change per task type]
  [Conversation history — changes each turn]  ← volatile, goes last
  [Current user message]                       ← most volatile

CACHE-UNFRIENDLY layout:
  [Timestamp or request ID]     ← volatile, poisoned the cache
  [System prompt]
  [Task]

def build_cache_optimized_request(
    system_prompt: str,       # stable — injected first
    tool_definitions: list,   # stable — injected second
    conversation_history: list, # changes each turn
    current_message: str,     # most volatile
) -> dict:
    return {
        "system": system_prompt,
        "tools": tool_definitions,
        "messages": [
            *conversation_history,
            {"role": "user", "content": current_message},
        ],
    }

interface CacheMetrics {
  inputTokens: number;
  cachedInputTokens: number;
  outputTokens: number;
}

function cacheHitRate(metrics: CacheMetrics): number {
  if (metrics.inputTokens === 0) return 0;
  return metrics.cachedInputTokens / metrics.inputTokens;
}

function assertCacheHealth(metrics: CacheMetrics, minHitRate = 0.4): void {
  const rate = cacheHitRate(metrics);
  if (rate < minHitRate) {
    console.warn(`Cache hit rate ${(rate * 100).toFixed(1)}% below threshold ${minHitRate * 100}%. Check prompt stability.`);
  }
}

type ModelTier = "haiku" | "sonnet" | "opus";

interface TaskSignals {
  inputTokens: number;
  requiresCodeGen: boolean;
  requiresMultiStepReasoning: boolean;
  hasAmbiguousRequirements: boolean;
  isClassificationOrExtraction: boolean;
  priorFailureCount: number;
}

function routeToModel(signals: TaskSignals): ModelTier {
  if (signals.priorFailureCount >= 2) return "opus"; // escalate on repeated failures

  if (signals.isClassificationOrExtraction && !signals.requiresCodeGen) {
    return "haiku";
  }

  if (signals.requiresMultiStepReasoning || signals.hasAmbiguousRequirements) {
    return "opus";
  }

  if (signals.inputTokens > 50_000) return "sonnet"; // large context → sonnet
  if (signals.requiresCodeGen) return "sonnet";

  return "haiku";
}

FALLBACK_CHAIN = ["haiku", "sonnet", "opus"]

async def route_with_fallback(task: dict, starting_tier: str) -> dict:
    start_idx = FALLBACK_CHAIN.index(starting_tier)
    for tier in FALLBACK_CHAIN[start_idx:]:
        result = await call_model(tier, task)
        if result["valid"]:
            return result
        # log that we escalated
    raise RuntimeError("All model tiers failed")

interface TokenBudget {
  inputCap: number;        // max tokens in prompt
  outputCap: number;       // max tokens in completion
  softWarnAt: number;      // warn but continue (as fraction of cap, e.g. 0.8)
  hardStopAt: number;      // abort task (as fraction of cap, e.g. 1.0)
}

const DEFAULT_BUDGETS: Record<string, TokenBudget> = {
  "code-review":      { inputCap: 8_000,  outputCap: 2_000, softWarnAt: 0.8, hardStopAt: 1.0 },
  "summarization":    { inputCap: 50_000, outputCap: 1_000, softWarnAt: 0.8, hardStopAt: 1.0 },
  "code-generation":  { inputCap: 10_000, outputCap: 4_000, softWarnAt: 0.8, hardStopAt: 1.0 },
  "orchestration":    { inputCap: 20_000, outputCap: 3_000, softWarnAt: 0.8, hardStopAt: 1.0 },
};

function checkBudget(budget: TokenBudget, usedInput: number, usedOutput: number): "ok" | "warn" | "stop" {
  const inputRatio = usedInput / budget.inputCap;
  const outputRatio = usedOutput / budget.outputCap;
  const ratio = Math.max(inputRatio, outputRatio);
  if (ratio >= budget.hardStopAt) return "stop";
  if (ratio >= budget.softWarnAt) return "warn";
  return "ok";
}

class CycleBudget:
    def __init__(self, cycle_cap_tokens: int):
        self._cap = cycle_cap_tokens
        self._used = 0

    def consume(self, tokens: int) -> None:
        self._used += tokens
        if self._used > self._cap:
            raise BudgetExceededError(f"Cycle budget {self._cap} exceeded at {self._used}")

    @property
    def remaining(self) -> int:
        return max(0, self._cap - self._used)

    @property
    def utilization(self) -> float:
        return self._used / self._cap

Turn 1-10:   [full text]
Turn 11-20:  [summary: "User debugged auth module. Fixed JWT expiry bug. Tests pass."]
Turn 21-30:  [summary: "Refactored UserService. Introduced repository pattern."]
Turn 31+:    [full text — most recent, highest relevance]

function applySlideWindow<T>(history: T[], maxTurns: number): T[] {
  if (history.length <= maxTurns) return history;
  return history.slice(history.length - maxTurns);
}

// Good: agents reference shared rules by path or ID
sharedRules: "file:///claude/evolve/shared-rules.md"

// Bad: each agent has its own copy
agentA: { systemPrompt: "You are a code reviewer. Always be thorough..." }
agentB: { systemPrompt: "You are a code reviewer. Always be thorough..." }  // drifted copy

Abbreviations used in this session:
TS = TypeScript, FE = function expression, RT = return type, CB = callback

// Prose: ~80 tokens
"The user has the name John Smith, they are 34 years old, their email is john@example.com,
and they have been active on the platform since January 2022."

// Structured: ~20 tokens
{"name":"John Smith","age":34,"email":"john@example.com","since":"2022-01"}

<!-- Verbose: 12 tokens of overhead per block -->
<code_block language="typescript">...</code_block>

<!-- Compact: 6 tokens of overhead per block -->
<c lang="ts">...</c>