Prompt Engineering

Onboarding Codebase — Explain Code to a New Team Member

A capable engineer with zero context on your codebase needs different explanations than a junior: conventions, vocabulary, and where everything connects — not syntax.

Overview

Onboarding explanations routinely miscalibrate: they either explain programming (insulting a strong hire) or assume tribal knowledge (losing them). This prompt uses the new-team-member audience profile, which gets the calibration right: assume strong general engineering, assume zero knowledge of this system's conventions, vocabulary, and history. Codebase-specific names and domain terms get explained the way an onboarding buddy would, and every part gets connected to the bigger system — where it is called from, what depends on it. Paired with the high-level overview mode, the result is the explanation that turns week-one confusion into a working map.

Workflow

Calibrate to the real reader
Strong engineer, zero codebase context — neither syntax lessons nor assumed tribal knowledge.
Decode the vocabulary
Codebase-specific names and domain terms explained like an onboarding buddy would.
Connect every part to the system
Where it is called from and what depends on it — the map that makes the code navigable.

Why This Works

The strong-engineer/zero-context split is exactly what generic explanations miss
Domain vocabulary is the actual barrier in mature codebases, not the code
System connections turn an isolated explanation into a usable map

Best for

Teams onboarding engineers into mature codebases
New hires self-serving understanding between pairing sessions
Modules with heavy domain vocabulary

Not for

Teaching programming concepts to beginners — that's this tool's Beginner Friendly mode, a different contract
Writing the onboarding documentation — that's the Markdown Output Builder

Use cases

Walking a new hire through the module they'll own
Explaining domain vocabulary the code assumes
Building the system map week one usually lacks

Customize This Resource

Opens this setup in Code Explanation Prompt. Generate to get the full understanding contract — then adjust the mode, audience, and depth.

Open in Code Explanation Prompt

Prompt Template

EXPLANATION OBJECTIVE
Explain the order processing module to a developer who joined the team this week.
Explanation mode: high-level overview — what this code is for and how it fits the system.
The goal is understanding, not judgment: explain what this code does and why it is built this way — and clearly separate what the code shows from what you infer.

CODE CONTEXT
System context: E-commerce platform; orders flow from cart through payment to fulfillment, with inventory checks at each step.
Code to explain:
```
[Paste the code to explain here]
```

AUDIENCE PROFILE
Audience: a new team member — a capable engineer with zero context on this codebase.
- Assume: strong general engineering; no knowledge of this system's conventions, vocabulary, or history.
- Explain codebase-specific names, conventions, and domain terms the way an onboarding buddy would.
- Connect each part to the bigger system: where it is called from, and what depends on it.

EXPLANATION STRATEGY
1. Lead with purpose: what problem this code solves and who or what calls it.
2. Map the major responsibilities — the three to five jobs this code actually performs.
3. Place it in the system: upstream callers, downstream dependencies, and its role between them.
4. Walk the important workflows end to end at the level of steps, not statements.
- Depth: detailed explanation — thorough coverage of behavior and structure.
- Cover every section of this contract with real content — no skipped or token sections.
- Go as deep as the code requires, but no deeper: detail serves understanding, not completeness theater.

KEY CONCEPTS
- Name the central concepts a reader must hold to reason about this code — the domain objects, the states, the contracts between parts.
- Order concepts by how load-bearing they are for understanding this code — not by where they appear in the file.

EXECUTION FLOW
- Describe the main workflows as numbered step sequences — what triggers each, what it produces, and what can short-circuit it.
- Where the flow depends on state or configuration, say which, and what each setting changes.

DESIGN DECISIONS
- Point out the structural decisions visible at this altitude: how responsibilities are divided, and what that division suggests about the system's priorities.
- Discuss only decisions actually visible in the code; rationale you cannot evidence belongs under ASSUMPTIONS, labeled as inference.

ASSUMPTIONS
- Separate what the code DOES (verifiable from the source) from why it might be that way (inference).
- Label every statement about intent, history, or rationale as an INFERENCE unless the code itself evidences it — a comment, a test, a telling name.
- Where behavior cannot be determined from the provided code, say "cannot be determined from this code" — never fill the gap with a plausible story.

TRADEOFFS
- Identify the tradeoffs this code embodies: what it optimizes for, and what it sacrifices for that.
- Tie each tradeoff to its visible consequence in the code.

LEARNING NOTES
- Close with the three things to remember about this code — the summary a colleague would give at a whiteboard.

NON-GOALS
- Do not review code quality — no findings, no severities, no verdicts.
- Do not debug failures — explain the behavior that exists without diagnosing it.
- Do not refactor the code or propose rewrites.
- Do not generate tests.
- Do not invent requirements or unstated intentions.
- If something looks defective, note it as a question for the team — investigating or fixing it is out of scope.
- Clearly separate facts from assumptions throughout.

OUTPUT REQUIREMENTS
- Structure the explanation with headings that mirror the sections above — a reader should be able to navigate it without reading all of it.
- Anchor every claim about behavior in the code: name the function, branch, or line it comes from when precision matters.
- Calibrate every section to the stated audience — too basic wastes their time, too advanced loses them.
- End with the open questions: what could not be determined from the provided code, and who or what could answer it.

Related Resources

Explore more resources that work well with this one.

Used in Playbooks

Complete workflows that include this resource as a step.

AI Codebase Onboarding Workflow Workflow · 4 steps

Tip: Save time by exploring related resources and tools that integrate with this workflow.

Explore all resources