Talking to a codebase: ask, explore, change

The install worked. claude --version printed something sensible. You are staring at a prompt in a real project folder. Now the hard part: what do you type?

Most people skip straight to “rewrite auth” because that is the ticket on the board. The agent invents a helper that does not exist, edits six files, and leaves you with a diff you cannot defend in review. The fix is not a secret prompt template. The fix is a three-beat conversation: ask, explore, then change. Same order you would use with a sharp junior engineer on their first day in the monorepo.

This is Part 2 of the Claude Code tutorial. Part 1 covered install, login, surfaces, and first-run safety. If you still need the wider product map, use Claude product map. For everyday chat skills that transfer here (clear goals, iterative follow-ups), keep Learn Claude from scratch nearby.

What you’ll learn

Why “ask → explore → change” beats “fix everything in one breath”
First questions that map a repo without inviting premature edits
How to explore with paths, tests, and existing patterns as evidence
How to scope a first change so review stays human-sized
When to use plan mode versus default permissions mid-conversation
A worked loop you can run on any unfamiliar codebase this week
Smells that mean you should stop editing and go back to questions

Commands and UI labels are as of writing. Re-check quickstart, common workflows, and best practices when you codify team habits.

The three beats: ask, explore, change

Three-step loop for Claude Code: ask orientation questions, explore with file paths and tests, then make a small chan…

Think of Claude Code as a teammate who can read the tree faster than you and write faster than you. Speed is only useful if the shared map is right. The three beats keep the map honest.

Beat	Your job	Agent’s job	Done when
Ask	State role, goal, and constraints in plain language	Answer with structure and file paths	You can open the cited files and they match the story
Explore	Drill into one area; demand examples and tests	Search, read, summarize, maybe run read-only commands	You know where a change should live and what might break
Change	Name the smallest useful patch; review every diff	Edit under your permission mode; run checks if asked	You can explain the patch in one sentence and tests (or a manual check) hold

People collapse the beats because tickets are written as outcomes (“dark mode”) not as investigations (“where is theme state owned today?”). Claude will happily collapse with you. Your job is to refuse the collapse until the map is good enough.

Beat 1: ask questions that force a map

Starter questions for a new codebase: what does this project do, where is the entry point, how do tests run, where is…

Official quickstart starters are intentionally boring. That is a feature. On a cold repo, try variants of:

what does this project do?

where is the main entry point?

what technologies does this project use?

explain the folder structure

Then move from brochure language to operational language:

how do I run tests and start the app locally? quote the exact commands from the repo

where is user authentication enforced for HTTP requests? list file paths

which package owns billing, and which package only consumes it?

Notice the pattern. You are asking for paths, commands, and boundaries, not for vibes. “This is a modern scalable platform” is useless. “Entry is apps/web/src/main.tsx, API is services/api, auth middleware is services/api/src/middleware/auth.ts” is gold, but only after you open those files.

Questions that set role and risk

Claude does not know whether you are a new hire, a contractor, or the original author unless you say so. A short framing block at the start of a session saves thrash:

I am new to this repo. I can run basic git and tests.
I am not allowed to change production deploy config today.
Goal: understand how notes are created, then fix a small validation bug.
Prefer small diffs and existing patterns over new frameworks.

That is not ceremony. It cuts off “helpful” refactors into a new state library when you asked about required fields on a form.

What good answers look like

They name files you can open in under ten seconds.
They distinguish “I read this” from “I am guessing.” If the agent never shows uncertainty on a messy repo, be suspicious.
They match what package.json, pyproject.toml, or the README already say about scripts.
They stop when you say “enough map, next question,” instead of pitching a rewrite.

If answers stay abstract after two tries, change tactics: “Show the contents of the top-level directory and tell me what each top-level folder is for.” Agents get better when the question attaches to something concrete on disk.

Beat 2: explore like you mean it

Explore is still mostly reading. You may allow shell commands that list files, search, or run tests. You should still hesitate before write tools. Plan mode (cycle with Shift+Tab as of writing, or start with a plan-oriented prompt) is built for this phase: research and propose without editing source until you approve.

Follow the path, not the slogan

When Claude says auth lives in middleware, open the middleware. Skim imports. Ask the next question from what you see:

in services/api/src/middleware/auth.ts, where do tokens get verified?
is there a test that covers an expired token?

This is the human part people skip. If you only read the chat pane, you are doing code review of a book report.

Find the sibling feature

Almost every “new” feature has a cousin. Want a new webhook? Find the last webhook. Want a new admin filter? Find the last admin filter. Point Claude at it:

find an existing admin list filter and explain the pattern end to end:
route, query params, UI control, tests.
I want to add a filter for createdAfter using the same pattern.

