Navigating an unfamiliar codebase: five questions asked aloud, in order

The first week in a foreign repo has a recognizable shape: the readme is two years old, the architecture doc was never written, and the codebase answers questions only when asked the right way. Every question the new hire asks gets a fragment in response: the queue is over there, that table is legacy, those services were split last year. The fragments arrive one at a time, the questions get asked one at a time, and the map in the new hire's head stays a collection of scraps rather than a picture. After a week the panic sets in, because the team expects contribution and the only thing the repo hands you is an invitation to grep, which is why navigating an unfamiliar codebase is a question-design problem rather than an effort problem.

The fragments are not the team's fault, they are the seam of the problem. The team has the map, but the map lives in the heads of the people who lived the history, and every question reconstructs a sliver of it with a fresh context switch. The fix is not to write a giant onboarding document, which nobody has time for and which ages badly; the fix is to design the inquiry itself, so that five well-ordered questions elicit the whole map in one conversation instead of thirty fragments across a month. This is a navigational problem, and navigational problems are solved with a route, not with more patience.

The voice is the right instrument for the inquiry because the questions need to be asked in sequence and the answers need to be held in your head at once. Typing a question, waiting, reading a paragraph answer, then typing the next one fragments the thread, and the map never assembles. Spoken questions, asked in a row to the repo through an agent, keep the conversation in one stream, and the agent can climb the stack while you hold the map together. New engineers who narrate their way in report the same effect: the repo starts to sound like a place instead of a pile, around hour two of focused asking.

The deadline to contribute puts a floor under the panic, and the floor is a good thing: it means the question design matters. The alternative to a designed inquiry is the industry-standard mess, the two-month drift where the new hire ships their first real task by copy-pasting a pattern from somewhere nearby and hoping. The designed inquiry compresses that drift into days, and it should be booked as a proper session, one hour, mic on, no calls, with the permission of the team: I am going to interrogate the repo, and I will come out with five questions answered. The session is the very first work item the new hire completes, and it is the one that makes everything after it faster.

The five questions are constant; asking them in a row on any codebase produces a usable map, and they are worth memorizing because they are the same five on every team. The first: where does a request enter and leave, in the widest sense? Follow one user action end to end, from the HTTP handler to the response, and name the services it crosses. The second: where does the state live, and who writes it? The databases, the caches, the message queues, and the one table that everything reads. The third: what is the deployment unit, and what does a release actually do? The pipeline, the migrations, the feature flags, the rollback. The fourth: who calls whom, and what breaks first? The dependency direction plus the two or three components that are load-bearing. The fifth: what is weird here, on purpose?

The fifth question is the one new hires never ask and the one that saves a week, because every long-lived codebase carries deliberate weirdness: the service that still owns a legacy table because the migration is too risky to schedule, the endpoint that returns a wrapper format only some clients expect. The weirdness looks like internal inconsistency to a newcomer and like careful trade-off history to the team, so the question should be asked with the frame of intent: what looks wrong or redundant here that is actually keeping something alive? The spoken answer is the difference between a new hire who respects the weirdness and a new hire who has scheduled a cleanup ticket for it, which is exactly the kind of ticket that never gets approved.

The five questions are also a filter for the documentation you will write, since the map they produce is the skeleton of the onboarding doc the team never got around to. Answer them in one sentence each while you are asking, out loud, so the assistant transcribes them into a note: requests enter at the gateway and leave through the worker; the state lives in the orders database with the hot cache in front; a release is a migration plus a flag flip; everything reads the pricing service; and the weirdness is the double-priced row, which is historical and guarded. Five sentences is the whole treasure, and the treasure is the map.

The questions flatten the codebase because they are shape questions rather than detail questions. Asking how a specific function works teaches you the function; asking where requests enter teaches you the architecture. New hires default to detail questions at the exact moment they need shape, and the shape questions feel too broad to ask a colleague, so they are exactly what an agent is for: the agent answers shape questions without worrying whether the question is polite, and it can be asked to follow the flow until it reaches the end. The five questions are the route, the code is the terrain, and the walk is entirely in your voice.

The order is part of the method, because the codebase answers the five questions in an order of its own, and starting with the entry point is how the answers chain. Ask question one first and follow the flow to the end; the flow's end introduces the state, which is question two; the state owners introduce the deploy story, question three; the service boundaries reveal the dependency direction, question four; and the journey surfaces the strange, question five. The chain is why the session works in one hour rather than in scattered afternoons: each answer is the door to the next question, and asking them aloud holds the chain together in a way that asking them in separate chat threads never will.

Name the things as you meet them, because naming is the retention mechanism: this service is the order writer, these three services are the order readers, this table is the order state. The names you give become your working vocabulary, and the vocabulary is what makes the friday standup comprehensible, since the team's jargon will need mapping onto your names, and the mapping is an exercise you do out loud. Ask the agent to keep a running glossary as you speak, and at the end of the hour review the glossary aloud; the review is the memory pass, and the memory pass is what turns the hour into a week's worth of context.

