graph-guided-code-reading

Graph Guided Code Reading

Save tokens by reading the codebase as a dependency graph, not as a pile of files.

Core Principle

Most repo-reading waste comes from opening too many files too early. Build a small relevance graph first, then read only the nodes that matter.

Minimal Relevance Graph

For each task, identify only:

• the user-visible entrypoint or changed surface;
• the owning module or service;
• the direct dependencies and dependents that shape behavior;
• the nearest tests, config, or contracts that constrain the change.

Stop expanding once the next action is clear.

Reading Workflow

1. Start from the highest-signal anchor:
   • changed files;
   • failing test;
   • route, command, job, or entry function;
   • exact symbol or error text.
2. Build a compact focus set:
   • entrypoint;
   • implementation module;
   • adjacent callers/callees or imports;
   • validating tests.
3. Read narrow slices around the relevant symbols first.
4. Expand one edge at a time only if the current node does not answer the question.
5. Maintain a short checked-location ledger so files are not reopened without a reason.

Preferred Tools

• If a repo graph, repomap, AST, or change-impact tool exists, use it first.
• If not, emulate graph reading with:
  • rg for symbol ownership;
  • git diff --name-only or failing-test paths for anchors;
  • imports, call sites, and config references for edges;
  • nearby tests for behavior contracts.

Task Patterns

PR Review

• Start with changed files and public interfaces.
• Trace immediate blast radius: callers, consumers, schemas, tests.
• Review the impact set before reading unrelated modules.

Debugging

• Start from the failing surface and walk inward.
• Prefer one causal path over opening every suspected file.
• Keep hypotheses tied to specific nodes in the focus set.

Architecture Questions

• Start from entrypoints and major seams, not internal helpers.
• Build a compact service/module map before diving into implementation details.