Agents imitate visible structure. When the sibling is clear, the first change is boring in the best way. When no sibling exists, say that out loud: “This may be a new pattern. Stay minimal.”

Use tests as a map

If the repo has tests, ask where behavior is specified before you invent behavior:

which tests cover note creation?
run the smallest relevant test command after you identify it
do not change code yet

Read permission prompts for test commands. Running tests is usually lower risk than rewriting packages, but “run tests” should not silently become “upgrade the entire toolchain.” Deny command shapes you do not recognize.

Exploration prompts that stay in explore

Language matters. These keep the agent in research mode:

“Do not edit files yet.”
“List options with tradeoffs; recommend one; wait for my pick.”
“Quote the existing function names you would call.”
“What could break if we change X?”

If you are in default mode and Claude still proposes edits too early, answer with “plan only” or switch to plan mode. You are allowed to slow the tool down. That is leadership, not fear.

Beat 3: change small, then review

Only after the map is good enough do you invite writes. “Good enough” means you know the primary file(s), the pattern to copy, and a check you will run (test, script, or manual click path).

Write the change request like a ticket for a careful teammate

Weak:

fix validation

Stronger:

In the note creation API, reject empty titles with a 400 and a clear error body
matching existing error shape in this service.
Add or update a test next to the existing note creation tests.
Do not change database schema.
Do not refactor unrelated files.

Specificity is kindness. It also makes bad diffs obvious: if the patch touches schema or renames half the module, something went wrong relative to the ask.

Stay on default permissions for early changes

As of writing, default mode asks before many edits. Read each prompt. Check path and action. acceptEdits is fine later when you already trust the loop and will review with git diff. Plan mode is for pre-edit design. Cycling is usually Shift+Tab in the CLI; see permission modes for the live list including modes your account may enable beyond the basic cycle.

Review before commit (non-negotiable)

After edits land:

git status
git diff

Ask Claude to explain the diff if you want a guided tour, then distrust the tour until the hunks match. Look for:

Files you did not mention
New dependencies you did not approve
Deleted tests or weakened assertions
Formatting-only churn that hides a real logic change
“Helpful” renames that break public API surface

Commit only when you can defend the patch. If Claude drafts the commit message, rewrite anything you could not say out loud in standup. Later parts of this series go deeper on diff review and undoing bad runs. The habit starts now: no blind commits.

Worked example: empty title on notes API

Setup from Part 1 style: you are in ~/src/notes-api, default permission mode, tests available via npm test.

Ask

what does this project do?
where is the HTTP entry point?
how are notes created today?

Claude points at src/server.js, src/routes/notes.js, and src/db.js. You open notes.js. There is a POST /notes handler that inserts title and body with almost no checks.

Explore

do not edit yet
how does this service format 400 errors for other routes?
where are tests for POST /notes?
what command runs only those tests if possible?

You learn errors look like { "error": "message" } with status 400. Tests live in test/notes.test.js. Command is npm test -- test/notes.test.js. You allow the test run. Existing tests pass. None cover empty title.

Change

Add validation so POST /notes returns 400 with { "error": "title is required" }
when title is missing or only whitespace.
Add a test in test/notes.test.js next to the other POST tests.
Do not change the database schema or other routes.

Claude proposes a small guard and a test. You approve both file edits after reading the paths. You ask it to run the notes tests again. Green. You run git diff. Two files. No surprise lockfile. You commit: “fix: reject empty note titles with 400.”

That loop took longer than a single “fix validation” prompt. It also produced something you can merge without praying.

Prompt patterns that transfer

Pattern	Example stub	When
Map first	“Explain X with file paths; no edits.”	New area of the tree
Sibling clone	“Match the pattern in FILE; list steps; wait.”	Feature similar to an existing one
Blast radius	“What else imports this symbol?”	Before renames or signature changes
Test seatbelt	“Write a failing test first, show it, then implement.”	Behavior bugs with a clear expected result
Scope lock	“Touch only these paths: …”	Any time the agent gets ambitious
Rollback line	“If tests fail, stop and summarize; do not keep hacking.”	Long agent loops

You will invent your own stubs. Keep them short. Paste them at the top of a session when the repo is cold.

When to switch modes mid-conversation

Default / manual: learning, sensitive areas, first change in a session, anything near auth/payments/deploy.
Plan: multi-file feature you do not yet understand; you want a written approach before disk changes.
acceptEdits: tight loop on a well-understood patch set, with you watching git diff often.

If you enter acceptEdits and the agent starts roaming, hit the brakes: stop the run if needed, return to default or plan, restate scope. Modes are not a loyalty program. Switch when risk changes.

Smells that mean go back to ask/explore

