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
- Open the repo in Cursor and let indexing finish before asking anything.
- Ask for an architectural map: entry points, boundaries, and data flow.
- Ask for the 'unusual choices' — anything that would surprise someone new.
- Pick one feature and ask for a call-graph from user action to database.
- 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 guide
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.