Onboard me to this codebase as an engineer who needs to make a safe first contribution. The repository is [REPOSITORY OR FILE TREE]. The product or service does [SYSTEM PURPOSE]. My intended first task is [FIRST TASK]. The runtime and delivery context is [STACK AND ENVIRONMENT]. These are the available docs, commands, and constraints: [KNOWN DOCS AND COMMANDS]. Inspect the supplied repository material before making conclusions. Do not invent files, APIs, tests, deployment behavior, credentials, architecture decisions, or command results. Ask up to 3 clarifying questions only if a required input is unavailable. Produce an onboarding brief with:
1. A 10-minute orientation: entry points, application boundaries, request or event flow, data stores, external dependencies, configuration sources, and the most important directories. 2. A trace of the first task from trigger to user-visible outcome. Name the specific files, functions, types, routes, jobs, or components involved, and distinguish confirmed paths from likely paths. 3. A local setup checklist with exact commands only when supplied or evident; otherwise state what must be confirmed. Include required environment variables by name, without requesting or exposing their values. 4. A change plan: smallest safe implementation sequence, test layers to run, fixtures or migrations needed, rollback considerations, and likely edge cases such as authorization, retries, null data, concurrency, time zones, pagination, or backwards compatibility where relevant. 5. A glossary of project-specific terms and a list of five high-value questions for the maintainer. Before answering, self-check that every file reference appears in the supplied material and that you have not turned an inference into a fact. End with a concise “first PR checklist” that avoids unrelated refactoring.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [REPOSITORY OR FILE TREE] | Paste the repository link, file tree, relevant files, or an exported code context. | apps/web/src/app/api/invoices/route.ts, packages/db/schema.prisma, packages/billing/createInvoice.ts, apps/web/src/components/InvoiceForm.tsx, tests/billing/createInvoice.test.ts |
| [SYSTEM PURPOSE] | Describe what the application does and who uses it. | A web app where small agencies create and send client invoices |
| [FIRST TASK] | State the bug, feature, or investigation you need to complete first. | Add an optional purchase-order field to invoice creation and display it on the PDF |
| [STACK AND ENVIRONMENT] | List known languages, frameworks, databases, deployment platform, and local environment details. | Next.js, TypeScript, Prisma, PostgreSQL, Stripe, Playwright; deployed on Railway |
| [KNOWN DOCS AND COMMANDS] | Paste README excerpts, run and test commands, architecture notes, and contribution rules. | README: pnpm install, pnpm dev, pnpm test, pnpm playwright test; DATABASE_URL is required locally |
How to use
- Paste a file tree plus the files nearest to your first task; a repository URL alone may not give the model enough context.
- Ask the model to trace the path, then compare named files and commands with the repository before acting.
- Run the proposed narrowest test first and add a regression test for the behavior you change.
- Follow up with: “Now write the smallest implementation plan as ordered edits, preserving existing conventions and listing uncertain assumptions.”
Variations
Architecture walkthrough
Use this when you need a system map before choosing a task.
Explain the architecture of [REPOSITORY CONTEXT] for an engineer joining [PRODUCT]. Produce a component map, request and data flows, ownership boundaries, configuration sources, external dependencies, test strategy, deployment path, and the three highest-risk areas. Cite files or supplied documentation for each conclusion. Do not invent architecture facts. Ask up to 3 questions only if needed, then label every inference and list the evidence that would confirm it.
Bug investigation plan
Use this when a bug report exists but the cause is unknown.
Create a debugging plan for [BUG REPORT] in this code context: [REPOSITORY CONTEXT]. The observed behavior is [OBSERVATIONS], and these logs or errors are available: [EVIDENCE]. Produce ranked hypotheses, the smallest discriminating check for each, files and code paths to inspect, reproducible test cases, instrumentation suggestions that avoid sensitive data, and a fix-validation plan. Do not diagnose without evidence. Ask up to 3 questions if essential, then separate confirmed facts from hypotheses.
First pull request
Use this when you know the task and need a narrow implementation scope.
Plan a first pull request for [TASK] in [REPOSITORY CONTEXT]. Existing conventions and constraints are [PROJECT RULES]. Produce the intended behavior, non-goals, ordered file-level edits, test cases, migration or compatibility considerations, code-review risks, and a concise PR description. Do not write changes outside the stated scope or invent files. Ask up to 3 questions only if necessary, then check that the plan has one observable acceptance criterion for every requested behavior.
Tips
- Trace one user action end to end before reading every directory; it reveals the real boundaries faster than a broad tour.
- Keep inferred behavior labeled until a test, log, or source file confirms it, especially around authentication and billing.
- Find the nearest existing test before adding code; it usually shows fixture setup, naming, and expected error handling.
- Make your first change narrow enough to review easily, then defer cleanup that is not required for the requested behavior.
FAQ
What should I give Claude Code for onboarding?
Provide a file tree, README, run and test commands, and files near your first task. Add error output or issue context when you are investigating a problem.
Should I let it run every command it suggests?
No. Confirm project commands and inspect scripts first, particularly commands that migrate databases, deploy, seed shared environments, or modify generated files.
How do I avoid a huge first PR?
Ask for explicit non-goals, a smallest safe path, and acceptance criteria. Keep refactoring separate unless it is necessary to make the change correct.