Playbooks · Coding agents

Onboard onto an unfamiliar codebase with an agent

A new hire maps a codebase they did not write, using Copilot Chat to explain code in small pieces and checking each explanation against the code itself.

Audience: New hire · Stack: Any repo in VS Code, with Copilot Chat available · Tool: GitHub Copilot Chat in VS Code, @workspace and /explain

Before you start

The repo cloned and running locally, or at least opening in your editor. Explanations of code you cannot run are harder to check.
Copilot Chat available in your editor. The author docs describe @workspace as the participant with context about the code in your workspace, for questions about project structure, how parts interact, and design patterns.
A notebook or scratch file for your own map. The agent's answers are not the map; your notes, checked against the code, are.
The name of one real task you will do in your first week — a bug, a small feature, a question from a teammate. Onboarding without a task drifts into reading everything and retaining nothing.

Steps

Start with structure, not details. Ask with @workspace: how is this project laid out, what are the main parts, and how do they interact? Write the answer down as a sketch, then verify each part exists in the file tree.
Pick the part your first task touches. Select its entry-point code and run /explain, which the author cheat sheet describes as explaining how the code in the active editor works. Read the explanation with the code open beside it.
Follow one request through the code by hand: from the entry point, through each function it calls, to the result. Ask the agent about each hop you do not understand, one question at a time, and check each answer in the code before moving on.
Find the tests for that part and read them. Tests show intended behaviour more plainly than explanations do, and they show what the team considers worth guarding.
Write your own one-page map: the parts, the request path, the data it touches, and the three things you still do not understand. Bring the three unknowns to a teammate, not to the agent — a teammate knows which unknowns matter.
Do the small first task with the agent's help, but make the change yourself where you can. The goal of onboarding is your understanding, and understanding comes from editing, not from reading explanations.
At the end of the first week, revisit your map and correct it. The corrections are the measure of what you actually learned.

Worked example

A new hire joins a team that runs a small booking service. Their first task is to fix a double-booking report. They ask @workspace for the project layout and learn there are three parts: a web layer, a booking service, and a store. They select the booking endpoint, run /explain, and follow one booking request by hand from the endpoint through availability checking to the store write. The explanation claims availability is checked inside a transaction; reading the code, they find the check and the write are separate steps — that gap turns out to be the double-booking cause. Their one-page map records the gap as an open question for a teammate, and the fix becomes their first real task, understood rather than pasted.

What can go wrong

The agent's explanation sounds confident and contradicts the code. Fix: trust the code. Note the contradiction and ask a teammate; confident explanations of wrong code are the main hazard of this playbook.
You have read for days and cannot describe the request path. Fix: stop reading. Pick the smallest real task and follow one request through it by hand — that path is the map.
The agent answers about a different part of the codebase than you asked about. Fix: narrow the question to one selected function and use /explain on that selection, rather than asking workspace-wide questions.
Your map is a copy of the agent's answers. Fix: rewrite it from memory, then check it against the code. Anything you cannot rewrite, you have not learned yet.

Limits

The agent explains code; it does not know your team's history, why a decision was made, or which parts are slated for replacement. Those answers live with teammates.
Explanations are only as good as the context the workspace participant has. A partial checkout or a missing part of the repo will produce partial explanations presented as complete ones.
This playbook builds orientation, not expertise. Shipping a large change in week one on the strength of agent explanations alone is not what it recommends.

Time and cost: NOT_MEASURED. This page gives no time or cost figure because the tool docs fetched for it state none that applies to this task.

Verification

Checked 2026-10-23 against the author's own docs. The workflow on this page was not run end to end; every command, flag, and capability claim was checked against an author doc or repo fetched that day.

Cut from this page, with reason:

No claim that @workspace understands the whole repo in every setup: the author docs describe its context role, and the page treats explanations as claims to check.
No time figure: onboarding time varies by codebase and is NOT_MEASURED here.
No cost figure: none stated on the fetched author pages, so none is given.

If a step here does not match what your installed tool shows, trust the tool's own docs for your version and stop before approving a change you cannot read.

Back to: Coding playbooks hub · Skills index