At makandra you will constantly work in applications you didn't write: customer projects, legacy apps, gems. A coding agent can read a code base much faster than you and explain it to you. This lesson teaches you to ask the right questions, and to check the answers, because an agent's explanation is a hypothesis, not a fact.
Important
Work on this lesson in
teachermode.
Learning goals
- You can ask an agent about an unknown code base in a way that gets useful answers: an overview first, then narrower questions.
- You can trace a request through a Rails app with the agent's help, from the route to the response.
- You can find where something is implemented, and learn a project's conventions and vocabulary.
- You can explain why an agent sometimes describes code that isn't there, and verify its claims against the actual code.
- You can keep an exploration session useful by scoping your questions so the context doesn't fill up with irrelevant files.
Learn
Prompts that work
Start broad, then narrow down. Good first questions for an unfamiliar app:
- "Give me an overview of this code base. What does the app do, and how is the code organized?"
- "Which are the central models, and how do they relate?"
- "Explain the conventions used in this project that differ from a default Rails app."
- "Give me a glossary of project-specific terms."
Then dig into specifics:
- "Find the code that handles X." / "Where is authorization for editing a movie enforced?"
- "Trace what happens when a user submits the form on /movies/new, from the route to the database."
- "Why does this controller call
fooinstead ofbar?" / "What edge cases does this class handle?" - "Look at the git history of this file and summarize how it came to look like this."
Use the project's own vocabulary in your questions. Reference files directly with @path/to/file instead of describing where they are.
Read the section Understand new codebases Show archive.org snapshot in the Claude Code docs, and Ask codebase questions Show archive.org snapshot from the best practices.
Verify what you are told
An agent reads code and summarizes it. Usually the summary is right. Sometimes it fills gaps with what a typical Rails app would do, and states it with the same confidence. You cannot tell the difference from the wording — only from the code.
So make verification a habit:
- When the agent names a file or method, open it. Is it there? Does it do what was described?
- When the agent describes a flow, follow it yourself once, step by step.
- Ask "how do you know?" and "show me the code for that." A good answer points to specific lines.
- Be suspicious of answers to questions that contain a false premise. Agents tend to go along with the premise.
The point is not distrust for its own sake. You are building the skill to judge agent output — the same skill you need later when agents write code for you.
Keep the session focused
Exploring fills the agent's context with file contents. Ask scoped questions instead of "look at everything". Run /clear when you switch to an unrelated topic. For a large question ("how does the whole permission system work?"), ask the agent to delegate to a subagent, so only the summary lands in your conversation.
Resources
Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.
Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.
- 📄 Claude Code: Understand new codebases Show archive.org snapshot — prompt recipes for an overview, finding code and tracing a flow
- 📄 Claude Code: Ask codebase questions Show archive.org snapshot — the questions you'd ask a senior engineer, and the "use subagents for investigation" pattern for large questions
- 📄 How Claude Code works Show archive.org snapshot — the agentic loop and the context window, so you understand why scoping questions matters
Exercises
Pick one of the sample apps from the card Sample apps. Work in a fresh agent session inside that app's directory.
1. Overview
Ask the agent for an overview of the application and its central models. Then write a ten-line summary in your own words, without looking at the agent's answer.
Pick three concrete claims from the agent's overview (e.g. "authentication is handled by Clearance", "movies belong to a user"). Verify each one by opening the code. Note what was accurate and what wasn't.
2. Trace a request
Pick a form in the app. Ask the agent to trace what happens when the form is submitted, from the route to the database and back to the rendered response.
Then follow the trace yourself in the code, file by file. Where did the agent skip a step, or describe one inaccurately?
3. Find where things happen
Ask three "where is X implemented?" questions about features you found while clicking through the app, such as "where is it decided whether the current user may delete this record?". For each answer, open the file and confirm it.
4. The false premise
Ask the agent a question that assumes something that isn't true about the app, for example "where is the Redis cache configured?" in an app that doesn't use Redis, or "how does the import from the external API work?" when there is none.
Did the agent correct you, or did it play along? Discuss with your mentor what this means for how you phrase questions.
5. Onboarding notes
Ask the agent for the project's conventions and a glossary of its terms. Compare with what you saw during exercises 1–4 and write a short onboarding note for the app (half a page): what it does, how it's structured, three things a new developer should know. Discuss the note with your mentor.
