Claude Code's 11-Step Agent Loop: What It Teaches You About Your AGENTS.md

Engineers reverse-engineered Claude Code and published the internals on Hacker News last week. It hit the front page fast.

The 11-step internal loop isn't a surprise — it's validation. Claude Code runs through exactly the steps you'd design if you were building an agent from scratch: read input, plan, execute, check, adjust. The fact that Anthropic ships it this way tells you something important: this is what agent architecture looks like at production scale.

For OpenClaw builders, the implications are direct. If you're writing an AGENTS.md file, understanding Claude Code's loop teaches you what your own agent config should express. Scoped tools, explicit step gates, clear boundaries between planning and execution. These aren't conveniences — they're the differences between an agent that works reliably and one that drifts.

The 11-Step Loop Decoded

Based on the reverse-engineering work (and publicly available documentation), Claude Code's loop runs like this:

1. Receive task or user input — System receives your request
2. Plan the approach — Model thinks through the strategy
3. Select tools — Agent decides which of the 53 built-in tools to use
4. Execute tool calls — Tools run (code execution, file read/write, terminal, browser)
5. Collect output — Agent captures tool results
6. Analyze results — Model evaluates whether the output matches expectations
7. Check success conditions — Did we solve the problem?
8. If failed, adjust — Modify the approach or tool selection
9. Loop back to step 3 — Retry with new tool strategy or parameters
10. Report back to user — Communicate the final result
11. Log the session — Store session data for continuity

This sounds obvious written out. That's the point. The obviousness is the architecture.

What makes this loop work in production isn't any single step — it's the explicit gates between steps. The agent can't skip from planning to execution. It can't execute arbitrary code without first declaring which tool it's using. It can't loop infinitely because there's a step limit.

These are things you define in AGENTS.md.

What Claude Code's Architecture Reveals About Tool Design

Claude Code has 53 built-in tools. That's a lot. But here's what's important: each tool has an explicit scope.

The code execution tool only runs the code you approve. It doesn't read arbitrary files on the system. The file read tool only reads files in the project directory. The terminal tool only runs specific command patterns.

In other words, each tool is bounded. Tool boundaries are enforced by design, not by hoping the model behaves well.

When you write TOOLS.md for an OpenClaw agent, you're doing the same thing. You list exactly which tools the agent can call. You don't say "the agent can use tools." You say "the agent can read files in /data/ and write to /tmp/reports/. It can send emails to addresses in a whitelist. It cannot execute arbitrary shell commands."

This is tool design by explicit allowlist, not by hope. Claude Code's 53 tools teach you why this matters.

The Step Gates That Make It Reliable

Claude Code's loop has three critical gates:

Gate 1: Tool selection before execution. The agent doesn't just run code. It first declares which tool it's using and what the tool should do. This is the inverse of asking for permission — it's announcing the action. OpenClaw agents do this via AGENTS.md step configuration: what tools are available, what order they're called in, what conditions trigger each tool.

Gate 2: Success evaluation. After a tool executes, there's an explicit check: did this work? If not, modify the approach. This is where Claude Code differs from simpler agents that execute once and report. The loop expects iteration. For AGENTS.md, this translates to retry logic, retry budgets, and fallback strategies defined in your agent config.

Gate 3: Session limits. There's a maximum number of loops Claude Code will run before it stops and reports back to the user. It doesn't loop infinitely. In OpenClaw terms, this is your max_steps configuration in AGENTS.md — the agent gives up after N iterations and escalates to a human.

These three gates are what separate production agents from broken ones. An agent with tool boundaries but no success gates will execute tools and never know if anything worked. An agent with success gates but no step limit will loop until your API bill hits zero. An agent with all three gates works.

How This Maps to Your AGENTS.md Structure

Your AGENTS.md file is where you encode these patterns for your own agents.

Here's a minimal example of what this looks like:

## Agent Identity
Name: Data Validator
Purpose: Check daily reports for accuracy

## Tool Access
Tools:
  - read: /data/reports/
  - write: /tmp/validated/
  - execute: none
  - send_email: only to validation_admin@company.com

## Execution Pattern
Max Steps: 10
Retry Budget: 3
Success Condition: "Report passes all validation checks"
Escalation: "If validation fails, notify validation_admin@company.com"

## Session Boundaries
Timeout: 5 minutes
Max Concurrent Tasks: 1

This isn't prose. It's configuration that an OpenClaw runtime can actually enforce. The agent can't exceed max_steps. It can't write outside /tmp/validated/. It can't send email to anyone except the validation admin. The runtime sees these rules and stops the agent if it tries to violate them.

Claude Code's 11-step loop is executing exactly this kind of bounded execution model. The difference is that Claude Code encodes these rules in its internal architecture. OpenClaw agents encode them in files you write and control.

The Tool Allowlist Lesson

Claude Code has 53 tools. It doesn't have 500. The scoping was intentional.

Each tool solves a specific class of problem:

• Code execution for writing and running code
• File operations for reading and writing files in scoped directories
• Browser control for web scraping and interaction
• Terminal for running safe commands

Notice what's missing: Claude Code doesn't have direct database write access. It doesn't have the ability to send arbitrary HTTP requests to any server. It doesn't have shell access to your entire system. These are treated as security boundaries, not features to enable.

When you write your TOOLS.md for an OpenClaw agent, apply the same principle: use allowlists, not allowalls. Don't give your agent every possible tool and hope it uses them responsibly. Give your agent only the tools it needs to do its specific job.

An invoicing agent doesn't need browser access. A data validation agent doesn't need email capability. A report generator doesn't need exec permissions on your file system.

Specificity is security.

Reliability Through Explicit Boundaries

The real insight from Claude Code's loop is that reliability comes from constraints, not from smart prompting.

You could write a clever prompt that tells an agent "be careful with tools, don't loop forever, and escalate when unsure." Some models might follow that advice. Most won't consistently. The agent will drift over time, especially as context grows and the model's focus narrows.

Claude Code doesn't rely on prompts. It relies on architecture: step limits, tool gates, success checks. The agent can't violate these even if it wanted to.

When you design your AGENTS.md, you're building the same kind of enforcement. The agent won't loop beyond max_steps. It won't call tools outside the allowlist. It won't escalate incorrectly if the escalation condition is a clear rule, not a suggestion.

This is why OpenClaw agents with well-structured workspace files outperform agents with clever prompts and no config guardrails. The file-based architecture makes the rules explicit and enforceable.

Why This Matters for Your Next Agent

If you're building a multi-agent system or an agent that touches production data, Claude Code's loop teaches you what to audit before you deploy:

1. Are tools scoped? Each agent's tool access should be specific, not broad.
2. Are there step limits? The agent can't loop indefinitely.
3. Is there a success gate? The agent knows when to stop trying.
4. Is escalation explicit? When does the agent hand off to a human?
5. Are tool boundaries enforced by the runtime? Config files alone aren't enough if the runtime doesn't check them.

OpenClaw's sandbox and task configuration handle most of these. But you have to configure them — you have to write the AGENTS.md file that declares the boundaries.

The fastest way to get these patterns pre-configured and tested is through a workspace bundle. The wizard asks you about your agent's scope, then generates an AGENTS.md that encodes the Claude Code lessons: bounded tools, step limits, success gates, and escalation rules.