{
  "$schema": "https://promptfoo.tech/schemas/workflow-template.json",
  "name": "Cursor AI: Fast Onboarding to an Unfamiliar Codebase",
  "slug": "cursor-ai-project-onboarding",
  "platform": "Cursor",
  "category": "coding",
  "difficulty": "Beginner",
  "tags": [
    "cursor",
    "coding",
    "onboarding"
  ],
  "summary": "A repeatable prompt sequence for using Cursor to map, explain, and safely modify a codebase you've never seen before.",
  "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.",
  "variables": {},
  "steps": [
    {
      "order": 1,
      "name": "Index the repo",
      "description": "Open in Cursor. Wait for the indexer icon to go quiet before asking questions — early answers are worse."
    },
    {
      "order": 2,
      "name": "Ask for the architecture",
      "description": "Prompt: 'Give me a one-page architectural map: entry points, layers, and data stores. Cite files.' Verify by opening a few cited files."
    },
    {
      "order": 3,
      "name": "Ask for the surprises",
      "description": "Prompt: 'What are 5 unusual or non-obvious choices in this codebase a new engineer would need to know?' This surfaces implicit conventions."
    },
    {
      "order": 4,
      "name": "Trace one feature end to end",
      "description": "Pick a real user action. Ask Cursor to trace it from UI event to database, listing every file it touches."
    },
    {
      "order": 5,
      "name": "Make a scoped first change",
      "description": "Choose a small, well-bounded task. Reference the map in your prompt so Cursor stays inside the intended boundary."
    }
  ],
  "howItWorks": [
    "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."
  ],
  "useCases": [
    "Contractors dropping into a client codebase.",
    "New hires in their first week.",
    "Anyone auditing an inherited legacy repo."
  ],
  "example": null,
  "faqs": [
    {
      "q": "Will Cursor hallucinate architecture?",
      "a": "It can — always verify cited files exist and contain what it claims. The verification step is why this works."
    },
    {
      "q": "Does this work with monorepos?",
      "a": "Yes, but ask per-package. A single map across a 15-package monorepo will be too abstract to be useful."
    },
    {
      "q": "Which model is best?",
      "a": "Cursor's default Sonnet is a strong baseline. Use a stronger model for the architecture map, and a faster one for edits."
    }
  ],
  "source": "https://promptfoo.tech/workflows/cursor-ai-project-onboarding",
  "updated": "2025-04-30",
  "license": "CC-BY-4.0"
}