CLAUDE.md instructions duplicate MCP server instructions — wastes tokens every turn

[lbzepoqo]

Problem

CodeGraph injects its usage instructions into the agent context twice per session:

1. MCP SERVER_INSTRUCTIONS — emitted in the MCP initialize response, surfaced by Claude Code as a system reminder (## codegraph block). This is automatic for any MCP server.
2. INSTRUCTIONS_TEMPLATE — written into CLAUDE.md (global or project-level) by codegraph init, wrapped in <!-- CODEGRAPH_START --> / <!-- CODEGRAPH_END --> markers.

Both contain ~90% identical content (tool selection table, rules of thumb, anti-patterns, staleness banner guidance). The CLAUDE.md version is loaded into the system prompt alongside the MCP server instructions, so the agent reads the same advice twice on every single turn.

Token cost

The CLAUDE.md block is ~35 lines / ~1,500 tokens of input. Since it duplicates what the MCP server already provides, it burns ~1,500 extra input tokens per message for no benefit.

Source files

• SERVER_INSTRUCTIONS in mcp/server-instructions.ts — the MCP-level injection
• INSTRUCTIONS_TEMPLATE in installer/instructions-template.ts — the CLAUDE.md injection
• writeInstructionsEntry() in installer/targets/claude.ts — writes the template into CLAUDE.md on codegraph init

Suggested fix

Since the MCP server instructions are always injected by the MCP protocol, the CLAUDE.md block is redundant for Claude Code. Options:

1. Skip the CLAUDE.md write for Claude Code — the MCP server instructions already cover it. Other targets (Cursor .mdc, Kiro) may still benefit from their own instruction files since they don't surface MCP server instructions the same way.
2. Make the CLAUDE.md write opt-in — add a --no-instructions flag to codegraph init so users can skip it.
3. Deduplicate the content — have the CLAUDE.md block contain only a one-liner like "CodeGraph is configured — see MCP server instructions" instead of the full template.

Option 1 seems cleanest since Claude Code already surfaces SERVER_INSTRUCTIONS reliably.

[colbymchenry]

Fixed in #538 (merged to main, ships in the next release).

You were right that the content was duplicated — thanks for the precise writeup and the source pointers. We went with a variant of Option 1, applied to all instruction-writing targets rather than just Claude Code: the installer no longer writes the ## CodeGraph block into CLAUDE.md / AGENTS.md / GEMINI.md / Cursor's .mdc / Kiro's steering doc. server-instructions.ts (the MCP initialize response) is now the single source of truth, so there's no more 3-way sync burden either.

Two notes on the cost framing for posterity: the CLAUDE.md block measured ~820 tokens (not ~1,500), and it lives in the cached system prompt — so after the first turn it's a cache read, not 1,500 fresh tokens per message. The real win here is killing the duplication + maintenance burden, not the token cost.

For existing installs: the cleanup is a self-heal — the next time you run codegraph install (or codegraph uninstall) it strips the block a previous version wrote, preserving everything else in the file. Simply upgrading the npm package won't remove it on its own (the leftover block is harmless in the meantime — just redundant with the MCP instructions). If you'd added your own notes inside the <!-- CODEGRAPH_START -->/<!-- CODEGRAPH_END --> markers, move them outside first, since only the marked block is removed.