Discovery — Claude Code Guide · Claude Code Guide

Discovery starts with a map, not with editing

In an unfamiliar repository, the first goal is not to immediately find a place to edit, but to build a verifiable starting map. It should show the stack, top-level structure, commands for running and testing, main modules, entry points, and unknown areas.

Discovery is best conducted in a separate read-only session. If you explore the architecture and change code at the same time, new edits can easily be mistaken for part of the initial state.

Question	First sources
What is the stack?	`package.json`, `build.gradle`, lockfiles
How do you run the project?	`README.md`, scripts, wrapper files, compose config
Where are the tests?	Test directories and test scripts
Where are the entry points?	Startup classes, routes, root components, CLI commands, or jobs
What is still unknown?	A separate list of open questions with confidence levels

A safe initial review

Make sure the correct repository is open.
Check the current branch and uncommitted changes.
Read descriptive files and the list of commands.
Inspect top-level directories without reading all the code sequentially.
Find startup files, routes, and tests.
Record confirmed facts separately from items that need verification.

Context before discovery

pwd
git status
ls

# Adapt the commands to the project stack.
cat README.md

A discovery prompt for Claude

Read-only discovery prompt

Explore this repository without editing files.
Create a short map: stack, top-level directories,
commands for running and testing, main modules,
entry points, and unconfirmed questions.
For each important conclusion, cite an evidence file or command.

What is not a discovery result

complete knowledge of every class and method;
refactoring the problems found;
a long list of files without explaining their role;
assumptions presented as architectural facts;
a conclusion based only on directory names.

Output artifact

The result of initial discovery should be saved in `CODEBASE_INVENTORY.md` or another agreed inventory file. This map survives the current session and gives the next investigator a reliable starting point.