The Claude Code Operating Model

1Same model, different harness, different agent

The frame first, with a figure from the book. Terminal-Bench 2.0 is a benchmark of command-line tasks. On it, the same model goes from 52.8% to 66.5% success. Only its surroundings changed. The book doesn't say what changed in them.

Jia Huang calls those surroundings the harness. It has five parts:

• tools: what Claude can call, such as reading a file or running a command;
• permissions: what it is allowed to do;
• context management: the context is everything Claude has in view, your messages, its answers, the files it read;
• hooks: scripts that check its actions;
• the agentic loop: observe, form a hypothesis, verify, and start again until the task is done.

Those five parts give the book its formula: "Agent = Model + Harness." (ch. 7). In plain terms: with the same model, the harness makes the difference. One of the book's examples shows it. A review subagent is a second Claude tasked with reading the code. The book gives it only three tools: Read, Grep and Glob. They read, search and list files by pattern. So this subagent can't modify anything, even if it's wrong. The limit comes from the harness, not the model.

2A short CLAUDE.md says more than a long one

First axis of the harness: what Claude knows about your project. And it knows very little. In the book, Xiaobing asks for a login API. An API is the entry point a program calls. Claude hands back Express code, to install with npm install. But the project uses Fastify and pnpm.

For a newcomer, those four names fall into two pairs. Express and Fastify are two JavaScript web frameworks. npm and pnpm are two package managers, the tools that install libraries. Claude picked the pair it saw most often during training. Every session is a first day: what it lacks "is not capability, but context" (ch. 10).

The book fills that lack of context with CLAUDE.md. CLAUDE.md is a text file at the project root. Claude reads it at the start of every session, like an onboarding manual for a new hire. The file arrives as a high-priority message, right after the system instructions, the model's base instructions. So it remains an instruction, not an enforced setting: Claude can ignore it. Here is a bad file and a good one, according to the book:

# ✗ BEFORE (book example)
Team of 5, project started in March 2024.
The code must be well written. Tests must be complete.
Please follow best practices.

# ✓ AFTER (book example, shortened)
- Fastify 4 (do not use Express)
- pnpm 8 (do not use npm/yarn)
- src/routes/: routes only; business logic goes in src/services/
pnpm test   # runs vitest (JavaScript test tool)

The bad file fails because it stays vague. "Well written" doesn't say which formatting. "Complete" doesn't say which tests. To sort the rules, the book offers a test: if Claude behaves well without a rule, "that rule does not belong in CLAUDE.md" (ch. 14).

That sorting has a reason: "instruction density is inversely proportional to compliance probability" (ch. 12). In other words, the more rules there are, the less each one is followed. That is reasoning, not measurement. The book aims for under 200 lines.

The sorting leaves one question: where does a rule go when it only applies to part of the code? The book puts it in the .claude/rules/ folder. Each file there starts with a header, the frontmatter, a block between two --- lines. The header's paths: field says when to load the rule:

---
paths:
  - "**/*.test.ts"
---
Use vitest; jest is forbidden.

This rule enforces vitest instead of jest, two JavaScript test tools. It only loads when Claude touches a test file.

3A skill only loads when it's needed

CLAUDE.md says what Claude must know. That leaves the how: the procedures it follows. The book stores them in skills. A skill is a folder that holds a SKILL.md file. That file describes a procedure, for example doing a code review or preparing a commit. A commit is a recorded set of changes in the Git history. Claude reads the skill only when it needs it.

The book pictures that on-demand loading with an image: "CLAUDE.md is the wall, while Skills is the filing cabinet" (ch. 16). The wall is always in view. The cabinet is opened when the case file arrives. The gain is counted in tokens. A token is a chunk of a word, the unit the model counts and bills. At rest, Claude loads only the skill's description: about 100 tokens. The full skill weighs 5,300.

So everything rests on the skill's description: "The semantic matching mechanism relies entirely on the description field" (ch. 20). And that signal often misses. The book cites an evaluation by the company Vercel. Without explicit guidance, the tested skill was not invoked in 56% of cases. The book states the limit of that figure: one skill, one evaluation.

Hence the book's method: write the description with users' own phrasing, then test it on ten to twenty cases. Here is the start of a SKILL.md, my own:

---
name: commit
description: Prepares a clean commit when the user says "commit" or "save my changes".
disable-model-invocation: true
---

This skill carries one more field: disable-model-invocation: true. The field reserves the skill for manual calls, by typing /commit. Why stop it from starting on its own, when a review skill can? The book reasons from the worst case. A side effect is what an action changes outside itself, such as a written file. The rule: "The greater the side effect, the tighter the control must be" (ch. 21). A botched review breaks nothing. A commit made without you does.

4A subagent saves context, not the bill

CLAUDE.md and skills fill the same space: Claude's context. And that space has a fixed size. When Claude loses the thread, it isn't forgetting: in the book's words, "it's drowning in a flood of information" (ch. 28). Its context window is the text it keeps in view, 200,000 tokens by default.

Picture that window as a desk. Out of 200 lines of test output, only the line "3 tests failed, 47 passed" matters. The rest clutters the desk. Hence the third mechanism, the subagent. A subagent is a second Claude instance, launched for one task, with its own window. It reads the noise on the side. Only its summary comes back to the main conversation.

The book puts numbers on the gain over five exchanges. An exchange is a round trip: your message, then Claude's answer. But the model's API remembers nothing from one exchange to the next. So each exchange resends everything. The system instructions weigh 5,000 tokens. The history weighs 8,000 tokens, plus 1,000 per exchange. Without a subagent, the test output adds 10,000 tokens. The total over five exchanges:

• without a subagent: 23,000, 24,000, up to 27,000 tokens per exchange, or 125,000 in all;
• with a subagent: the conversation only receives a 100-token summary, and weighs 13,100 to 17,100 per exchange, or 75,500. The subagent consumes 41,000 tokens once. Total: 116,500;
• the gap: 8,500 tokens, or 6.8%.

That already thin gap shrinks further with prompt caching. Thanks to the cache, tokens already sent cost 10% of the price. The gap then falls to 1 or 2%. The book admits it grows over 10 or 20 exchanges. So the real value is elsewhere. With a subagent, Claude compacts its history later, meaning it summarizes it later. So it loses fewer details.

When should you launch a subagent, then? The book's practical rule compares the volume to read with the volume to report back: "examine the input-to-output volume ratio" (ch. 34).

5CLAUDE.md advises, a hook decides

Second axis of the harness: what Claude is allowed to do. The hooks module opens with an incident. A .env file holds the project's passwords and API keys. That file is pushed by mistake to the repository, the shared copy of the code. The result: half a day spent rotating every key. No line of CLAUDE.md can prevent it, since Claude can ignore an instruction.

For a rule that allows no exception, the book therefore moves to hooks. A hook is a script that Claude Code runs before or after an action by Claude: read, write, run a command. If the script exits with code 2, the action is refused. Its error message then goes back to Claude. Here is a hook of my own, following the book's principle:

#!/bin/bash
# .claude/hooks/block-env.sh
FILE=$(cat | jq -r '.tool_input.file_path // ""')
if [[ "$FILE" == *".env"* ]]; then
  echo "Writing to .env refused" >&2
  exit 2
fi
exit 0

The script above is declared in .claude/settings.json. A matcher there names the targeted tools, here Write|Edit: writing and editing a file. A second field gives the command to run. Inside the script, jq reads the data Claude Code sends, in JSON, a text format for structured data.

The book sums up the gap with CLAUDE.md: hooks "are not suggestions, but enforcement" (ch. 38). It draws a lesson about deterministic rules, which always give the same result for the same input: "deterministic rules are always more trustworthy than judgments made by large models" (ch. 40). Yet a hook only sees what it is shown. My example only covers the write tool. The command cat > .env, which writes the file from the terminal, therefore slips through.

A hook can also rerun the tests at the end of each of Claude's answers. That hook must then check the stop_hook_active flag, a true-or-false value. Otherwise, the loop never ends:

1. Claude says it is done, the hook runs the tests, they fail, the hook stops Claude from finishing.
2. Claude fixes things and says it is done again. The hook fires again, with stop_hook_active set to true.
3. The script sees that flag, exits with exit 0 without rerunning the tests, and Claude stops.

6MCP: plug in everything, open up little

Hooks bound what Claude does inside the project. MCP does the opposite: it reaches outside the project, which raises the same question of rights. Say Claude must read a ticket in Jira, a task-tracking tool. It needs an adapter: a small program that connects it to Jira.

The problem is the number of adapters. You need one for each pair of assistant and tool, an assistant being Claude Code, for example. With 5 assistants and 100 tools, that is 500 adapters to write (5 × 100).

The MCP (Model Context Protocol) solves this with a common language. Each assistant learns it once, and so does each tool. Then 105 connections are enough (5 + 100). It works like a USB-C port: one cable for every device. The book takes up Anthropic's line: "MCP is the USB-C of AI tool integration" (ch. 46).

An MCP server is the program that gives access to a tool or to data. You declare it in a .mcp.json file, at the project root. The book's gives access to the /workspace folder. The npx -y command runs the server without installing it first:

{ "mcpServers": { "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } }

A server talks to Claude over stdio when it runs locally, and over HTTP when it runs remotely. The older SSE transport is replaced by HTTP (ch. 47).

Plugging in a tool also means opening access to it. So the book sets two limits:

• a database: "database connections should only use read-only accounts" (ch. 48);
• a third-party server: "pin the version, read the source, and scope its credentials to the narrowest thing that works" (ch. 49).

That leaves placing MCP next to the skills of idea 3. The book's image: MCP is the kitchen, a skill the recipe (ch. 50). MCP provides the tools and the data. The skill says how to use them for a specific case.

7With no one at the screen, set everything up front

So far, a person has been watching Claude work and guiding it. The last mechanism does without them. Headless mode runs Claude with no screen, from a script. You launch it with claude -p "...". It is mostly used in CI. CI (continuous integration) is a robot that checks every change pushed to the repository.

But that person did three things. They approved actions, judged the result and decided what comes next. Without them, you must write those three decisions into the command in advance. Here is the book's review command, shortened:

claude -p "Review these files. End with <VERDICT>approved</VERDICT>
or <VERDICT>request_changes</VERDICT>" \
  --max-turns 10 --max-budget-usd 0.50 --allowedTools "Read,Grep,Glob"

Each setting in that command replaces one of those three decisions:

• Tool allowlist (--allowedTools), in place of the person who approves: only Read, Grep and Glob are allowed.
• Turn and budget ceilings, in place of the person who decides what comes next. A turn is one step of the assistant's loop. It can contain several tool calls, so turns and tool calls don't match one for one.
• Final status and sentinel line, in place of the person who judges the result. The final status says how the run ended. The sentinel line is a fixed marker the script looks for in the answer, here <VERDICT>.

Each of those settings has its trap. First trap, the ceilings: set them above the maximum observed over ten real runs. A run cut off by its ceiling exits with the status error_max_turns. A script that doesn't test for that status sees a success. The budget ceiling gives another status, error_max_budget_usd, and no conclusions.

Second trap, detecting the verdict. The sentinel line fails the CI unambiguously. A word search with grep does worse: a grep critical also fires on "no critical issues", which says everything is fine. The book puts it this way: "Match an explicit sentinel, never a bare grep for "critical"" (ch. 56).

Even with these limits, an agent can leak a secret. Book example: a read-only review agent is asked to "check the configuration". It copies the .env, the secrets file, into the CI log. GitHub Actions is GitHub's CI service, and it masks secrets in its logs. That masking doesn't cover text written by the model (ch. 59).

8The bill triples, and Claude isn't to blame

The first seven ideas tune the tool. The last one shows that a well-tuned tool isn't enough for a whole team. Here is the book's case. Three months after adopting Claude Code, the bill is three times higher than forecast. The cause is a session of nearly five hours on logs, the records an application writes. Those logs stayed in the conversation, so they were billed again at every exchange.

A second issue comes on top: each engineer has their own CLAUDE.md, so Claude doesn't follow the same rules for one and for another.

The CTO draws a lesson from this: "We have the tool, but we have yet to establish engineering practices to match it" (ch. 76). The book offers three practices to close that gap:

• Look for the cause in order (ch. 78). Imagined example, not from the book: Claude uses Express, a JavaScript web library, while the team uses another one. First possible cause, context was missing: CLAUDE.md says nothing about it. Second cause, instructions contradicted each other. Third cause, a permission was missing, and Claude fell back on what it had. The example is mine, the order is the book's.
• Review CLAUDE.md like code: "CLAUDE.md should be treated as core code and included in a rigorous code review process" (ch. 82). Every change goes through a pull request, a reviewed change proposal. A senior engineer approves it before merging.
• Don't pay for the logs at every exchange: hand the analysis to a subagent. It reads the logs on its own side, and the main conversation no longer carries them (ch. 77).