The agent cannot name a file path for a claim it just made.
It introduces a library the repo does not use anywhere else.
The first proposed patch is larger than the ticket description.
Tests are “left for later” on a behavior change.
You feel lost reading the diff (that feeling is data).
It keeps re-explaining architecture instead of answering “where.”
Permission prompts show directories outside the project or destructive shell.

When you smell smoke, say it in the session: “Stop editing. Summarize current repo facts with paths only. We will replan.” Clearing context with /clear (as documented in session commands) can help when the conversation has accumulated wrong assumptions. A clean short ask beats a polluted long thread.

Talking to Code vs talking to chat

Chat (claude.ai style) is strong at explaining concepts, drafting designs, and reviewing pasted snippets. Claude Code is strong when the truth lives in a tree of files you should not paste by hand. The conversational skill still transfers from Learn Claude: clear goals, iterative questions, skepticism toward fluent nonsense. What changes is evidence. In Code, evidence is paths, diffs, and command output, not a confident paragraph alone.

If you catch yourself pasting whole files into web chat because “it feels safer,” notice the cost. You became the integration layer. Use Code for repo-grounded work; use chat for product thinking that is not yet tied to this tree. The product map series is the long form of that choice.

Team habits that make the loop stick

Even as a beginner you can set norms:

PR descriptions state what was explored, not only what was edited.
Screenshots of green tests (or CI links) beat “seems fine.”
Large agent diffs get a human walkthrough in review, not a rubber stamp.
Secrets and production data stay out of prompts.
Instruction files (CLAUDE.md and friends) get updated on purpose later, not as drive-by noise in a bugfix.

Later parts of this tutorial cover slash commands, skills, memory, instruction files, plugins, longer agent loops, and team rails. None of those replace ask → explore → change. They only accelerate it.

Common mistakes

Starting mid-sentence with the biggest refactor

If your first real prompt is “migrate us to the new framework,” you skipped school. Map, then migrate a leaf module, then expand.

Treating the first summary as ground truth

Summaries hallucinate structure on messy repos. Paths you open are ground truth. READMEs that disagree with code need a human decision, not more fluency.

Approving edits to “just see what happens”

Git helps, but not if you never look. Curiosity is fine in a throwaway branch with a reset plan. It is not fine on main at 4:55 p.m.

Forgetting to say what not to do

Constraints are part of the prompt: no schema changes, no dependency adds, no drive-by renames. Agents fill silence with ambition.

Confusing green tests with correct product

Suites lag. Click the user path. Check error copy. Ask whether analytics or flags are required in your shop before you call it done.

FAQ

How long should explore last before I allow edits?

Until you can name the primary files and a check. Sometimes that is five minutes. Sometimes it is an afternoon on a legacy service. The clock is not the point. The map is.

Should I use plan mode every time?

No. Use it when the change is multi-file, unfamiliar, or high risk. Tiny typo fixes in a file you already have open do not need a full planning ceremony.

What if the repo has no tests?

Keep changes smaller. Prefer feature flags if your team uses them. Write a minimal test if the project will accept one. Manual checklists become mandatory, not optional.

Can I skip ask/explore once I know the codebase?

You can compress them. You should not delete them. Even experts ask “where is this enforced now?” because code moves. Compression looks like two sharp questions and a sibling pointer, not zero questions and a hope.

How to practice this week

Open a sandbox or well-known sample app with Claude Code (Part 1 install).
Run a pure ask session: project purpose, entry point, how tests run. No edits.
Explore one subsystem with path-forcing questions. Open every file cited.
Make one small behavior or docs change with an explicit “do not touch” list.
Review git diff. Commit or discard on purpose.
Repeat once in plan mode for a slightly larger idea, approve or reject the plan before any write.

Quick recap

Ask for maps with paths and commands, not slogans.
Explore until you know where to change and what might break; plan mode helps.
Change with tight scope, review diffs, then commit only what you can defend.
Smells (no paths, surprise deps, huge diffs) mean return to questions.
Chat skills transfer; Code adds repo evidence. Stay oriented with the product map and Learn Claude.

Next: Part 3 covers slash commands and common command patterns so you spend less time rediscovering session tools mid-flow.

Sources

Research and further reading used for this article (re-check before you freeze team process):

Claude Code Docs: Quickstart (first questions, first change, git conversation examples, permission mode pointer)
Claude Code Docs: Common workflows (plan-before-edit and everyday task patterns)
Claude Code Docs: Best practices (prompting and project setup guidance)
Claude Code Docs: Choose a permission mode (default, acceptEdits, plan, cycling)
Claude Code Docs: How Claude Code works (agent loop and tools orientation)
Claude Code Docs: Interactive mode (session keyboard shortcuts)
Claude Code Docs: Overview (product surfaces and framing)
Analytics Made Simple: Claude product map (when Code vs chat vs Cowork)
Analytics Made Simple: Learn Claude from scratch (everyday conversation habits)