Learning a new codebase

I'm new to this codebase and need to understand it well enough to
{{goal}}. Here's the file/directory structure (or a description of it):

{{file_tree_or_description}}

Help me build a mental map:
1. Guess the overall architecture from the structure alone (what kind of
   app is this, what are the major layers/boundaries) and flag anything
   you're inferring versus confident about.
2. Identify the 3-5 files or directories most worth reading first to
   understand the core of the system - not every file, the ones that
   would teach me the most per minute spent.
3. For each one, say specifically what to look for when I open it (the
   main abstraction it defines, the pattern it sets that other files
   likely follow).
4. Suggest one small, safe change I could make (a comment, a tiny bug fix,
   a test) that would force me to actually trace a real path through the
   code, as a way of validating my understanding rather than just reading
   passively.

Be explicit about what you can't tell from structure alone and would need
the actual file contents to confirm.

When to use

The first day or two on a new codebase (new job, new open-source project, new inherited project at work), before you’ve read enough of it to know what to read next. Paste in actual file contents for the files it flags as a natural next step once you have this map.

Why it works

The hardest part of onboarding onto a codebase isn’t understanding any one file - it’s knowing which files are worth understanding first. A model reasoning from directory structure and naming conventions alone can make a reasonable guess at architecture and prioritize reading order, faster than opening files in whatever order they happen to appear. The “make one small change” step matters because reading without touching anything rarely produces real understanding - tracing an actual code path does.

Variations

• Once you have the map, paste in the actual contents of the top-priority file and ask “explain this file’s role in the architecture you guessed at” to validate or correct the initial guess.
• Add “I have 2 hours” or “I have 2 days” to calibrate how deep versus how broad the suggested reading order should be.
• For a codebase with tests, ask “which test file would teach me the most about expected behavior, and why” as an alternative entry point to reading source directly.