Cursor Prompt to Understand a Codebase: Ask Mode Tour

Prompt

Act as a staff engineer onboarding onto an unfamiliar repository in Cursor's Ask mode, who explores the code read-only, cites the file path for every claim, and says "not found" instead of guessing.

How to run it: open the Agent panel, switch to Ask mode (Shift+Tab or the mode picker), and @-mention the folders in EntryPoints.

Inputs:
- What the product does, in one or two sentences: [RepoPurpose]
- The first task I need to do in this repo: [FirstTask]
- Top-level tree I pasted (for example from `tree -L 2`): [RepoTree]
- Folders or files I will @-mention as starting points: [EntryPoints]
- Languages, frameworks, and services I already know are used: [Stack]
- Specific questions I have: [Questions]
- How long I have for this tour: [TimeBox]

Generate:
1. Repo map: one line per top-level folder in RepoTree saying what it holds, based on files you opened. Mark any folder you did not open as "not opened".
2. Flow trace for FirstTask: the path a request or job takes through the code that FirstTask touches, as numbered steps, each with file path and function or class name.
3. Mermaid diagram: a short flowchart of that trace that I can paste into a Markdown file.
4. Glossary: domain terms from model, table, or type names, each with the file where it is defined.
5. Change map: the files FirstTask will most likely touch, the tests that cover them (or "no test found"), and one risk per file.
6. Questions answered: answer each item in Questions with a file reference, or "not found in the files I opened".
7. Still unknown: one short list of what you could not confirm and where a teammate would know.

Rules:
- Read only. Do not propose edits in this pass; I will switch to Agent mode for changes.
- Cite only paths that exist in RepoTree or that you opened. Never invent a path, function, or config value.
- Fit the tour into TimeBox: if it is short, do steps 1, 2, and 5 first.

Instructions

Paste your real top-level tree and @-mention 2 or 3 starting folders in Ask mode. Check each cited path before relying on it, then switch to Agent mode when you are ready to make the change.

Generated Output

This image was generated using the prompt above.

Cursor Prompt to Understand a Codebase: Ask Mode Tour - Result

Examples

Example Input

RepoPurpose: invoicing app for small agencies; clients get monthly invoices and payment reminders
FirstTask: add a late fee line to invoices that are 30 days overdue
RepoTree:
backend/
  invoices/ (models.py, views.py, serializers.py, tasks.py, tests/)
  billing/ (fees.py, tests/)
  config/ (settings.py, celery.py)
frontend/
  src/pages/Invoices/
  src/api/
EntryPoints: @backend/invoices/ @backend/billing/ @frontend/src/pages/Invoices/
Stack: Django, Django REST Framework, Celery, React
Questions: where are overdue invoices detected? is there an existing fee concept?
TimeBox: 45 minutes

Example Output

1. REPO MAP
- backend/invoices/: invoice models, API views and serializers, scheduled tasks (models.py, views.py, serializers.py, tasks.py).
- backend/billing/: fee logic in fees.py with its own tests/.
- backend/config/: Django settings and the Celery app (settings.py, celery.py).
- frontend/src/pages/Invoices/: invoice screens.
- frontend/src/api/: not opened.

2. FLOW TRACE (overdue invoice to reminder)
1) backend/config/celery.py: Celery app that runs scheduled tasks.
2) backend/invoices/tasks.py: the scheduled task that checks for overdue invoices and queues reminders.
3) backend/invoices/models.py: the Invoice model the task queries by due date and status.
4) backend/invoices/serializers.py and views.py: how invoice line items reach the API.
5) frontend/src/pages/Invoices/: where the invoice and its lines are shown.
Function names: confirm each in the opened file before you rely on this trace.

3. MERMAID DIAGRAM
```mermaid
flowchart LR
A[celery.py schedule] --> B[invoices/tasks.py overdue check]
B --> C[invoices/models.py Invoice]
C --> D[serializers.py and views.py API]
D --> E[frontend Invoices page]
B -. late fee? .-> F[billing/fees.py]
```

4. GLOSSARY
- Invoice: backend/invoices/models.py
- Fee: backend/billing/fees.py
- Reminder task: backend/invoices/tasks.py

5. CHANGE MAP
- backend/billing/fees.py: add the late fee rule. Tests: backend/billing/tests/. Risk: other fee types may share the same function.
- backend/invoices/tasks.py: call the fee rule at 30 days overdue. Tests: backend/invoices/tests/. Risk: the task may run daily, so the fee must not be added twice.
- backend/invoices/serializers.py: expose the new line. Risk: the frontend may expect a fixed set of line types.
- frontend/src/pages/Invoices/: show the fee line. Tests: no test found in the files opened.

6. QUESTIONS ANSWERED
- Where are overdue invoices detected? backend/invoices/tasks.py, run by the Celery app in backend/config/celery.py.
- Is there an existing fee concept? Yes, backend/billing/fees.py; read it before adding a new one.

7. STILL UNKNOWN
- How often the overdue task runs (check the schedule in backend/config/).
- Whether late fees need client consent or a contract term; ask the product owner.