How Claude Code Executes the Read-Edit-Run-Test Loop
Claude Code is not an autocomplete engine that guesses at a file and stops.
It is an agent that works the way an engineer works: look at the code, change the code, run something to check the change, then look again.
That cycle, read, edit, run, verify, is the mechanical core of almost everything Claude Code does, from a one-line typo fix to a multi-file refactor.
Understanding the loop matters because it explains what you are actually watching happen in your terminal, and why Claude Code behaves so differently from a single-shot code generator.
Summary
- Core Idea: Claude Code repeats a read, edit, run, verify cycle, using each command's real output to decide its next step, until the task is done or it is blocked.
- Why It Matters: A single-shot generator can only guess; a loop that reads real output can catch its own mistakes before they reach you.
- Key Concepts: the read step (loading current file state), the edit step (proposing a change), the run step (executing a command), the verify step (interpreting the result), and iteration (repeating the cycle until done).
- When to Use: This is the default behavior for any non-trivial Claude Code task; there is no separate mode to turn it on.
- Limitations / Trade-offs: The loop is only as good as the commands available to run; without tests or a build step, verification is weaker and mistakes are more likely to slip through.
- Related Topics: file re-reads before edits, codebase search, multi-file edits, automated test iteration, permission prompts.
Foundations
The loop has four steps, and it is worth naming each one precisely.
Read means Claude Code opens the relevant file or files and looks at their current, actual contents, not a memory of what they probably contain.
Edit means it proposes a specific change: a new function, a modified line, a renamed variable, expressed as a concrete diff against what it just read.
Run means it executes a command, a test suite, a linter, a build, a one-off script, and captures the real output: exit code, stdout, stderr.
Verify means it reads that output and decides what it means: did the test pass, did the build fail, did the linter flag something new.
The loop is not read-edit-done.
It is read-edit-run-verify, and then, if verification says the job isn't finished, back to read (or straight to another edit) and around again.
A simple way to picture one pass through the loop:
READ file(s)
|
v
EDIT (propose a diff)
|
v
RUN a command (test / build / lint)
|
v
VERIFY the output
|
+--- task done? --> stop
|
+--- not done? --> back to READ or EDIT
This is the same rhythm a careful developer already uses by hand: open the file, make the change, run the tests, check the result, fix what broke, run again.
Claude Code just runs that rhythm explicitly and can repeat it many times without a human re-typing each command.
Mechanics & Interactions
The read step is deliberately grounded in the file's actual current content rather than an assumption.
If Claude Code already looked at a file earlier in the conversation, it does not necessarily treat that earlier read as still valid by the time it is ready to edit; a stale copy is a common source of failed patches, so a fresh read right before editing is part of how the loop stays reliable (a separate article in this section, linked below, covers exactly why that re-read happens).
The edit step produces a concrete, applyable change rather than a vague description of one.
That matters for the run step: a change that does not actually apply, or that introduces a syntax error, will surface immediately once a command tries to use the file, which is exactly the kind of signal the loop is built to catch early rather than let a person discover later.
The run step is where the loop connects to the real state of your project.
npm test
npm run build
npm run lint
pytest
go test ./...Any of these, or a project-specific equivalent, can serve as the "run" step.
The specific command matters less than the fact that its output is real: a failing test prints an actual assertion error, a broken build prints an actual compiler message, and Claude Code reads that literal text rather than assuming success.
The verify step is where the loop earns its name.
Verification is not Claude Code declaring "this should work now"; it is Claude Code reading the actual exit status and output of the command it just ran and deciding, based on that evidence, whether to stop, keep going, or change approach.
A test failure at this step is not a dead end, it is information: which assertion failed, what value was expected, what value was produced, and that information feeds directly into the next edit.
Permission prompts sit inside this loop at the run step specifically, because running a command is the action most likely to need approval depending on your permission mode; file reads and, in many configurations, file edits can be auto-approved, while a bash command may pause for a yes/no depending on the settings covered in this site's Claude Code 101 section.
Advanced Considerations & Applications
The loop scales from a single file to a whole codebase without changing shape.
For a one-line fix, the cycle might run once: read the file, make the edit, run the linter, see it pass, stop.
For a larger task, "add a new field and thread it through the API, the database layer, and the frontend form", the same four steps repeat across several files and several passes, with each verify step narrowing down what still needs work.
| Task size | Typical loop shape | What "verify" usually checks |
|---|---|---|
| One-line fix | Single pass: read, edit, run, verify | Linter or type-check passes |
| Bug fix with a reproduction | A few passes: read, edit, run test, verify, repeat | The specific failing test now passes |
| Multi-file feature | Many passes across files: read, edit set, run suite, verify, repeat | Full test suite, build, and any affected call sites |
A second consideration is that the loop is only as strong as what it can run.
If a project has no tests and no build step, Claude Code can still read and edit code, but the verify step has much less real evidence to work from, which is why projects with a fast, reliable test suite tend to get noticeably more accurate iteration than projects without one.
A third consideration is that the loop does not require a human to sit and watch every step.
Once a task is underway and the permission mode allows it, Claude Code can move through several read-edit-run-verify passes in a single turn, only surfacing back to you when the task is complete, blocked on a decision only you can make, or when a command needs explicit approval.
Common Misconceptions
- "Claude Code writes code once and you're done." The loop's whole value is in the run and verify steps; a change that has not been checked against a real command is treated as unfinished, not final.
- "The loop always runs the full test suite." The run step uses whatever command is appropriate to the change, a single test file, a linter, a type-checker, a full build, not necessarily the entire suite every time.
- "Verification means Claude Code trusts its own judgment about correctness." Verification means reading the literal output of a command that actually executed; that is a stronger signal than self-assessment.
- "If a test fails, the loop stops and reports failure." A failing test is usually treated as input to the next edit, not as an endpoint; the loop keeps iterating within the same turn when it is able to.
- "Re-reading a file mid-loop is wasted effort." It is a safeguard against editing a stale copy of a file that may have changed since it was last read, covered in detail in a companion article.
FAQs
What are the four steps of Claude Code's core loop, in order?
Read the relevant file, propose an edit, run a command against the result, and verify what that command's output means.
If verification shows the task isn't done, the cycle repeats from read or edit.
Does Claude Code always run tests as part of this loop?
It runs whatever command fits the situation, which can be a test suite, a linter, a type-checker, or a build.
Tests are the most common and strongest form of verification when a project has them, but they are not the only command the run step can use.
What happens if the run step fails, for example a test fails or a build breaks?
Claude Code reads the actual failure output and treats it as information for the next pass: which assertion failed, what error the compiler reported, or what the linter flagged.
That usually feeds directly into another edit rather than ending the task.
Can this loop run without a human approving every step?
Within a single turn, yes, depending on your permission mode; Claude Code can move through several read-edit-run-verify passes before surfacing back to you.
Commands that need explicit approval under your current permission settings will still pause for that approval.
Why does the loop matter more than the fact that Claude Code can "write code"?
Because writing code without checking it against real output is guesswork, and the loop is specifically designed to replace guesswork with evidence: an actual test result, an actual build error, an actual lint warning.
That is what separates an agent workflow from a single-shot code generator.
Does the loop only apply to bug fixes, or also to new features?
Both. A new feature typically runs through more passes of the loop than a one-line bug fix, since it usually touches more files, but the shape of the cycle, read, edit, run, verify, is the same either way.
What if my project has no tests to run?
Claude Code can still read, edit, and run whatever commands are available, such as a build or a type-check, but with fewer or weaker checks, the verify step has less real evidence to work from, so mistakes are more likely to slip through unnoticed.
Is "verify" just Claude Code saying the code looks correct?
No, verify specifically means interpreting the literal output of a command that was actually executed, an exit code, an error message, a passing or failing assertion, not an unchecked opinion about the code.
Where do permission prompts fit into this loop?
They sit at the run step, since running a command is the action most likely to need your approval depending on your permission mode.
Reading files and, in many setups, editing them can be auto-approved, while running a bash command may pause for confirmation.
Does the loop stop as soon as one file's edit is applied?
No, the loop is oriented around the task being done, not around a single file being touched.
For multi-file work it repeats across files and passes until verification shows the whole task, not just one edit, is complete.
How is this different from asking an LLM to "write me a function" in a chat window?
A chat window typically returns text once, with no mechanism to check that text against a real file, a real command, or a real test result.
Claude Code's loop closes that gap by actually running commands and reading their real output before deciding the task is finished.
Related
- Core Claude Code Workflows Basics - practice the loop hands-on with a small task
- Why Claude Code Re-Reads Files Before Editing Them - the safeguard inside the read step
- Running Tests and Iterating on Failures Automatically - a deeper look at the verify step in action
- How Claude Code Decides When to Run a Command vs Ask Permission - what governs the run step's approval behavior
- Permission Modes Explained: Auto-Accept vs Ask-Every-Time - the settings that shape approval across the whole loop
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.