You've just been handed a codebase you've never seen before. No walkthrough, sparse docs, and the person who built it has moved on. You need to ship something in it by end of week. This is one of the most common — and most draining — situations in engineering, and AI actually handles it well if you know how to prompt it. Here's a step-by-step walkthrough you can follow right now.
Step 1: Get a High-Level Map Before You Touch Any File
Don't start by opening random files. Start by asking AI to orient you from the top down.
Paste in the root directory tree (just the folder/file names — no code yet) and use this prompt:
I'm trying to understand a codebase I've never worked in before.
Here is the top-level directory structure:
[PASTE DIRECTORY TREE HERE]
Based on this structure:
1. What is the likely purpose of this application?
2. What architectural pattern does it appear to follow (e.g. MVC, layered, event-driven)?
3. Which directories should I read first to understand the core domain logic?
4. What questions should I be asking that this structure alone can't answer?
This gives you a mental scaffolding before you wade into implementation details. The fourth question is the most valuable — it surfaces what to look for next.
Step 2: Explain a Specific File Without Reading Every Line
Once you have a target file, paste it into the chat and ask for a structured breakdown rather than a summary. Summaries tend to be vague. A structured breakdown forces the model to be specific.
Here is a file from a codebase I'm ramping up on:
[PASTE FILE CONTENTS]
Please explain it with the following structure:
- **Purpose**: What is the single responsibility of this module?
- **Inputs / Outputs**: What does it receive and what does it produce or affect?
- **Dependencies**: What does it rely on that I should also understand?
- **Side effects**: Does it write to anything, emit events, or mutate shared state?
- **Gotchas**: Any non-obvious logic, edge cases, or things that could confuse a new reader?
The "Gotchas" section alone has saved me from misreading code more times than I can count. Models are good at spotting patterns that are technically valid but semantically surprising — things like a function named getUser that also writes a log entry.
Step 3: Trace a Request or Data Flow End-to-End
Understanding individual files isn't enough — you need to know how they connect. Pick an entry point (an API route, a queue consumer, a CLI command) and ask AI to walk the execution path with you.
Paste in 2–3 files that you suspect are in the same call chain and prompt:
I'm trying to understand how a request flows through this system.
Here are several files I believe are connected:
[FILE 1 — paste contents]
[FILE 2 — paste contents]
[FILE 3 — paste contents]
Please trace what happens when [describe the trigger, e.g. "a POST request hits /api/orders"].
Show the sequence of function calls across these files,
note where data is transformed, and flag any steps where the flow is unclear or could break.
This is where AI pays for itself in ramp-up scenarios. Manually tracing a call chain across 4–5 files used to take a full afternoon. With the right prompt, you have a working model in 10 minutes that you can then verify.
Step 4: Generate a "New Contributor Cheat Sheet"
Once you've used steps 1–3 to develop a mental model, consolidate it. Have the AI produce a reference doc you can keep open while you work.
This pattern is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version below is enough to get value on its own.
Based on everything we've discussed about this codebase, generate a "New Contributor Cheat Sheet" with:
1. One-paragraph system overview
2. Key modules and their responsibilities (bullet list)
3. The 3–5 files a new engineer must read before making any changes
4. Common pitfalls or conventions that aren't obvious from the code alone
5. Glossary of any domain-specific terms used in the codebase
Paste this into your team's internal docs or a personal note. The next time you hit a confusing area of the codebase, you have a foundation to ask more precise questions from.
What This Workflow Is Actually Doing
Each step moves from abstract to concrete: structure → file → flow → reference. You're using AI as a structured reading partner, not an autocomplete. The quality of what you get back scales directly with the specificity of your prompt — generic questions produce generic answers.
A few practical notes:
- Context window matters. For large files, trim dead code or test fixtures before pasting. Focus the model on the logic, not the noise.
- Always verify. AI will occasionally misread intent, especially in codebases with unconventional patterns. Use its output as a hypothesis to confirm, not a fact to accept.
- Iterate. The cheat sheet from Step 4 will have gaps. Go back, paste the confusing parts, and refine.
I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. It's built for engineers who want to work faster without cutting corners. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=long_w9
Top comments (0)