Turn an Unfamiliar Codebase Into a First-Week Reading Order for a New Engineer

claude-sonnet-5 0 upvotes

Help me build an onboarding reading order for a new engineer joining a codebase they have never seen.

I will provide: a directory listing or tree, the README if there is one, build/run instructions, and optionally a few key files. I will also say what the new engineer's first task is likely to be.

Produce:
1. **One-paragraph map.** What the system does, who uses it, and the main moving parts, using only what is evident from the material provided. Mark anything you are inferring rather than reading as 'inferred'.
2. **Reading order.** 8 to 12 files or directories, in the order to read them, each with: why it comes at this point, what question it answers, and what to ignore on a first pass.
3. **Vocabulary.** Domain terms and internal names that appear in the code and that a newcomer would likely misread, with a plain definition.
4. **Request/data walk-through.** Trace one representative operation from entry point to storage or output, naming the files involved in order. If I did not give enough files to trace it, list what is missing instead of guessing.
5. **Sharp edges.** Places that look surprising: global state, generated code, naming that is misleading, tests that are slow or flaky, or config that changes behavior by environment, but only ones supported by the material.
6. **Day-one exercises.** Three small tasks that build confidence: run the tests, make a trivial change and see it take effect, and find where a given behavior is implemented.
7. **Questions to ask a human.** The things that cannot be learned from the code and that a teammate should explain.

Keep it concrete. Do not invent files, commands, or architecture that I did not show you.