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