AI Guides › Step-by-step guides
By Nigel Guy · 6 min read
Most people meet an AI agent in one of two ways. Either they treat it as a black box and hand over a vague job, then feel uneasy when it works for ten minutes without them. Or they treat it as a chatbot, paste in a task, and wait for a single answer. Both miss what is actually happening: a small cycle that repeats, in plain view, with a stop button under your thumb.
The rule: an agent is a loop of gather context, take action, check the result. You steer it by controlling what it can reach, what counts as "done", and when you step in.
The examples here use Claude Code, because Anthropic documents its loop in detail. The same shape applies to other agents, but the commands and menus below are Claude Code's.
Anthropic's documentation describes three phases: gather context, take action, verify results. They blend together rather than running in strict order. Underneath, there are two parts: a model that reasons, and tools that act. Tools fall into groups: file operations, search, execution (shell commands), web, and code intelligence. Every tool result feeds back in and shapes the next decision.
In the Agent SDK documentation, one trip round the cycle is called a turn. Claude asks for tools, the tools run, results come back. The loop ends when Claude replies with no tool calls. A quick question may take one or two turns. A refactor can take dozens.
So "fix the failing tests" might go: run the tests, read the errors, search for the files, read them, edit, run the tests again. You can read every step on screen. That visibility is the whole point.
claude.Shift+Tab to cycle permission modes. The documented modes are Auto (a classifier model reviews most actions and blocks risky ones), Manual (asks before file edits and shell commands), Accept edits, and Plan (explores and proposes without editing your source files).Type a read-only request:
Explain how this project is laid out and where the tests live.
Watch the loop run with only the gather phase. Notice which files it opens and which searches it runs. You have just seen the cycle with the action phase switched off.
For anything that touches more than one file, separate thinking from doing.
Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan.You are helping me change a small project safely. Goal: [WHAT_I_WANT_CHANGED].
Constraints: [THINGS_NOT_TO_TOUCH]. Done means: [CHECK_THAT_MUST_PASS, e.g. "npm test passes"].
First, read the relevant files and list what you found. Then propose a numbered plan
naming each file you would change and why. Do not edit anything yet.
If any of the goal, constraints or check is unclear, ask me before planning.
Before you answer, confirm every file named in your plan actually exists.
Fill in the goal, the off-limits files and the check. Press Ctrl+G to open the plan in your editor if you want to edit it directly. Approve it, or press Shift+Tab to leave plan mode, and the action phase begins.
Anthropic's best-practice guidance is blunt: Claude stops when the work looks done, and without a check it can run, "looks done" is the only signal. A test suite, a build exit code, a linter or a screenshot comparison closes the loop. Ask for the evidence as well:
Make the change from the plan. Then run [CHECK_COMMAND] and show me the command and its output.
If it fails, fix the cause rather than silencing the error, and run it again.
Stop and ask me if you have tried the same fix twice without progress.
Fill in the command that proves success. Reading shown output is faster than re-running it yourself.
You do not have to wait for the end. The documented controls:
Esc stops Claude immediately. The running tool call is cancelled and your context stays.Enter while it works. It is queued and read as soon as the current tool calls finish.Esc twice, or /rewind, opens the rewind menu to restore earlier conversation and code state./clear resets context between unrelated tasks.If you have corrected the same issue more than twice, the documentation advises running /clear and starting again with a sharper prompt, since failed attempts clutter the context.
If you build on the Agent SDK, the loop has explicit limits: max_turns (maxTurns in TypeScript) counts tool-use turns, and max_budget_usd (maxBudgetUsd) caps spend. Without limits the loop runs until Claude finishes, which is risky on open-ended prompts. A capped run ends with a result subtype of error_max_turns or error_max_budget_usd, and you can resume the session.
Esc and it recovered without starting over.git diff shows only changes you expected.