Skip to content
TilloTech Docs

Context, scope, and cost

Context is a shared budget for the task, instructions, code, tool output, and conversation history. More context is not automatically better: irrelevant material consumes tokens and makes the useful constraints harder to select.

Scope from the task outward

Start a task at the smallest directory that contains the likely change. Expand access only when dependencies or cross-package work require it. For a broad change, start at the repository root but explicitly identify the affected packages and their validation boundaries before editing.

For large repositories:

  • keep root guidance short and layer subsystem-specific guidance beneath it;
  • exclude generated, built, vendored, and otherwise irrelevant paths from routine discovery;
  • use language-server or index-backed symbol lookup instead of repeated tree scans where possible;
  • use sparse worktrees or focused checkouts for isolated tasks;
  • keep shared conventions at the root and package-specific skills near their code;
  • plan cross-package changes around dependency order and package-level checks.

Concrete Claude Code controls map to distinct problems: nested CLAUDE.md for owned subsystem conventions, claudeMdExcludes for instruction trees a developer never needs, Read(...) denies for checked-in generated or vendored content, code-intelligence plugins for symbol navigation, sparse paths for worktree materialisation, and --add-dir for deliberate cross-tree access. File access and configuration discovery remain separate capabilities.

Tool-specific detail: Claude Code loads instructions and settings according to the launch directory and can use nested instructions, read-deny rules, sparse worktrees, additional directories, and language-server plugins. Do not assume those exact loading semantics apply to another client.

Control always-on context

Move long procedures, examples, and reference material out of always-loaded instructions and into focused skills or linked documents. Keep the skill entry file navigational and place large references, templates, and scripts beside it. Only the selected procedure should incur the full context cost.

Reduce noisy tool output before it reaches the model. Prefer commands that can emit focused summaries, machine-readable status, or failure-only output. A hook can filter a verbose test run, but the underlying command should offer a concise mode when the team owns it.

Manage long conversations intentionally

Long work should not depend on retaining a verbatim transcript. Preserve:

  • the objective and current plan;
  • decisions and their rationale;
  • changed files and produced artifacts;
  • validation already completed and outstanding;
  • blockers and required approvals.

Use compaction before context exhaustion and keep durable artifacts on disk. Reuse an execution environment when dependency caches and intermediate files matter. A resumed agent should be able to reconstruct state from the repository and artifacts, not only from chat history.

Invoked skills also consume long-run context. Claude Code reattaches recent skill invocations during compaction, retaining at most 5,000 tokens per skill within a combined 25,000-token budget, newest first. Large or older skills may therefore be truncated or dropped. Keep entry files concise, write critical state to artifacts, and reinvoke a skill when its complete contract must be restored.

Measure cost as an operational signal

Track context size or tokens, duration, tool volume, and outcome quality by workflow. Optimise only after identifying the cause:

  • excessive startup cost suggests oversized instructions or too many tool schemas;
  • repeated file reads suggest poor navigation or missing code intelligence;
  • huge command output suggests missing filters or structured summaries;
  • long re-orientation after compaction suggests weak durable state;
  • parallel agents multiply context cost, so use the smallest useful team and give each a bounded prompt.

For Claude Code API usage, /usage is a local estimate rather than the authoritative bill and distinguishes API time from wall time. Attribute usage to skills, plugins, subagents, and MCP servers where the client exposes it. Establish a small pilot baseline before setting organisation budgets or rate limits, and record the product version with comparisons.

Cost reduction is successful only if the workflow still meets its quality and safety contract.