Verified against Cursor · 2026-08-06
Have Cursor's Agent mode explore an unfamiliar codebase and write the onboarding doc you don't have
A brief for using Agent mode's codebase-wide search and read access to produce a real onboarding document for an undocumented or under-documented repo, grounded explicitly in what the agent actually traced through the code rather than a generic description of what a project 'like this' would typically contain.
The prompt
Ready to copy — highlighted parts are example details you can swap.
Explore this codebase and write an onboarding document for a new engineer joining this project, with nothing to go on except what's actually in the repository. Do not describe what a project of this general type would typically contain — describe what this specific one actually does, based on what you traced.
PROJECT CONTEXT YOU ALREADY KNOW
This is an internal tool for the ops team to manage vendor contracts. Built on Next.js. I inherited this repo and have never worked in it before.
SPECIFIC AREAS THE ONBOARDING DOC MUST COVER
How authentication works, how the vendor data gets imported (there's a cron job somewhere, I think), and what the difference is between the two similarly named directories app/vendors/ and app/vendor-admin/.
DEPTH LEVEL
First-week orientation depth — enough to be productive on a small first task, not a comprehensive architecture reference.
WHAT TO PRODUCE
1. A short "what this is and what it does" section — grounded in the actual entry points and routes you found, not the README's aspirational description if the two disagree.
2. An architecture overview naming the actual major modules/directories and what each one is responsible for, based on what you found by reading them, not by their names alone.
3. "How to run this locally" — traced from the actual package scripts, config files, and any setup steps that appear to be required based on what the code actually reads at startup (env vars, config files, expected running services).
4. "Where things live" — a short map from common task types ("add an API route," "add a UI component," "add a background job") to where in the repo that kind of change actually goes, based on existing examples of each.
5. A "known gaps and rough edges" section: anything you noticed while exploring that a new engineer would hit and be confused by — an undocumented env var, a module that looks unused but is actually load-bearing, a naming inconsistency between two similar-looking directories.
RULES
- If the README or existing docs claim something the code doesn't actually support, or no longer matches what you traced, flag the discrepancy explicitly rather than reporting the doc's claim as current fact.
- Do not fabricate a setup step, a script, or an env var that you didn't actually find referenced somewhere in the codebase — if something about local setup is genuinely unclear from what's available, say so rather than guessing at a plausible-sounding default.
- Keep this to the depth level specified — a document written for someone's first day should not be the same length or level of detail as a deep architecture reference.Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
Agent mode's codebase-wide semantic search and read access is what makes this task possible at all in one pass rather than requiring someone to already know the codebase well enough to write the doc themselves, but that same breadth of access is also what makes "describe what a project like this typically contains" a real risk — a model can produce a plausible-sounding architecture overview for a generic Next.js admin tool without having actually traced a single one of this specific repo's real entry points, and that output will read as helpful right up until the new engineer tries to follow it and finds the described module doesn't exist under that name. Explicitly instructing it to ground the "what this is" section in actual traced entry points rather than the README's description matters because a README is exactly the kind of artifact that goes stale the moment the project's actual direction shifts and nobody circles back to update the framing paragraph at the top, so treating it as one input to check against the real code rather than as the primary source is what keeps the onboarding doc accurate rather than merely readable. The "known gaps and rough edges" section is the part a generic "document this codebase" request would never produce, because it requires the model to hold two different things in mind simultaneously while exploring — what the code does, and where a newcomer with no prior context would specifically get confused by it — and that second framing only gets applied if it's explicitly requested, since describing intended behavior and describing where intended behavior is likely to mislead a first-time reader are genuinely different tasks even though they draw on the same exploration. The rule against fabricating a setup step or env var closes the single most damaging failure mode for this specific kind of document: an onboarding doc is trusted uncritically by definition, since the reader has no independent way yet to know the codebase well enough to notice a fabricated instruction is wrong, so a plausible-sounding but invented setup step doesn't just fail to help, it actively costs a new engineer real debugging time chasing a step that was never real.
Verified against
Cursor 2.2 · 2026-08-06
Changelog
- 2026-08-06 — Initial publish, verified against Cursor 2.2 Agent mode on an undocumented internal tool repo.
Need this built into your business?
If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
