The Agentic Loop

You type a sentence and press Enter. Some time later a change exists in your project. This lesson is about the middle part, because knowing its shape changes how you write the sentence.

Three phases

When you give Claude a task, it works through three phases: gather context, take action, and verify results.

1. Step 1

   Gather context

   Find out what is actually true. Search the project, read the files that look relevant, run a command to see current behaviour, look something up on the web.

2. Step 2

   Take action

   Change something. Edit a file, create one, run a build, run a migration, make a commit.

3. Step 3

   Verify results

   Establish whether the change worked. Run the tests, run the type checker, re-run the command that was failing, read the output.

The phases blend. Claude uses tools throughout, and a single turn can move between them repeatedly: read a file, edit it, run the tests, read the failure, read a different file, edit again, re-run. There is no moment where one phase ends and the next begins.

The loop adapts to the task

This is the part worth internalising, because it explains why sessions feel so different from one another.

A question about your codebase might need only the first phase. Claude searches, reads, answers, and nothing is changed at all. A bug fix cycles through all three, repeatedly, until something passes. A refactor might involve a small amount of editing and a lot of verification, because the risk is not in writing the change but in establishing that behaviour did not shift.

Claude decides what each step requires based on what it learned from the previous step, chaining actions together and correcting course along the way. A single instruction can become dozens of actions.

Watching it happen

Here is "the tests are failing" run to completion. The interesting thing is not the fix; it is how much of this is the loop deciding what to do next.

claude

1. >You typed: npm test is failing on main. Can you find out why and fix it?

2. Claude ran: Run: npm test

3. Output: FAIL  src/pricing.test.ts
     applyDiscount › caps at 50%
     expected 50, received 65

4. WhyPhase one, and note what it did not do: it did not ask you which test was failing. Running the command was cheaper than asking, and the output is better than your description of it would have been.

5. Claude ran: Read src/pricing.test.ts

6. Claude ran: Read src/pricing.ts

7. Claude replied: applyDiscount clamps the discount before applying the stacking bonus, so a stacked discount can exceed the cap. The clamp needs to move after the bonus is added.

8. WhyStill phase one. It read the test to learn the intended behaviour, then the source to learn the actual behaviour. The diagnosis came from the gap between them.

9. Claude ran: Edit src/pricing.ts

10. Claude ran: Run: npm test

11. Output: FAIL  src/pricing.test.ts
      applyDiscount › applies stacking bonus
      expected 35, received 30

12. WhyThe first test passes now and a different one broke. This is the loop earning its keep: without verification the session would have ended one step ago, looking successful.

13. Claude ran: Edit src/pricing.ts

14. Claude ran: Run: npm test

15. Output: PASS  src/pricing.test.ts  (9 tests)

16. Claude replied: Both cases pass. The clamp now runs last, and the stacking bonus is applied to the pre-clamp total rather than the clamped one.

Count the decisions Claude made that you did not make: which command to run, which two files to read, what the discrepancy meant, what to change, and — after the second failure — that the first fix was incomplete rather than wrong.

Now notice what made all of that possible. The project had tests. Every phase three in that transcript was npm test. Without it, the loop would have had nothing to verify against, and the session would have ended after the first edit with a confident summary and an unproven change. This comes up again and again in this course.

You are inside the loop

You are not waiting outside it while it runs. You can redirect at any point, and there are two ways to do it that behave differently.

Press Esc to stop Claude immediately. The running tool call is cancelled and Claude waits for your next instruction. Work already done is kept, so this is not a reset — it is an interruption. Use it when the action in progress is itself wrong: it is reading the wrong module, or about to edit something you did not mean.

Type a correction and press Enter without stopping anything. The running tool finishes, then your message lands before Claude decides its next step. Use this when the direction needs a nudge rather than a halt — "actually keep the existing function signature", or "check the integration tests too".

Both are better than watching a session go wrong out of politeness. Interrupting early is cheap. Letting a wrong direction run for four more minutes is not.

What is doing the work

The loop is powered by two things: a model that reasons, and tools that act.

The model reads code, works out how components connect, and decides what needs to change. Several models are available with different trade-offs — Sonnet handles most coding work well, Opus offers stronger reasoning for harder architectural problems — and you can switch with /model during a session or choose one at launch. Whenever documentation says "Claude decides", it is the model doing the reasoning.

Everything around the model is the agentic harness: the tools it can call, the management of what fits in its context, and the environment where commands actually run. Claude Code is that harness. The same model with no harness is a chat window.

That split is useful when something disappoints you. If Claude misunderstood what you wanted, that is a model-and-prompt problem, and a clearer prompt is the fix. If it never found the relevant file, or ran out of room, or was blocked from running the command it needed, that is a harness problem, and the fix is configuration. Later lessons are largely about the second category, because it is the one you have direct control over.

Why the shape matters for how you prompt

Two practical consequences fall straight out of the loop.

First, give it something to gather. Claude cannot read the conversation you had in a meeting or the constraint that is obvious to you. Naming the relevant directory, pasting the error, or pointing at an existing example that does the thing correctly all shorten phase one and improve everything after it.

Second, give it something to verify against. A test command, an expected output, a screenshot of the intended design. Without one, the loop has no phase three and stops when the code looks done, which is the weakest possible stopping condition.

Neither of these is about writing longer prompts. It is about noticing that the loop needs inputs at two points, not one.

What to take away

Claude works through three blended phases — gathering context, taking action and verifying results — and chooses what to do next based on what the last step returned. The mix changes with the task: a question is nearly all context, a bug fix cycles through all three until something passes. The model reasons and the harness around it provides the tools, the context management and the place commands run. You sit inside the loop rather than outside it: Esc stops the current action, and a typed message lands after it without stopping anything. Prompting well mostly means feeding the loop at its two entry points — what it should gather, and what it should check against.

Next: the tools themselves — the five categories of thing Claude can actually do, and why that list is the whole difference between an agent and a chat window.