Cursor codebase context beyond indexing

What does Cursor codebase indexing do well?

Cursor builds a semantic index of your repository so the editor can pull in relevant files for a request. It is fast at answering where code lives and good at surfacing similar implementations.

• Locates relevant files from a natural-language description.
• Keeps answers grounded in your actual repository.
• Improves steadily as the index stays current.

Where does indexing fall short on large repositories?

Similarity is not structure. Indexing rarely shows which module everything else depends on, which files bridge subsystems, or why a boundary exists. Those answers live in dependencies and rationale, not in vector distance.

• No explicit map of imports, calls, and cross-module edges.
• Design rationale disappears between sessions and teammates.
• Deep architecture questions need paths, not only nearest chunks.

How does a graph add structure to Cursor workflows?

Build a graph with Graphify and keep the artifacts with the project. Use graph.html to see subsystem clusters, GRAPH_REPORT.md to read what each cluster owns, and graph.json for scripted queries. Bring those findings into Cursor sessions as structured context.

• Check the target subsystem in graph.html before starting a change.
• Share GRAPH_REPORT.md so reviews work from the same map.
• Refresh the graph after refactors so context tracks the code.

What does a short setup inside Cursor look like?

Build the graph once from a project ZIP, download the artifacts, and place them in a docs folder in the repository. Add a short note to your Cursor project rules or docs pointing at GRAPH_REPORT.md. Before a task, open graph.html to see the subsystem you are about to touch; during the task, keep the report open as the structural reference the editor cannot infer on its own.

• Keep artifacts in the repository so every session can read them.
• Reference GRAPH_REPORT.md from project rules or the docs folder.
• Open graph.html when planning a change, not only when debugging.

How should codebase search and graph artifacts be used together?

Codebase search answers where something lives; the graph answers what it touches. A reliable sequence: search to locate the relevant files, open the matching cluster in graph.html, then check the report for the paths and god nodes that interact with your change. Search narrows, structure widens, and using both in that order avoids editing a file without seeing its blast radius.

• Locate with search, then confirm the subsystem in the graph.
• Check cross-cluster edges before touching shared modules.
• Let the report frame the change; let indexing find the lines.

When should the graph be rebuilt for Cursor?

Treat the graph like any other project document: refresh it after refactors, dependency moves, and boundary changes, and archive a dated report when the structure shifts meaningfully. A stale graph misleads sessions more than no graph at all, because it answers with confidence about an architecture that no longer exists.

• Rebuild after refactors, migrations, and dependency changes.
• Keep dated reports so structure changes can be compared over time.
• Refresh before onboarding onto an unfamiliar subsystem.

What belongs in Cursor rules versus the graph report?

Project rules should carry what never changes per task: conventions, commands, and the instruction to consult the artifacts. The graph report carries what changes with the code: structure, boundaries, and risky edges. Keeping that split means rules stay short and stable, while the structural detail lives in the document that gets refreshed, not duplicated in instructions that slowly go stale.

• Rules: conventions, commands, and a pointer to the artifacts.
• Report: structure and boundaries that change with the code.
• Avoid copying structure into rules where it cannot stay fresh.