Developers blame 'Claude' for unexpected file reads or commands when those are actually intended loop behavior they didn't predict. Understanding the loop is the first step to trusting — and controlling — what Claude Code does.
Each loop iteration is one API call. Claude receives the conversation history (including all previous tool results), reasons about what to do next, and either calls a tool or stops. Tool results — file contents, command output, search results — are appended to the context window and passed back to Claude, which is why reading the wrong file can cascade into wrong assumptions across the rest of the session.
# Example: Claude working on 'add rate limiting to the API' # Turn 1 — Claude calls Read on the main router file # tool: Read file: src/routes/index.ts # → returns 140 lines of route definitions # Turn 2 — Claude calls Read on the middleware directory # tool: Read file: src/middleware/auth.ts # → returns existing auth middleware pattern # Turn 3 — Claude calls Edit to insert rate limiting middleware # tool: Edit file: src/middleware/rateLimit.ts (new file) # → creates middleware matching the existing pattern # Turn 4 — Claude calls Edit to wire it into routes # tool: Edit file: src/routes/index.ts # → inserts import and app.use() call # Turn 5 — stop_reason: end_turn # Claude returns a summary of the changes made
Claude does NOT read your whole codebase automatically — it uses Read on specific files it chooses to open. If Claude reads the wrong file, its assumptions for every subsequent step will be wrong. Mention filenames explicitly in your prompt: 'in src/routes/index.ts, add...' directs Claude to the right starting point.
Given a tool call sequence and stop_reason value, predict what happens next. stop_reason: tool_use means the loop continues — Claude expects tool results back. stop_reason: end_turn means the session is complete. stop_reason: max_tokens with a partial tool_use block in the response means you must continue the conversation — do NOT retry from scratch, or the partial work is lost and costs double.
Open Claude Code, give it a concrete task like 'add a console.log to the fetchUser function in src/api/users.ts and run the test suite', then watch each tool call in the transcript. Trace the loop: which files did it read first, what did it edit, what did it run? Compare what you expected to what actually happened.