# Cursor AI: Fast Onboarding to an Unfamiliar Codebase

> A repeatable prompt sequence for using Cursor to map, explain, and safely modify a codebase you've never seen before.

**Platform:** Cursor  
**Category:** coding  
**Difficulty:** Beginner  
**Tags:** cursor, coding, onboarding  
**Updated:** 2025-04-30  
**Source:** https://promptfoo.tech/workflows/cursor-ai-project-onboarding

## Overview
Joining an unfamiliar codebase is where AI coding tools save the most time — if you use them structurally. This workflow uses Cursor's chat, @codebase, and @docs features in a specific order to build a mental model before you touch a line of code.

## How it works
1. Open the repo in Cursor and let indexing finish before asking anything.
2. Ask for an architectural map: entry points, boundaries, and data flow.
3. Ask for the 'unusual choices' — anything that would surprise someone new.
4. Pick one feature and ask for a call-graph from user action to database.
5. Only then make a first change, using the map as context.

## Benefits
- Two hours saved on day one is worth ten hours of hunting later.
- You learn conventions before overwriting them.
- Better first PRs mean faster team trust.

## Use cases
- Contractors dropping into a client codebase.
- New hires in their first week.
- Anyone auditing an inherited legacy repo.

## Step-by-step
### Step 1: Index the repo
Open in Cursor. Wait for the indexer icon to go quiet before asking questions — early answers are worse.

### Step 2: Ask for the architecture
Prompt: 'Give me a one-page architectural map: entry points, layers, and data stores. Cite files.' Verify by opening a few cited files.

### Step 3: Ask for the surprises
Prompt: 'What are 5 unusual or non-obvious choices in this codebase a new engineer would need to know?' This surfaces implicit conventions.

### Step 4: Trace one feature end to end
Pick a real user action. Ask Cursor to trace it from UI event to database, listing every file it touches.

### Step 5: Make a scoped first change
Choose a small, well-bounded task. Reference the map in your prompt so Cursor stays inside the intended boundary.

## FAQs
**Will Cursor hallucinate architecture?**

It can — always verify cited files exist and contain what it claims. The verification step is why this works.

**Does this work with monorepos?**

Yes, but ask per-package. A single map across a 15-package monorepo will be too abstract to be useful.

**Which model is best?**

Cursor's default Sonnet is a strong baseline. Use a stronger model for the architecture map, and a faster one for edits.

---
Licensed under CC-BY-4.0. Attribution: PromptFoo.tech