Verified against Gemini · 2026-07-23
Turn an entire small-to-mid codebase into an onboarding doc a new engineer can trust
A long-context prompt that reads a whole repository — every file pasted or uploaded, not a handful of representative snippets — and produces an onboarding document that names actual file paths and real architectural seams, instead of generic advice that could describe any Next.js or Python project.
The prompt
Ready to copy — highlighted parts are example details you can swap.
I'm giving you the source of a 40-file Next.js App Router site with a Postgres backend via Prisma. Read the whole thing before writing anything — all files under app/, lib/, and prisma/ — roughly 6,800 lines total — this only works if you're describing what's actually in these files, not what a project like this "would typically" look like. WHO THIS IS FOR a mid-level engineer who knows Next.js well but has never seen this specific codebase MUST COVER how a request flows from a route handler to the database, where environment configuration actually lives, and what happens when a request is unauthenticated INSTRUCTIONS 1. Trace at least one real request or data flow end to end, naming the actual files involved in order — not a generic "the frontend calls the backend which calls the database" description that would apply to almost any web app. 2. Name the two or three files that are load-bearing enough that a mistake in them would break a large part of the system, and explain why, using what you actually found (heavy import fan-in, shared config, a central data model), not a guess about what's typically important in a codebase like this. 3. If you look for something specific — rate limiting, authentication, error handling — and genuinely can't find it anywhere in what I gave you, say plainly that you didn't find it, rather than describing how it "would typically be implemented" as if that were a fact about this codebase. 4. Known gotchas already understood by the team: lib/legacy-adapter.ts looks dead but is still imported by one scheduled cron job — don't flag it for deletion. — incorporate these rather than contradicting them from a fresh read that doesn't have this context. 5. Flag anything that looks like dead code or an unused file only if you can point to the actual evidence (no imports found anywhere in what was provided) — and even then, phrase it as "appears unused based on what I read," not a confident claim, since a partial upload can hide the one file that imports it. CONFIGURATION AND ENVIRONMENT Separately, list every place configuration actually lives — environment variables, config files, feature flags — and for each one, name the specific file where it's read, not just "config is handled via environment variables" as an unattributed generality. A new engineer's first real blocker is usually a missing or misconfigured environment variable, and a vague pointer wastes exactly the time this document is supposed to save. DEPENDENCIES WORTH FLAGGING Note any dependency that's doing unusually heavy lifting relative to how invisible it is in the code — a small utility import that's actually load-bearing across dozens of files, or a dependency whose version is pinned in a way that suggests a known compatibility issue. Skip a generic list of every dependency in the manifest; that's not useful and isn't what this document is for. OUTPUT FORMAT A short onboarding document: an architecture overview naming real files, the traced flow from step 1, the load-bearing files from step 2 with reasons, the configuration map, anything from step 3 you looked for but didn't find, and a "things to verify with a teammate before relying on this" section listing your own uncertainty, not just confident claims.
Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
Reading the whole repository in one context, instead of a handful of representative files chosen ahead of time, is what lets Gemini trace an actual import chain end to end and cite real file paths — a documentation pass built from a sample can only ever describe what a codebase like this typically looks like, which produces prose that reads as competent but is subtly wrong about this specific repository the moment it's checked against the actual files. The explicit instruction against inventing a typical implementation when something can't be found targets a very specific and common failure: when a model searches for a feature (say, rate limiting) and doesn't find it, the fluent default is to describe how such a thing is usually built in a stack like this one, which reads exactly like a factual claim about the codebase in front of it but is actually a guess dressed as documentation — a new engineer trusting that sentence would waste real time looking for a safeguard that was never actually implemented. Naming the load-bearing files by pointing to concrete evidence (import fan-in, a shared central data model) rather than intuition gives a checkable claim instead of an opinion — a reviewer can verify 'twelve other files import this one' far more easily than they can verify 'this feels important.' Seeding known team gotchas up front prevents the single most damaging failure mode of a fresh-eyes codebase read: flagging something the team already knows is intentional (a file that looks dead but is quietly load-bearing for one cron job) as a cleanup candidate, which is a mistake an onboarding document written by someone who does know the code would never make and a document generated without that context easily would. Requiring the configuration map to name the exact file where each setting is actually read, rather than a general statement that configuration is environment-driven, matters because the specific failure a new engineer hits in their first week is almost never architectural curiosity — it's a missing environment variable or a misread config file, and a document that describes the pattern in the abstract without pointing at the concrete file leaves that person doing the same repository-wide search the document was supposed to save them from doing themselves.
Verified against
Gemini Gemini 3 Pro · 2026-07-23
Changelog
- 2026-07-23 — Initial publish, verified against Gemini 3 Pro reading a full 40-file Next.js repository in one pass.
Need this built into your business?
If a prompt isn't enough — what Scult builds, built and maintained for you — that's Scult's day job.
EXPLORE WHAT SCULT BUILDS
