Claude Code Learning Hub
中文 Mingyu's Library

Hub / Tips / F · End-to-end scenarios

Five questions to ask on day one with an unfamiliar codebase

Joining a new team or inheriting someone else's project? On day one, instead of digging through the code yourself, let Claude Code be your guide: ask five questions in order and you walk away with a map you can actually work from.

The official docs' advice is "treat Claude like a senior colleague and just ask" — no special prompting tricks required. This page turns that advice into a five-question checklist you can run on day one, each question with a single purpose, ending with the conclusions distilled into CLAUDE.md.

One-line answer

Answer Start Claude Code at the project root (ideally switching to plan mode first for read-only exploration), then work through five questions from broad to narrow — architecture overview → entry points and data flow → build and test commands → conventions and pitfalls → what's changed recently — and finish by running /init to distill the conclusions into CLAUDE.md. Going from broad to narrow is the officially recommended way to explore; the five-question framework is our arrangement of it.

Steps

  1. Prepare: go to the project root and run claude, then press Shift+Tab to switch to plan mode (the status bar shows ⏸ plan mode on); Claude reads files without modifying anything — ideal for pure exploration on day one. OfficialThe official recommendation is "explore first", starting with broad questions and narrowing down. See D5 · plan mode.
  2. Question 1 · Architecture overview: ask for the bird's-eye view first — what the repo does, what modules it has, what tech stack and architecture patterns it uses. OfficialThis is the first step of the official "Understand new codebases" workflow; the verbatim prompt is give me an overview of this codebase, followed by explain the main architecture patterns used here. Expect a list of modules and their responsibilities.
  3. Question 2 · Entry points and data flow: where the program starts, and which layers a typical request passes through. OfficialThe official recipe: trace the login process from front-end to database — swap in whatever path is most central to your project. Expect a call path annotated with file names.
  4. Question 3 · Build and test commands: how to install dependencies, run the project locally, and run tests and lint. Our takeGetting the commands and running them on the spot is the most concrete win of day one — documentation for a project you can't get running is worth nothing.
  5. Question 4 · Conventions and pitfalls: which practices in this project differ from the defaults. OfficialThe official tips explicitly suggest "ask about coding conventions and patterns used in the project" and "request a glossary of project-specific terms". Expect a glossary plus a list of project-specific conventions.
  6. Question 5 · What's changed recently: have Claude read the git history and summarize active branches and frequently changed files. OfficialThe "Point to sources" pattern from best practices: rather than asking "why is this API so weird", tell it to look through the git history and summarize. You learn what the team is pushing forward and which areas are minefields.
  7. Wrap-up · Distill: run /init; it analyzes the codebase, detecting the build system, test framework, and code patterns, and generates an initial CLAUDE.md. Fold in the key conclusions from today's five questions (commands, conventions, pitfalls), then confirm it's loaded with /context. OfficialCLAUDE.md is read at the start of every session — keep it lean and only include what applies universally. See D4 · CLAUDE.md and rules.

Our takeIn large repos, questions 1 and 2 can easily pull a huge number of files into context and blow it up: ask Claude to "investigate with a subagent" so only the conclusions come back to the main session (see D10 · Subagents); if context gets dirty between questions, run /clear.

Copy-paste prompt

I just took over this codebase today. Working read-only, answer five questions for me in order, pausing after each one for my confirmation:
1) Architecture overview: what does this repo do? What modules does it have, and what is each responsible for? What tech stack and architecture patterns does it use?
2) Entry points and data flow: where does the program start? Pick the most central path and give me the complete call chain from entry point to database write (or output), with file names.
3) Build and test: how do I install dependencies locally, get it running, and run tests and lint? List the commands one by one.
4) Conventions and pitfalls: which coding conventions and naming habits here differ from the defaults? Put together a glossary of project-specific terms, and point out the traps newcomers tend to fall into.
5) What's changed recently: read the last 30 git log entries and the active branches, and summarize what the team is working on and which files change most often.
Use subagents when exploring large directories — don't pull whole file contents into the main context.
Finally, compress the conclusions from 1–4 into a bullet list; I'll use it to flesh out CLAUDE.md.

Once you've finished the questions, run /init to generate CLAUDE.md, then have Claude merge the bullet list above into it.

Sources & last verified