exploring-codebase

Exploring the Codebase

Overview

Structural questions about a codebase have a single right answer that can be derived from the graph. Grep gives string matches; file reads give whatever happens to live in the file you opened. The graph carries the actual edges — calls, imports, extends, annotations, parent-child — and resolves them faster and more accurately than text search.

This skill calls the query_graph, find_node, and trace_flow MCP tools.

When to use

Any question about relationships in code:

• Callers / callees — who calls X? what does X call?
• Class hierarchy — what extends Y? what does Y extend?
• Imports — who imports module Z? what does Z import?
• Annotations — what is annotated with Controller? what annotations does this class carry?
• Routes / endpoints / handlers — what handles route /foo? what middleware runs on it?
• Flows — what runs when this endpoint is hit? what's in the call chain from request to response?
• Where is X used — every reference to X across the repo

If the answer requires walking edges, use this skill. If it requires reading a function body to interpret what code does, you may need to fall back to file reads, but only AFTER querying the graph for the names and locations.

Tool selection

The three tools cover different shapes of question. Pick the right one first.

query_graph — search by name or partial phrase

Use first, almost always. Returns ranked hits with 1-hop neighbors (callers, callees, parent class, declared annotations).

Good for:

• "Who calls processPayment?"
• "Where is User used?"
• "Find anything related to billing reconciliation"
• "What extends BaseHandler?"

The query takes a name or phrase. Hits include qualified_name, file, line, plus immediate neighbors. Cite file:line from the result when answering the user.

find_node — resolve a specific qualified_name

Use when you already have a fully-qualified handle and just need its file:line and direct edges. Faster than query_graph when the input is exact.