Cursor Prompts to Understand a Codebase: 10 Ask Mode Prompts

The best Cursor prompt to understand a codebase asks for a read-only tour with file citations: what each folder does, how a request flows, and where your change will go. Run these in Ask mode, Cursor's read-only mode (Shift+Tab or the mode picker in the Agent panel), and @-mention the files or folders you already know matter. The 10 prompts below go from a first look to a change plan; ask for "not found" instead of guesses so you can trust the answers.

First look

1. Repo map

Here is the top-level tree: [paste tree]. Open enough files to say what each top-level folder holds, one line each, with the file you based it on. Mark folders you did not open as "not opened".

2. How to run it locally

From the files in this repo only, list the steps to install dependencies, set environment variables, and run [app or service] locally. Cite the file for each step, for example a README or config, and say "not found" for anything missing.

3. Stack and services inventory

List the languages, frameworks, databases, queues, and external services this repo uses, each with the file that shows it, such as a dependency file or config. Do not list anything you cannot point to.

Trace the code

4. Request flow trace

Trace what happens when [user action or API call] runs, from entry point to database and back, as numbered steps with file path and function name. Start from @[entry file or folder].

5. Mermaid diagram of a flow

Turn the flow for [feature] into a Mermaid flowchart I can paste into a Markdown file. Use file and function names as node labels and keep it under 12 nodes.

6. Explain one module

Explain what @[file] does, what calls it, and what it calls, in plain English. List its public functions with one line each and point out anything surprising.

7. Domain glossary

Build a glossary of the domain terms in this codebase from model, table, and type names in @[folders]. For each term, give a one-line meaning and the file where it is defined.

Plan a change

8. Change map for my first task

My task is [task]. List the files it will most likely touch, the tests that cover each one or "no test found", and one risk per file. Do not write code yet.

9. Find existing patterns

Before I add [feature], find two places in this repo where something similar is already done. Show the file paths and summarize the pattern so my change follows it.

10. Onboarding notes for the next person

Summarize what we learned in this chat as onboarding notes: repo map, key flows, glossary, and open questions, in Markdown. I will save it to [docs path] myself after reviewing it.

Get the whole tour in one prompt

The flagship Cursor Prompt to Understand a Codebase: Ask Mode Tour combines the repo map, a flow trace for your first task, a Mermaid diagram, a glossary, a change map with tests and risks, and a list of what is still unknown. Its example tours a Django and React invoicing app before adding a late fee to overdue invoices.

A tip: Cursor's agent searches the repo on its own, so you only need @-mentions for files you already know are relevant. Once the tour is done, switch back to Agent mode for the actual change, and capture lasting conventions as project rules in .cursor/rules/*.mdc files so future chats start with them.

Related prompts

When you hand the repo to an agent, start from a system prompt for a coding agent or the coding agent system prompt with repo rules. For rules files, see Cursor rules for React and AGENTS.md and Cursor .mdc rules from a repo brief.

Ready to change the code? See ChatGPT prompt for code refactoring and system prompt for a coding agent.

Find more in the Coding category, look through Browse, or post your own on Share.