Choosing the Right Way to Ask the Codebase

Once a reader knows how to audit a graph answer, the next practical problem is choosing how to obtain it. Code-Graph-RAG offers deterministic graph tools, model-mediated natural-language querying, semantic search, SDK access, and MCP integration. This chapter compares those interfaces by the kind of question they can support, the uncertainty they introduce, and the confirmation step that should follow. The useful choice is rarely “the most intelligent” interface; it is the smallest one that matches the claim.

Match the interface to the question

Start with what is already known. If the reader has an exact symbol or a source location, asking a language model to rediscover it adds an unnecessary interpretation step. Code-Graph-RAG’s deterministic tools can resolve a name or location, retrieve a definition, and find callers, callees, implementors, overrides, importers, or tests that reach a symbol. They use fixed graph queries, so the same graph produces the same structured result. That makes them a strong default for questions such as “Where is this method defined?” or “Which call sites invoke this qualified name?”

Deterministic does not mean complete in every semantic sense. The tool can return the relationships represented in the graph, including their locations and resolution information, but it cannot manufacture an edge that the parser or frontend did not capture. A caller query is also different from a behavioral claim. It can show recorded static call sites; it does not necessarily show a framework callback, reflection route, or registry dispatch that static analysis missed. The benefit is that the question-to-query step is stable and easy to inspect.

An open-ended question is different. A reader may know the concern but not the graph vocabulary: “Find the parts of the application that handle database connections,” “How does a request reach the billing logic?” or “Which components depend on this user contract?” Code-Graph-RAG can use a configured model to translate such a request into Cypher, run it against the graph, and present results with source snippets. This lowers the barrier to a graph query because the reader can describe an intent instead of writing the relationship pattern by hand.

The model’s role is formulation and explanation, not authority. The project’s documentation warns that the generated Cypher may be narrower than the natural-language question. A result can therefore be technically valid while covering only one interpretation of the request. The reader should inspect the query when possible, check the relationship columns and site information, and cross-check material call claims in the source. For a broad exploratory question, this trade-off is often worthwhile; for an exact lookup, it is avoidable.

Semantic search addresses a third kind of uncertainty: the reader knows what a piece of code does but not what it is called.