fix(installer): stop duplicating agent instructions; MCP server is the single source of truth (#529) (#538)
The installer wrote a `## CodeGraph` usage block into each agent's
instructions file (CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules /
Kiro steering) that duplicated, almost verbatim, the guidance the MCP
server already emits in its `initialize` response — so agents that
surface MCP instructions (Claude Code) read the same playbook twice
every turn.
All 6 instruction-writing targets (claude, cursor, codex, opencode,
gemini, kiro) now stop writing the block. install self-heals by
stripping a block a previous version wrote (uninstall already did), so
the next `codegraph install`/`uninstall` cleans up existing installs;
upgrading the package alone does not (the leftover block is harmless).
server-instructions.ts is now the single source of truth — the two
steers unique to the old template ("trust codegraph, don't re-verify
with grep" and the not-initialized -> `init -i` hint) are ported there.
Removes the now-dead INSTRUCTIONS_TEMPLATE / CLAUDE_MD_TEMPLATE,
claude-md-template.ts, writeClaudeMd / hasClaudeMdSection, and the
Cursor-only wireProjectSurfaces bootstrap. The install log learned a
"Removed" verb. Tests rewritten to the new contract + self-heal
coverage (140/140 installer tests pass).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
cea78ceb1b
commit
a9c9e76d8c
@@ -1,64 +1,18 @@
|
||||
/**
|
||||
* Agent-instructions template — the markdown body each agent target
|
||||
* writes into its conventional instructions file (CLAUDE.md /
|
||||
* AGENTS.md / codegraph.mdc / etc.).
|
||||
* Marker constants for the legacy agent-instructions block.
|
||||
*
|
||||
* The body content is identical across agents because the codegraph
|
||||
* usage advice is agent-agnostic — only the destination filename and
|
||||
* any optional frontmatter (Cursor `.mdc`) varies per target.
|
||||
* Codegraph used to write a `## CodeGraph` usage guide into each
|
||||
* agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md /
|
||||
* codegraph.mdc / Kiro steering doc). That duplicated the guidance the
|
||||
* MCP server already emits in its `initialize` response — every agent
|
||||
* read the same playbook twice each turn (issue #529). The installer no
|
||||
* longer writes an instructions file; the MCP server instructions in
|
||||
* `mcp/server-instructions.ts` are the single source of truth.
|
||||
*
|
||||
* The legacy `claude-md-template.ts` re-exports these names for
|
||||
* backwards compatibility with downstream importers.
|
||||
* These markers are retained so install (self-heal on upgrade) and
|
||||
* uninstall can find and strip the block a previous install wrote.
|
||||
*/
|
||||
|
||||
/** Markers used by the marker-based section replacement. */
|
||||
/** Markers used by the marker-based section removal. */
|
||||
export const CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->';
|
||||
export const CODEGRAPH_SECTION_END = '<!-- CODEGRAPH_END -->';
|
||||
|
||||
/**
|
||||
* The full marker-delimited block written into each agent's
|
||||
* instructions file. Includes the start/end markers so the section
|
||||
* can be detected and replaced on re-install.
|
||||
*/
|
||||
export const INSTRUCTIONS_TEMPLATE = `${CODEGRAPH_SECTION_START}
|
||||
## CodeGraph
|
||||
|
||||
This project has a CodeGraph MCP server (\`codegraph_*\` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
|
||||
|
||||
### When to prefer codegraph over native search
|
||||
|
||||
Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
|
||||
|
||||
| Question | Tool |
|
||||
|---|---|
|
||||
| "Where is X defined?" / "Find symbol named X" | \`codegraph_search\` |
|
||||
| "What calls function Y?" | \`codegraph_callers\` |
|
||||
| "What does Y call?" | \`codegraph_callees\` |
|
||||
| "How does X reach/become Y? / trace the flow from X to Y" | \`codegraph_trace\` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
|
||||
| "What would break if I changed Z?" | \`codegraph_impact\` |
|
||||
| "Show me Y's signature / source / docstring" | \`codegraph_node\` |
|
||||
| "Give me focused context for a task/area" | \`codegraph_context\` |
|
||||
| "See several related symbols' source at once" | \`codegraph_explore\` |
|
||||
| "What files exist under path/" | \`codegraph_files\` |
|
||||
| "Is the index healthy?" | \`codegraph_status\` |
|
||||
|
||||
### Rules of thumb
|
||||
|
||||
- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: \`codegraph_context\` first, then ONE \`codegraph_explore\` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with \`codegraph_trace\` from→to — one call returns the whole path with dynamic hops bridged — then ONE \`codegraph_explore\` for the bodies; don't rebuild the path with \`codegraph_search\` + \`codegraph_callers\`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
|
||||
- **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.
|
||||
- **Don't grep first** when looking up a symbol by name. \`codegraph_search\` is faster and returns kind + location + signature in one call.
|
||||
- **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one call.
|
||||
- **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
|
||||
- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. \`codegraph_status\` also lists pending files under "Pending sync".
|
||||
|
||||
### If \`.codegraph/\` doesn't exist
|
||||
|
||||
The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run \`codegraph init -i\` to build the index?"*
|
||||
${CODEGRAPH_SECTION_END}`;
|
||||
|
||||
/**
|
||||
* Backwards-compat alias. Existing downstream code may import
|
||||
* `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
|
||||
* `claude-md-template.ts`.
|
||||
*/
|
||||
export const CLAUDE_MD_TEMPLATE = INSTRUCTIONS_TEMPLATE;
|
||||
|
||||
Reference in New Issue
Block a user