Token optimization: benchmark data on context pre-filtering

[nicolalessi]

Great resource. One topic that could add value to the mastery guide: context pre-filtering as a token optimization strategy.

I tracked Claude Code on a real project (~800 files) and found it averages 23 tool calls per prompt, consuming ~180K tokens. Roughly 70% of that context is files the model reads and ignores.

Adding an MCP server that pre-indexes the codebase (tree-sitter AST + dependency graph) and serves only relevant code per query reduced tool calls to 2.3 and cost from $0.78 to $0.33 per task.

Could be a useful addition to the guide as an advanced optimization technique.

Data: vexp.dev/benchmark · FastAPI writeup: reddit.com/r/ClaudeCode

[TheDecipherist]

Good data — and the benchmark is real. But there's a more fundamental fix before reaching for infrastructure.

The reason Claude makes 23 tool calls averaging 180K tokens is that it has no structured entry point into the codebase. It reads broadly because it has no other choice — there's nothing telling it what's relevant before it starts. A context pre-filter solves this at the infrastructure layer. MDD solves it at the methodology layer, and the results compound differently.

What MDD does to this problem:

Every feature lives in a structured doc at .mdd/docs/NN-feature-name.md with explicit YAML frontmatter:

source_files:
  - src/handlers/users.ts
  - src/types/user.ts
depends_on: [01-auth, 03-database]
routes:
  - GET /api/v1/users/:id

Claude doesn't need to discover the relevant files — they're declared. A task that would normally require 23 tool calls to orient starts with 1 read of the feature doc and 3-4 targeted reads of the declared source files. The rest of the 800-file codebase is never touched.

On top of that, the SessionStart hook injects .mdd/.startup.md — a ~100-200 token project snapshot covering current branch, features, last audit results, and rules — before the first prompt of every session. Claude is oriented before it touches a tool.

The benchmark comparison:

Your setup: 23 tool calls → 2.3 tool calls (90% reduction via AST index)
MDD: documentation-declared files → typically 3-6 tool calls per task, no infrastructure required

The AST approach and MDD are also composable — if you're running MDD on an 800-file codebase, adding your MCP pre-filter on top would likely push it to 1-2 tool calls since the doc already narrows the search space before the index runs.

The companion starter kit ships with /mdd out of the box:
👉 claude-code-mastery-project-starter-kit

Worth trying on one feature before adding the infrastructure layer — you may find the structured docs get you most of the way there without the AST overhead.