Skip to content

docs: add token-cost budget to grep-verification guidance#353

Open
ckforce wants to merge 1 commit into
colbymchenry:mainfrom
ckforce:main
Open

docs: add token-cost budget to grep-verification guidance#353
ckforce wants to merge 1 commit into
colbymchenry:mainfrom
ckforce:main

Conversation

@ckforce
Copy link
Copy Markdown

@ckforce ckforce commented May 23, 2026

Problem

The current CODEGRAPH_START instructions tell agents "Trust codegraph results" and "Do NOT re-verify with grep" but give no concrete reason why. Agents naturally fall back to grep-verifying codegraph results, wasting tokens.

Change

Replace vague "wastes context" with a concrete token-cost framing across all 3 synced instruction files:

Before:

- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.

After:

- **Don't grep-verify codegraph results — each unnecessary verification costs ~800 tokens.** They come from a full AST parse. Budget: 3 grep verifications per task. Spend them only on genuinely ambiguous text content (strings, comments, logs) — never on structural queries that codegraph already answered.

Also updated the MCP server-instructions.ts to replace the soft "Reach for raw Read/Grep only to confirm" with the same framed guidance.

Proven Impact

Measured on a 983-file embedded C codebase using the same 2 agent queries before and after:

Test Before After Delta
Pattern finding (taskADC timeout) 13msgs, ~8grep, 197s 8msgs, 6grep, 135s -31% time
Impact analysis (cr_timer_set) 13msgs, ~20+grep, 226s 8msgs, 7grep, 105s -53% time, -65% grep

The cost-budget framing gave agents a concrete decision rule for when grep is justified vs wasteful.

Files Changed

  • src/mcp/server-instructions.ts — MCP server initialize response (agent system prompt)
  • src/installer/instructions-template.ts — installed CODEGRAPH_START block
  • .cursor/rules/codegraph.mdc — Cursor rules

Replace vague 'wastes context' with concrete ~800 token cost and
3-grep budget per task. This directly reduced grep overhead by 65%
and time by 53% in agent benchmarks.

Updates all 3 synced instruction files:
- src/mcp/server-instructions.ts (MCP initialize response)
- src/installer/instructions-template.ts (installed CLAUDE.md block)
- .cursor/rules/codegraph.mdc (Cursor rules)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant