# How Claude Code Works

Jared Zoneraich, PromptLayer | AI Engineer CODE 2025 | 1:05:43

Source: https://www.youtube.com/watch?v=RFKCzGlAU6Q
Channel: AI Engineer (https://www.youtube.com/@aiDotEngineer). Summarised by AIE Talks.
Page: https://aietalks.com/talks/how-claude-code-works
Published: 2025-12-26
Tags: agents, coding-agents, context-engineering, guardrails, harness-engineering

## TL;DR
- Claude Code works because it combines a simple master loop with capable models and a small set of tools.
- Bash, sandboxing, context management, and prompt-based planning let the model explore and act without a large workflow graph.
- Coding agents need different designs for different tasks, and engineers should use rigorous tools and tests where they need predictable output.

## Summary
Jared Zoneraich explains Claude Code through architecture he and others have independently inferred, while stressing that Anthropic did not endorse the talk. His central claim is that the agent is simple: a master while loop repeatedly gives the model tool results until the model stops calling tools. Bash, file reading, diffs, grep, tasks, and to-do lists provide enough structure for the model to work through coding problems. Sandboxing and permissions contain the risks that come with shell and web access. Context management matters because long context makes the model perform worse, so sub-agents, summarization, compaction, and handoffs keep the main thread smaller. Zoneraich compares Claude Code with Codex, Amp, Cursor, Factory, Devin, and others. He argues that general-purpose agents should rely on models, while strict output requirements belong in tested tools or workflows. He expects headless agent SDKs to become part of ordinary software pipelines.

## Key ideas
### Claude Code became useful through simpler architecture and better models
[05:41](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=341s)
Zoneraich attributes the recent improvement in coding agents to two changes: simpler agent design and models that are better at tool calls and autonomous work. His shorthand is, "give it tools and then get out of the way." He argues against surrounding model flaws with layers of prompts, classifiers, embeddings, and branching workflows that may become unnecessary as models improve. The architecture should have less scaffolding and more room for the model to explore. He connects this to the Zen of Python: "simple is better than complex" and "flat is better than nested."

### The core agent is a single master loop that runs tools until the work is done
[11:17](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=677s)
Claude Code and other current coding agents can be understood as one while loop. While the model returns tool calls, the system runs each tool, sends the results back, and repeats. When there are no more tool calls, it asks the user what to do next. Zoneraich says this was surprising when he first used tool calls because the model could decide when to continue and could often correct its own mistakes. He believes relying on that flexibility makes the system work better as models improve.

### Claude Code's tools imitate actions a developer would take at a terminal
[12:50](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=770s)
The tools Zoneraich discusses include read, grep, glob, edit, bash, web search, web fetch, to-dos, and tasks. Read handles token limits for large files. Grep and glob let the model search directly instead of depending entirely on vector retrieval. Edit uses diffs instead of rewriting whole files, which reduces context use and mistakes. Bash is the most important tool in his view because it can run commands, create temporary scripts, run tests, start environments, and remove files. It also has extensive training data behind it, making it a universal adapter for many tasks.

### To-do lists add structure through prompts instead of deterministic control flow
[18:11](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=1091s)
Claude Code's to-do mechanism gives the model a structured plan without enforcing that plan in application code. The system asks for one task at a time, completion markers, useful task breakdowns, and continued work on blocked items. The list can include an ID, title, status, version, and evidence. Zoneraich says the structure helps the model plan, resume after crashes, stay steerable, and give the user visible progress. He finds the design notable because it depends on instruction following and would not have worked reliably with earlier models.

### Context management determines how long an agent can work effectively
[21:06](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=1266s)
Zoneraich repeatedly returns to context length as the agent's main constraint. When the context becomes too full, he says, the model gets "stupider." Claude Code uses an asynchronous buffer and a context compressor that can drop the middle while summarizing the head and tail. Tasks and sub-agents keep long operations out of the main thread. A sub-agent gets its own context and returns only its results. He also recommends saving useful information as markdown files in a sandbox, since later work can read those files instead of carrying every detail through one conversation.

### Sandboxing and permissions contain the risks of giving an agent shell access
[27:20](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=1640s)
The less glamorous part of the design is the permission and sandboxing system. Zoneraich warns that an agent with shell access and web fetching can be exposed to prompt injection from the internet. Claude Code can block URLs, place some work in a sub-agent, and gate Bash commands according to their prefixes. He admits that he often uses a permissive mode locally, while saying his team does not use that approach with enterprise customers. The controls matter because some team members have accidentally dropped local databases.

### Skills extend the prompt without putting every instruction into the main context
[33:21](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=2001s)
Zoneraich describes Skills as an extendable system prompt for tasks that need extra instructions. His examples include documentation updates, Microsoft Word and Excel work, design style guides, deep research, and unified diffing. A skill can encode a product's writing style or teach Claude Code how to perform a specialized workflow. He also describes a limitation: skills may not be invoked when expected, so users sometimes need to call them manually. He says this could be a prompting issue, a model-training issue, or a sign that the invocation mechanism is still immature.

### General-purpose agents should rely on models, while strict requirements belong in tested tools
[22:32](https://www.youtube.com/watch?v=RFKCzGlAU6Q&t=1352s)
Zoneraich advises engineers to leave exploration to the model and put deterministic requirements into structured tools that can be evaluated and versioned. He gives the example of an email workflow with a fixed format, an assertion that checks the result, and a revision step when parts are missing. Such a workflow is easier to test because its output is constrained. For agent evaluation, he suggests end-to-end tests, point-in-time tests, and backtests over captured historical data. He also proposes watching agent behavior, such as tool-call counts, retries, and execution time, as practical sanity checks.

## Notable quotes
- "Give it tools and then get out of the way is what a one-liner of the architecture is today." (06:20)
- "The more you lean on the model to explore and figure it out, the better and more robust your system is going to be when it comes to better models." (12:23)
- "The most interesting thing to me is it's not enforced deterministically." (18:37)
- "The biggest enemy here is when your context is full, the model gets stupid for lack of better words." (15:29)
- "When in doubt, rely on the model when you're building agents." (55:23)

## Tools & references mentioned
- Claude Code
- Anthropic
- PromptLayer
- Cursor
- ChatGPT
- Codex
- Amp
- Sourcegraph
- Factory
- Droid
- Devin
- OpenAI
- Claude Code Skills
- RAG
- unified diff
- Zen of Python

## Who should watch
- You are building a coding agent and need a simpler architecture than a large graph of prompts and classifiers.
- Your agent can use shell commands or the web, and you need practical guidance on sandboxing, permissions, and context control.
- You need predictable outputs from an otherwise flexible agent and want an approach for separating model exploration from tested workflows.

## Related talks

- [Claude Code & the evolution of agentic coding](https://aietalks.com/talks/claude-code-the-evolution-of-agentic-coding) (Boris Cherny, Anthropic, 18:12)
- [Claude Agent SDK [Full Workshop]](https://aietalks.com/talks/claude-agent-sdk-full-workshop) (Thariq Shihipar, Anthropic, 1:52:25)
- [Boris explains Claude Code](https://aietalks.com/talks/boris-explains-claude-code) (Boris, Anthropic, 00:56)
- [Code Mode: Let the Code do the Talking](https://aietalks.com/talks/code-mode-let-the-code-do-the-talking) (Sunil Pai, Cloudflare, 19:40)
- [Evolving Claude APIs for Agents](https://aietalks.com/talks/evolving-claude-apis-for-agents) (Katelyn Lesse, Anthropic, 13:25)