Claude Code - better instructions

[vaibhav276]

I find that in Claude-code inspite of the skill and its tools made available, it still does the laborious grep/glob/reads. It looks like its because Claude spawns a sub-agent for exploration which ignores the instructions put by this tool into CLAUDE.md and continues on as if its on its own.

If I make edits to CLAUDE.md and ask it to consider them before spawning the sub-agent, it has a second problem - it over-uses this skill and is not able to find issues which are not in the responsibilities of this tool (apparently), like finding out if the doc-string of a function is not accurate.

Overall better instructions around the following might help:

• When to use it over other skills claude might have
• (More importantly) When not to use it or rely on its output as the sole source of truth

I am not sure if these are Claude Code specific problems, but this is the only platform I tested it on so reporting it as such.

[tirth8205]

Both observations are accurate, and the second one is already tracked as issue #314.

How the injection works today: code-review-graph install appends a marked section to your project CLAUDE.md (the template lives in code_review_graph/skills.py, _CLAUDE_MD_SECTION) and copies skill files. That section currently says "ALWAYS use the graph BEFORE Grep/Glob/Read" and has no "when not to use it" half. That is a real gap on our side, not something you misconfigured.

Why subagents ignore it: Claude Code Task subagents start with a fresh context. Their behavior is driven mostly by the prompt the main agent writes for them, so if the main agent says "search the codebase for X", the subagent greps. Injected text cannot fix that from our end; it is client behavior.

What works today:

1. Add a line to your CLAUDE.md telling the main agent to run the graph queries itself and paste the results (file paths, callers, node names) into any subagent prompt, rather than asking subagents to explore. This is the most reliable fix I know of.
2. Define a custom subagent in .claude/agents/ whose own system prompt contains the graph rules, since that prompt does reach the subagent.
3. Add guardrails like the ones proposed in Warning: blindly using code-review-graph can make model faster but noticeably worse at code understanding #314: use the graph to narrow scope, then read the actual source before concluding; if graph and source disagree, trust the source. The graph stores structure (definitions, calls, imports, tests), not docstrings or exact semantics, so things like docstring accuracy are out of scope for it by design.

I plan to fold the #314 guardrails into the installed section and the shipped skills.