docs(agents): stop steering agents away from Grep for code search - #119
Merged
Conversation
The shipped Code Graph guidance told agents to "prefer graph commands over grepping or reading files" and to run `mex graph scope` first on every task. `scope` matches lexically, so when a task's phrasing does not share vocabulary with the code it returns weak results — and the old wording then discouraged the cheap fallback that would have answered the question. Agents paid for the manifest, expanded node ids that did not help, and grepped anyway. Reorder the guidance around what each command is actually good at: - `graph query`/`get` lead. They are exact and cheap when the symbol name is known, and note that an approximate name can return a confident wrong match. - `scope` is framed as a starting point for unfamiliar tasks, with an explicit statement that it matches words rather than meaning. - Add explicit permission to fall back to Grep/Glob when the manifest does not contain what is needed, and cap `scope` rephrasing at one retry. Applied to all five shipped tool configs and this repo's own scaffold.
There was a problem hiding this comment.
Pull request overview
This PR updates the shipped agent/tool configuration templates to stop steering agents away from Grep/Glob and to position the code graph as a complementary tool (with graph query/get as the first choice when the symbol name is known, and scope as an optional, vocabulary-based starting point for unfamiliar tasks).
Changes:
- Rewrites the Code Graph guidance to lead with
mex graph query/mex graph getfor exact symbol lookups. - Reframes
mex graph scopeas a vocabulary match (not semantic), with explicit guidance to fall back to Grep/Glob and to cap scope rephrasing. - Keeps the “treat returned sources as already read” instruction while discouraging irrelevant node expansion.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| templates/AGENTS.md | Updates Code Graph guidance to treat graph as complementary to Grep/Glob and to lead with exact query/get usage. |
| templates/.tool-configs/copilot-instructions.md | Aligns Copilot tool-config Code Graph guidance with the new query-first / scope-caveated wording. |
| templates/.tool-configs/CLAUDE.md | Same Code Graph guidance rewrite for Claude tool-config template. |
| templates/.tool-configs/.windsurfrules | Same Code Graph guidance rewrite for Windsurf rules template. |
| templates/.tool-configs/.cursorrules | Same Code Graph guidance rewrite for Cursor rules template. |
| .mex/.tool-configs/copilot-instructions.md | Mirrors the updated guidance in the repo’s maintained tool-configs. |
| .mex/.tool-configs/CLAUDE.md | Mirrors the updated guidance in the repo’s maintained tool-configs. |
| .mex/.tool-configs/.windsurfrules | Mirrors the updated guidance in the repo’s maintained tool-configs. |
| .mex/.tool-configs/.cursorrules | Mirrors the updated guidance in the repo’s maintained tool-configs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Merged
theDakshJaitly
added a commit
that referenced
this pull request
Aug 5, 2026
Patch release carrying the agent guidance fix from #119. Documentation and tool-config changes only; no source or schema changes. Note that upgrading does not rewrite an existing .mex/ scaffold — tool configs are copied at setup time — so existing users need to replace the Code Graph section manually. Called out in the changelog.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites the
## Code Graphguidance block in all five shipped tool configs (AGENTS.md,CLAUDE.md,copilot-instructions.md,.cursorrules,.windsurfrules) and this repo's own.mex/.tool-configs/.Why
The old wording opened with:
That makes
graph scopethe first command an agent runs on every task, and positions the reliable path (graph query) as the exception.scopematches lexically — FTS5 plus name scoring. When a task's phrasing does not share vocabulary with the code, it returns weak results. Measured on this repository, a scope response is ~1,200 tokens against ~200-500 forgraph query, and on natural-language questions the expected symbol is frequently absent.The old wording then discouraged the fallback that would have worked. The observed pattern is: run
scope, get a weak manifest, expand node ids that do not help, grep anyway. Every step is billed, and correctness is preserved only because the agent eventually ignores the instruction.External measurement in #115 found mex costing 1.3-1.7x plain grep's session tokens across three real tasks while reaching the same answers on two of them. This guidance is part of that cost.
Changes
graph query/graph getlead: exact and cheap when the symbol name is known. Notes that an approximate name can return a confident wrong match (where-defined ledgerresolves toplanSource, because FTS matches a parameter name in a signature).scopeis framed as a starting point for unfamiliar tasks, with an explicit statement that it matches words rather than meaning, and should never be treated as a complete answer.scoperephrasing.Treat any source the graph DOES return as ALREADY READis retained — that instruction is sound and avoids real duplicate reads.Scope
Documentation only. No code, no schema, no CLI behaviour changes. The underlying retrieval issues are tracked separately; this stops the guidance from amplifying them while they are fixed.
Verification
npm run buildclean,npx vitest run369/369 passing.