codebase-exploration

Understanding a repository you have not read

Two questions arrive dressed as one: where does this happen, and why is it like this. Answer the first from the layout and the code, the second from the commits — and never guess at either from a file name.

Sequence

1. Take the shape before the contents. get_repository_tree with recursive: true returns the whole layout in one call. On a large repository, set path_filter to a prefix and take the top level first; the directory names alone usually identify the entry points, the tests and the generated code.
2. Read the documents the project wrote about itself. get_file_contents on the README and any contributing guide. They state intent, which no amount of code reading recovers.
3. Establish where the current work is. list_branches shows what exists beside the default branch, and list_tags shows whether the project versions itself. If it does, the newest tag is a better reading point than the default branch, because it is a state someone chose to publish.
4. Find the behaviour, do not browse for it. search_code with repo:owner/name and a distinctive symbol goes straight there. Qualify with path: and language: to cut noise; quote a phrase for an exact match. Keep the query under 256 characters, and use fields to return only path and text_matches when you are locating rather than reading.
5. Read around every match. A search result is a line; get_file_contents gives it the context that decides whether it is the definition, a caller, or a test.
6. Ask why only once you know where. list_commits with path set to the file gives that file's history in change order. This is where the layout question ends and the history question begins — references/history-investigation.md covers the rest.
7. Report a route, not a conclusion. Name the files, the symbols and the commits you actually read, so the next person can start where you finished.