← All prompts

Explain This Codebase to a New Contributor

A grounded tour of an unfamiliar repo, with file paths on every claim so you can check the work.

The prompt

Give me the orientation I would want on my first day in this repository.

WORK FROM THE REPO, NOT FROM PATTERN RECOGNITION
Read the files. Every claim below must cite a real path, and a line number
where one applies. If you cannot find evidence for something, say that it is
unclear rather than filling the gap with what a project like this usually does.

COVER
1. What this thing is and who uses it, in three sentences.
2. The entry points. Where does execution actually begin, for each way the
   project can be run.
3. The five files that carry the most weight, and why each one matters.
4. How data moves through a single representative request or command, start to
   finish, naming the files it passes through in order.
5. The conventions a newcomer would violate without knowing: naming, layout,
   error handling, testing style. Cite an example of each.
6. Where the sharp edges are. Code that is load-bearing and fragile, anything
   with a comment explaining why it must not be touched, anything the tests do
   not cover.

THEN
List the three questions you would ask the maintainer, ranked by how much the
answer would change how a newcomer works.

RULES
Be concrete. "Well structured" and "clean separation of concerns" are not
observations. If the architecture is inconsistent, describe the inconsistency
and where it starts.

The “work from the repo, not from pattern recognition” block is the whole prompt. Ask for a codebase tour without it and you get a description of a generic project of that shape, which is confidently wrong in the exact places that would have been useful.

Point six is the one worth reading twice. Fragile load-bearing code is what a newcomer breaks first, and it is almost never in the README.

Comments