Resist the detours: the codebase will offer them, the interesting bug in the retry logic, the dead code with the funny name, and they are the exact places an hour-long exploration dissolves. Say the detour rule out loud at the start: if something is interesting but not on the route, I will note it in the glossary and keep walking. The noted detour becomes a later ticket and the walk stays on schedule, which is the difference between a map and a procrastination engine. Attach the same rule to the answers: if an answer opens a question that is not one of the five, note it and move on.

The order changes for a codebase with no entry point you can find, which happens in the batch-worker world, and the fix is to ask question two first, where does the state live, since state is the anchor that everything else hangs on. Say the swap out loud when you feel the first question failing: this repo has no web entry, so I am starting with the state and working outward. Changing the route deliberately is fine, changing it without noticing is how the five questions become zero questions. The route's purpose is not the order, it is the completion, and completion is measured by the moment you can say all five answers in one breath.

A map is only a map when it gets walked, so the session ends with the test: pick the two changes that the team actually wants, the small ones that are already on the board, and predict, out loud, where each one touches. Say the prediction before opening anything: the price display change touches the pricing service, the renderer, and the two tests that pin the format; the notification change touches the worker and the email template. Then make the first change with the agent, and compare the real walk against the prediction. Every mismatch is a correction to the map, and the correction is the point, since a day of predicting and walking is worth a week of discovering by surprise.

The first change should be the one with the fewest surprises, so that the map's forecast gets a fair test, and the second should be the one that crosses a boundary you are unsure about, since the boundary is where the map is weakest. Doing the second change immediately after the first loops the agent's context through two real paths, and the two paths give you the shape of the territory rather than just the shore of it. The prediction and the walk are both done out loud, and when reality disproves the forecast, the sentence is recorded rather than swallowed: I expected the renderer to read the pricing service directly, but there is a cache in between, so the map gets a new node with a note that the cache is the part nobody mentioned.

The team's review of your two small changes is the social test of the map: the reviewer comments on the diff, and you can now place every comment in context, because you know the shape of the house you are renovating. The reviewers will notice the difference within a week, the questions you ask will be map questions rather than panic questions, and their answers will be shorter because your references are correct. When you ask, does this touch the double-priced row, the team knows you have the weirdness in your map, and the question that would have taken a whole conversation lands in ten seconds. That speed is the metric of onboarding done well.

Finish the test pass by updating the glossary with the corrections and by saying the five answers one more time, this time with the cache and the pipeline detail included. The second reciting is the moment the map becomes yours, and the moment the panic is genuinely over, not because the repo got documented but because you can navigate it. If the two changes felt easy and their diffs were small, the session has done its work: the first week now ends with a map instead of a shrug, and the second week can start with contribution, which is what everyone on the team, including you, actually wanted from this onboarding.

The map is too valuable to walk away with: leave a trail, and make the trail in the medium you discovered the map in. Record a voice walk, ten minutes, in which you answer the five questions in order, using the names you coined and the corrections the test pass produced: requests enter at the gateway, and the pricing cache is the part that surprises everyone, so check it before you blame the pricing service. The recording is the onboarding artifact, because it carries the judgment of what is normal and what is weird, which is the exact thing the documentation always leaves out. A ten-minute recording made by the last new hire is worth a fifty-page architecture doc written by someone who no longer remembers being new.

The written half of the trail is the glossary and the five answers, updated with the corrections, placed where the next hire will look, the repo's readme or the team's wiki, alongside the recording link. Keep both short, because the goal is the map, not the manual, and a map that fits on one screen is the kind that gets read on day one, while a manual that runs to forty pages gets read by nobody and maintained by nobody. The trail is also the maintenance loop: when the pricing cache moves, the next hire's correction lands in the glossary, and the glossary stays honest without any of the team having to write documentation, which is the original sin that caused this whole situation.

The recorded trail is also a testing artifact for the next hire: hand them the recording and the two changes, and watch how long the onboarding takes. If the next hire walks the same route in a day, the trail has worked, and if they get stuck at the same place you got stuck, the trail has a hole, and the hole is now visible rather than secret. Say the hole-fix aloud when you find it, and let the patched glossary be the evidence of the team's onboarding improving, since a team that measures its onboarding in the hours of the newest hire is a team that will keep improving it. The measurement is one of the few metrics that actually get better when watching them.

The trail's final piece is the invitation: put the five questions in the team's onboarding doc as the official first task, and let the next hire know that the map is expected before any feature work, because the team that expects a map gets a hire who can build one. The five questions become part of the culture rather than a personal trick, and the hour of interrogation becomes a rite of passage rather than a lonely struggle. Onboarding into a foreign repo stops being a test of courage and becomes a procedure with a route, and the new hire who completes it in their first week is the one who starts saying the team's jargon fluently in their second, which is the fastest possible signal that the trail did its job.