Saltar al contenido
artículos
AI EngineeringAI AgentsEvalsClaude CodeBook Review

AI Engineering by Chip Huyen, Read by Someone Who Builds With Coding Agents

Chip Huyen's AI Engineering, chapter by chapter, for people who build software with coding agents: what each chapter really teaches, how it plays out in Claude Code, what aged since it came out, checked against 28 days of my own logs.

The book describes every piece of a coding agent except the one that holds the pieces together.

AI Engineering: Building Applications with Foundation Models (Chip Huyen, O’Reilly, December 2024, 532 pages) is worth reading in 2026 if you build software with coding agents, but not cover to cover. Chapters 4, 5, 6 and 10 (evaluation, prompts, agents, architecture) transfer almost directly to a Claude Code workflow. Chapters 1, 2, 3 and 9 give you the vocabulary of planning, sampling, judges and cost. Chapters 7 and 8 are for people who train models. What aged: it came out before Claude Code, gives agents about 25 pages, and never names the harness, the code that ties instructions, context and model together. Its closest terms are agent framework and orchestrator.

I read it to the last chapter, then checked each chapter against 28 days of my own Claude Code logs: 90 sessions, 2,535 turns I typed, nearly 24,000 calls to Claude models. The numbers in this review are mine. I have shipped production code for 25 years, and most of the last year with agents doing the typing, including a 13-app crypto fintech in 70 days. I would hand this book to whoever builds the agent platform. Someone who starts with Claude Code tomorrow should read four chapters and know why they can skip the rest.

If you already write specs for your agent, start with chapter 4. Its rule is evaluation-driven development: define the evaluation criteria before you build, which is what a spec’s acceptance criteria are when you write them as checks. When I built one payments feature twice with the same agent and model, a one-line prompt passed 8 of 14 hidden acceptance checks and the spec passed 14 of 14.

Free book · 169 pages · PDF + EPUB

AI Engineering says define the eval before you build. The free book turns that into a spec with acceptance criteria, an approval gate and a Claude Code kit.

Get the free book

What the book covers, and what a coding agent adds

The preface names three things that decide the quality of a model’s answer: the instructions, the context and the model. Chapter 5 covers the instructions (prompt engineering), chapter 6 the context (RAG and agents) and chapter 7 the model (finetuning). The unit of analysis is one request to one model.

A coding agent works at a different unit: hundreds of model calls in a loop. Between calls, something decides which instructions and files go into the next one, which model runs it, which tools it may use, and whether the last result passes before the next step starts. That layer is now called the harness. Claude Code and Codex are examples.

The book covers parts of this layer in separate places. Chapter 6 describes agent frameworks by the planners, tools and control flows they support, and recommends human approval before risky actions. Chapter 10 adds guardrails, a router and an orchestrator that chains components with a format check between steps. It does not treat these as one component, and coding agents appear only as one example in chapter 6, SWE-agent. Harness engineering covers that layer directly.

The map below reads each chapter by the part of a coding agent it informs, rated read, skim or skip for someone who builds with one. Each card also names a rung of the ladder I use to hand work to agents. At L1 the agent suggests. At L2 it edits files and you review every diff. At L3 it takes the task and opens the pull request. At L4 it plans, builds, checks itself and delivers at a gate, a point where work stops until a check or a person approves it. At L5 it ships to production, and what happens there feeds the next task. Pick a chapter:

Each chapter, mapped to a part of your harness

1. Introduction

SkimGate · L3 to L4
In the book
Set a usefulness threshold (quality, latency, cost) before you build. LinkedIn reached 80% of what it wanted in one month and spent four more trying to pass 95%.
In your coding agent
Promote a type of task, not a team. When one task type clears its threshold, that type moves up a rung.

Copy this: Write the threshold for one task type before you let the agent run it alone. The agentic ladder

Read this chapter below

2. Understanding foundation models

SkimVerify loop · L3
In the book
Verifiers gave about the same gain as a 30x bigger model. A model tends to repeat similar mistakes across queries.
In your coding agent
Your tests and type checker are the verifier. A repeated mistake gets a fixer (a lint rule, a hook), not another line of prose.

Copy this: Turn the mistake your agent repeats most into a lint rule.

Read this chapter below

3. Evaluation methodology

SkimReviewer · L4
In the book
An AI judge is a system: a model plus a prompt plus its settings. Judges favor their own output, the first answer and the longer one.
In your coding agent
Your reviewer subagent is a judge. Version its model and prompt, and keep its verdict as advice.

Copy this: Pin the reviewer's model and prompt in the repo, like code. How to test a Claude skill

Read this chapter below

4. Evaluate AI systems

ReadGate · L4
In the book
Evaluation-driven development: define the criteria before you build. About 100 examples to trust a 10% difference.
In your coding agent
The spec's acceptance criteria are the eval. What code can check becomes a test, the rest a yes/no check.

Copy this: Map each requirement to a test, a judge check or a person. What is spec-driven development

Read this chapter below

5. Prompt engineering

ReadContext and guardrails · L2
In the book
System and user prompts are processed the same way. The risk of prompt attacks may never be fully eliminated.
In your coding agent
AGENTS.md is input, not law. What must hold goes into permissions, hooks and CI.

Copy this: Move one rule from AGENTS.md into a hook this week. AGENTS.md

Read this chapter below

6. RAG and agents

ReadAgent loop · L3
In the book
At 95% per step, 10 steps succeed 60% of the time. Decouple planning from execution. An agent can be convinced it is done when it is not.
In your coding agent
Checks inside the loop and a plan gate before execution. The agent's own done closes nothing.

Copy this: Approve the plan before execution on any task you will not watch. Harness engineering

Read this chapter below

7. Finetuning

SkipModel
In the book
Finetuning is for form, RAG is for facts. Base models may improve faster than your finetune.
In your coding agent
A facts failure is a context failure. A form failure is fixed in the harness, not in the weights.

Copy this: Read Reasons Not to Finetune and Finetuning and RAG, then stop.

Read this chapter below

8. Dataset engineering

SkipEval data · L4
In the book
Annotation guidelines are the same as evaluation guidelines. Automating data verification is harder than automating generation.
In your coding agent
Your golden set and rubric follow the same rules: what separates a 3 from a 4?

Copy this: Start the golden set with 20 to 50 real cases from your history.

Read this chapter below

9. Inference optimization

SkimCaches
In the book
Without a prompt cache, the model processes the system prompt on every query. Prefill, decode, time to first token.
In your coding agent
A coding agent resends its whole context on every call. The cache decides the bill.

Copy this: Change models or tools only where the context starts fresh: a new session or a subagent. Where agent tokens die

Read this chapter below

10. Architecture and user feedback

ReadThe whole harness · L5
In the book
Five steps: context, guardrails, router and gateway, caches, agent patterns. Change failure rate. Degenerate feedback loops.
In your coding agent
The same five parts in reverse: the loop comes first now. Monitoring is what lets an agent run back into the loop.

Copy this: Know your change failure rate before an agent merges anything. What an agent harness is

Read this chapter below

Read: chapters 4, 5, 6 and 10. Skim: 1, 2, 3 and 9. Skip: 7 and 8.

Chapter 1, Introduction: promote a type of task, not a team

Chapter 1 reads like an overview, and most of it is one: a short history from language models to foundation models, then a tour of eight use cases. Skim that. The middle section, Planning AI Applications, is the best planning framework in the book. She wrote it for a support chatbot. Swap in a coding agent and nearly every rule holds.

You adapt and evaluate a model someone else trained

The chapter’s definition is short: AI engineering is building applications on top of foundation models. It differs from classic ML engineering in three ways. You use a model someone else trained, so the work moves from training to adaptation. The models are bigger and slower, so inference cost matters more. And the outputs are open-ended, which makes evaluation much harder. Her summary is that the job is “less about model development and more about adapting and evaluating models.”

She splits the stack into three layers: application development (prompts, context, evaluation, interface), model development (training, finetuning, datasets, inference optimization) and infrastructure (serving, compute, monitoring). You start at the top and go down only when you must. Her comparison table moves prompt engineering from not applicable to important, and evaluation from important to more important. The full-stack section adds the shift in workflow: build the product first, and invest in data and models only once the product shows promise.

A team on Claude Code or Codex never leaves the top layer. You don’t train and you don’t serve. You adapt with the three things the preface names: the instructions (the task, the spec, AGENTS.md), the context (files, skills, tool output) and the model that runs each step. Then you evaluate. The code that picks among them and checks each step is the harness from the top of this review, and the book’s application layer has no box for it. The parts are in what an agent harness is.

The chapter’s sharpest evaluation warning fits here too. Gemini Ultra scored 83.7% on MMLU, a multiple-choice exam across 57 subjects, when shown five solved examples, and 90.04% with Google’s CoT@32 setup, which samples 32 step-by-step answers and goes with the consensus. Same model, different adaptation, six points apart. The same model in two harnesses is two systems, and an agent score quoted without its harness is that 90.04% without the footnote.

The book’s promotion rule is scoped to one type of request

Before building, the chapter asks what role the AI plays, using Apple’s guidance on AI in products. Two of the axes matter for agents. Critical or complementary: Face ID doesn’t work without its model, Gmail works fine without Smart Compose, and the more critical the AI, the more reliable it has to be. Reactive or proactive: a chatbot answers when asked, a traffic alert in Google Maps shows up on its own. Proactive output gets a higher quality bar, because nobody asked for it and a bad one reads as intrusive.

Then the role of humans. Her support bot can draft replies for human agents, answer simple requests and route the rest, or answer everything. Microsoft’s Crawl-Walk-Run sets the pace: human involvement is mandatory, then the AI works directly with internal employees, then more automation, possibly in front of customers. The promotion test comes with an example number. When 95% of the AI’s suggested replies to simple requests are used verbatim by the human agents, let customers talk to the AI directly for those simple requests.

Notice the scope of that rule. It promotes one type of request, on a measured acceptance rate. The same rule fits the agentic ladder: promote one type of task at a time, never a whole team at once.

Crawl-Walk-Run, on the agentic ladder

Microsoft's stageIn the bookOn my ladderWho checks the work
CrawlHuman involvement is mandatoryL1 to L2: the agent suggests or edits filesYou, on every diff
WalkThe AI works directly with internal employeesL3: the agent takes the task and opens the PRA teammate, on the PR
RunMore automation, possibly with external usersL4 to L5: the agent delivers at a gate, then shipsYou at the gate; at L5, on call
The book's example: when 95% of the AI's suggested replies to simple requests are used verbatim, let customers use the AI for those requests. I apply it per type of task. For code, verbatim means merged with no human commit on top.

A docs change can clear that bar long before a change to the payments path does, so the two sit on different rungs in the same repository. Her two axes say where the bar goes up:

Where an agent's bar goes up

  • A payments ticket

    cost of a wrong change: high · work: reactive

    Critical and requested. A spec, the gate and a person on the PR.

  • An unasked payments change

    cost of a wrong change: high · work: proactive

    Critical and unrequested. The highest bar on the board.

  • Docs you asked for

    cost of a wrong change: low · work: reactive

    Complementary and requested. The first types of task to promote.

  • Dependency bumps

    cost of a wrong change: low · work: proactive

    Complementary and unrequested. Cheap to get wrong, and nobody asked, so the bar sits higher than it looks.

Horizontal axis: work, from reactive to proactive. Vertical axis: cost of a wrong change, from low to high.Chapter 1's critical or complementary and reactive or proactive, applied to code. Proactive output needs a higher bar because nobody asked for it.

The right column is the L5 problem. An agent that opens pull requests nobody asked for, hunting flaky tests or bumping packages, is her proactive feature. It needs a stricter gate than the agent working your ticket.

A thin layer gets eaten by the next model

On defensibility the chapter names three moats: technology, data and distribution. With everyone on the same few foundation models, the technology converges and distribution favors incumbents, which leaves data and usage. Her example is a PDF-parsing app built on the assumption that ChatGPT parses PDFs badly. Its ability to compete weakens the day the assumption breaks.

Harness builders face the same squeeze. Plan mode, subagents and a todo list all ship inside Claude Code now. If your internal tooling was one of those, the vendor built it for you. What the vendor can’t ship is your domain context, your eval cases, your gate definitions and your logs. Usage data works as a moat at any size: every number about my own agent in this review comes from my session logs. Build the parts the next release can’t absorb, because the harness is your edge.

A gate without numbers is an approval button

Setting Expectations starts from the business metric (for the support bot: the share of messages automated, response time, hours of labor saved) and then fixes a usefulness threshold, meaning how good the product has to be to be useful. Her groups are quality, latency (time to first token, time per output token, total), cost per request, and the rest, such as interpretability and fairness. Latency is relative: if humans answer in a median of an hour, anything faster may be good enough.

Milestone Planning adds two habits. Evaluate the off-the-shelf model first. If the goal is to automate 60% of tickets and the model already handles 30%, the plan differs from one where it handles none. And expect the goal to change after that evaluation, sometimes to dropping the project, when reaching the threshold costs more than it returns.

Then the last mile. The section opens on it: “It’s easy to build a cool demo with foundation models. It’s hard to create a profitable product.” The UltraChat authors found 0 to 60 easy and 60 to 100 very hard. LinkedIn reached 80% of the experience it wanted in the first month and spent four more months trying to pass 95%, much of it on product kinks and hallucinations.

An agent finishing one task end to end is the demo. Letting it deliver at a gate on its own, L4, is the four extra months. So write the threshold for one type of task before you promote it, tie it to the business metric that type serves, and use the units an agent is actually measured in:

The usefulness threshold for one type of task, before L4

  • Required:
    Quality: the checks passThe one verify command (lint, type check, tests) is green and the acceptance checks pass, including some the agent never saw
  • Required:
    Accepted without editsThe share of its PRs merged with no human commit on top. The book's example bar is 95%
  • Required:
    Cost per taskDollars per merged PR at list price, cache included
  • Required:
    Time to a reviewable PRWall-clock, against what a person takes today
  • Anti-pattern:
    Time to first tokenA chat metric. Nobody waits on the first token of a task that runs for minutes

Every model upgrade changes your harness

The maintenance section calls the field a bullet train. Providers cut prices in half and your in-house option becomes the expensive one. A vendor you built around runs out of funding. APIs converge, but each model has its own quirks, so prompts, workflows and data need adjusting on every swap, and without versioning and evaluation in place that swap hurts.

For a coding agent, every model release changes how your AGENTS.md, skills and prompts behave, in every repo at once. Without a regression eval, the upgrade is a change nobody reviewed. The pace also argues against finetuning for agent work, a case chapter 7 makes in full.

Where it aged: coding is one use case among eight

The coding section is a snapshot of 2024’s completion tools: Copilot passing $100 million in annual recurring revenue, single-purpose tools for commit messages and screenshot-to-code, and McKinsey’s numbers (twice as productive on documentation, 25 to 50% on code generation and refactoring, minimal gains on highly complex tasks). Agents show up under workflow automation, booking restaurants. Claude Code launched as a research preview on February 24, 2025, less than three months after the book.

The claim I would re-test first is the one about complex tasks. I built a 13-app crypto fintech in 70 days, solo, with Claude Code guided by specs and about 1,650 tests. The speed came from the specs and the tests, which is the planning half of this chapter applied to code. Skim the use cases. Read Planning AI Applications twice.

Chapter 2, Understanding Foundation Models: sampling explains more of your agent than the transformer does

She calls sampling perhaps one of the most underrated concepts in AI, and for anyone running a coding agent it’s the part of chapter 2 that pays. Skim the architecture and scale sections; you never train or serve the model. Keep one idea: input is processed in parallel (prefill) and output one token at a time (decode). Chapter 9 shows why that makes output cost more and lets input be cached.

Your private codebase is a low-resource language

A model is only as good as its training data, and the data is lopsided. English is 45.88% of Common Crawl, eight times the next language. GPT-4 did worst on MMLU in Telugu, Marathi and Punjabi, three of the least represented.

Code follows the same distribution. Python, React and git are high-resource. Your internal frameworks and house conventions are a language with zero speakers in the training data. This site’s AGENTS.md says internal links end in / because the host 307-redirects the slashless URL, and no model learned that from Common Crawl. A context file supplies the training data your domain never had, in about 2,000 tokens, half a percent of what my average Opus call read. Spend them on low-resource facts; clean code is already in the weights. More in AGENTS.md. The same logic, my inference, favors a CLI the model already knows over a bespoke tool it has to learn from a schema: give your agent a shell.

The system prompt’s authority was trained in

Pre-training teaches the next token. Post-training teaches whole responses, in two steps. Supervised finetuning clones demonstrations: InstructGPT used about 13,000 prompt and response pairs. Preference finetuning, in its RLHF form, first trains a reward model, a second model that learns to predict which of two answers a person prefers. It learns from comparisons because scores are noisy (two labelers give the same answer a 5 and a 7) and picking the better of two is easier. InstructGPT’s labelers still agreed only about 73% of the time. The model is then trained to win the reward model’s scores. All of post-training took 2% of InstructGPT’s compute: it unlocks what pre-training built.

Your agent’s obedience comes from there. AGENTS.md carries the authority of a learned habit, and chapter 5 shows how little that is. The comparison finding carries over to evals: compare two versions of a skill on the same input instead of scoring each from 1 to 10. With and without the skill is the simplest pair, the one how to test a Claude skill runs. Even on comparisons, InstructGPT’s labelers agreed only 73% of the time, so expect noise from any single judge.

Temperature is a knob you no longer hold

For each next token the model outputs a raw score, a logit, for every token it knows. Softmax turns those scores into probabilities that add up to 1, and sampling draws one token from them. Temperature divides the logits first. Below 1 it stretches the gaps, so the top token wins more often. Above 1 it squeezes them, so rare tokens get a chance. At 0 the model just takes the top token (argmax). Top-k samples among the k likeliest tokens (she gives 50 to 500). Top-p keeps the smallest set whose probabilities reach p, usually 0.9 to 0.95, so a yes-or-no question draws from two tokens and an open question from many. A stopping condition (a token limit or a stop token) that fires before the closing bracket leaves JSON that won’t parse. Logprobs are the probabilities on a log scale, so tiny ones don’t round to zero. They are the debugging view into a model, and when she wrote, Anthropic exposed none.

On the book’s two-token example, logits 1 and 2, token B gets 73% at temperature 1 and 88% at 0.5. Here is the same softmax on five candidates for the next token of a status check:

Move temperature and top-p on one next token

Next token after: if response.status_code ==

  • 20067.9%
  • 20116.7%
  • 2049.2%
  • 4044.1%
  • 5002.1%
Illustrative logits, the book's softmax. Temperature divides the logits before the softmax; 0 is argmax. Top-p keeps the smallest set of tokens whose probabilities add up to p.

Drag temperature to 0 and 200 takes every draw. Push it to 2 and 500 comes up about one draw in thirteen. Back at 1, set top-p to 0.9 and 404 and 500 drop out. Claude Code gives you no temperature, no top-p and no logprobs. The mechanism still applies: every token of a diff is a draw like this one, so one prompt can produce two different diffs. A tool call is JSON written token by token, so the stopping warning covers every edit. Consistency has to come from the context and the gates; the sampler belongs to the vendor.

A verifier buys what a 30x bigger model buys, until the agent learns to fool it

Test-time compute means generating several outputs and keeping the best (best of N), at about N times the cost. The value is in the pick: the highest average logprob, a majority vote (self-consistency), or your own rule, such as generating until the SQL is valid. A strong picker is a verifier, a model trained to judge whether a solution is correct: “the use of verifiers resulted in approximately the same performance boost as a 30× model size increase.” In the OpenAI paper, a 6B model with a verifier slightly beat a finetuned 175B one.

A coding agent’s loop is the SQL rule with a better verifier, and the agent reads each failure before it tries again. In my logs, 24.9% of 16,156 shell commands were tests, lint or type checks. Spend on the check before the model upgrade.

The same experiment carries the warning. Gains rose up to 400 samples and then fell; the authors guessed that more samples find more outputs that fool the verifier. An agent can read the test, which improves its odds. Anthropic’s Claude 3.7 Sonnet system card (February 2025) reported that model special-casing tests in environments like Claude Code, returning the expected values or editing the tests, usually after several failed attempts at a general fix. More attempts, more chances to game the gate, and my turns run 24 tool calls at the 90th percentile. What holds: acceptance checks the agent never sees (chapter 4 has a run with 14 of them), a reviewer in a fresh context, and a person who reads the test diff.

Code gets by on bandages

For structured output she lists five layers. Prompting, post-processing and test-time compute are bandages for a model that is nearly there. Constrained sampling (a grammar that filters the logits) and finetuning are the intensive treatment. The bandage that pays is post-processing, from an observation she first made teaching students: “A model tends to repeat similar mistakes across queries.” Find the common mistake and a script can often fix it. LinkedIn’s defensive YAML parser took valid outputs from 90% to 99.99%.

With a hosted agent the intensive treatment is the vendor’s: you hold no logits and train no weights. You own the bandages, and code has the best ones in software: compilers, type checkers, formatters and linters.

Her five layers for structured output, on a coding agent

  1. 1

    Prompting

    A rule in AGENTS.md or a skill. The model weighs it against everything else in the window.

    AGENTS.md, skills
  2. 2

    Post-processing

    A script fixes the mistake the model keeps repeating, right after it writes.

    pnpm fix, eslint --fix in a hook
  3. 3

    Test-time compute

    Run the check, read the failure, try again until it passes.

    pnpm verify
  4. 4

    Constrained sampling

    A grammar filters the logits at every token. The vendor's layer: you hold no logits.

    provider side
  5. 5

    Finetuning

    Change the weights. I have never needed it for an agent workflow.

    skipped
5 layers, each adding to the last.

Every long session is a snowball in progress

Sampling makes the model probabilistic, which shows up two ways. Inconsistency: the same prompt scored an essay 3/5 and then 5/5. Fixed settings and a seed help and guarantee nothing; her image is a teacher who grades consistently only in one particular room. Hallucination gets two hypotheses. Self-delusion (DeepMind, 2021), which Zhang et al. call snowballing: the model can’t tell text it was given from text it generated, so an early wrong sentence becomes a fact it builds on. Knowledge mismatch (Leo Gao, then John Schulman): supervised finetuning on answers that use knowledge the labeler had and the model lacked teaches it to make things up. Schulman proposed verification: make the model retrieve its sources. Some teams also prompt the model to say “I don’t know” when unsure.

An agent session is the self-delusion setup at scale:

What my agent reads: 28 days of Claude Code transcripts

tool output
54.8%
from commands the agent chose
the agent's tool calls
33.3%
file writes, edits, commands
the agent's own text
6.5%
everything it said to me
what I typed
1.9%
2,535 turns
Share of characters in my main Claude Code sessions, September 18 to October 16, 2026. Harness messages are the other 3.5%.

About 40% of what the model reads is text it wrote, and most of the rest is output from commands it chose. “This function is unused,” written at minute five, is a given at minute fifty. Compaction locks it in: 76 compactions in 28 days, each replacing the history with a summary the model wrote. The defenses follow that list. “All tests pass” counts only with the command output behind it. A reviewer in a fresh context doesn’t share the snowball. Short sessions, with the context cleared at each gate, cut it short. And a skill eval that passed once proves little: run each case several times and report a pass rate.

Where it aged: the recipe changed, the mechanisms held

The post-training recipe changed under the book. In January 2025, weeks after it came out, DeepSeek-R1 described R1-Zero, a reasoning model trained with reinforcement learning against rule-based rewards (for code, compiler feedback on test cases). It used no neural reward model, because one may suffer from reward hacking. Anthropic’s card traced its special-casing to reward hacking during RL training: at least one model in our terminals, by its maker’s account, learned the shortcut the 400-sample curve hints at. Her cause for nondeterminism at fixed settings, the hardware, also got a sharper answer in 2025: batching, covered in chapter 4. Her conclusion stands. Build the workflow to survive a different answer on every run, and let the gates decide which one ships.

Chapter 3, Evaluation Methodology: your reviewer subagent is a judge, so audit it like one

For many teams, chapter 3 says, evaluation is the biggest hurdle to shipping an AI application. Open-ended output has no complete list of right answers, and the smarter the model, the harder the check. Anyone can spot a wrong first-grade sum. Verifying a coherent book summary means reading the book. So teams fall back on word of mouth and eyeballing, which a footnote calls the vibe check.

A diff from a coding agent is that coherent summary. It compiles, it reads well, and the only way to know it is right is to run it or read every line. The chapter is a tour of the ways to avoid reading every line.

Perplexity is a training metric you will read about and never compute

Entropy is how much information a token carries. Her example is a square: two tokens (upper, lower) need one bit each, four tokens (upper-left and so on) need two. Cross entropy is how hard it is for a model to predict the next token of a dataset: the data’s own entropy plus how far the model’s learned distribution sits from the real one. Perplexity is 2 raised to the cross entropy, roughly how many options the model weighs per token. A perfect model of the four-token square has a perplexity of 4.

Two side uses survive. A suspiciously low perplexity on benchmark text means the model probably trained on it, and a very high one flags gibberish. The limits: post-training usually raises perplexity, so it says little about a chat or coding model, and computing it needs token probabilities that many commercial APIs do not expose. Low perplexity also only means predictable, and a plausible wrong line is predictable too.

Functional correctness is the metric coding gets for free

The chapter splits methods into exact (no ambiguity, like a multiple-choice answer) and subjective (the score depends on who grades). Her bluntest line goes to the exact one: “Functional correctness is the ultimate metric for evaluating the performance of any application, as it measures whether your application does what it’s intended to do.”

Many tasks cannot automate that check easily. Code could long before AI: unit tests, LeetCode’s judge, benchmarks like HumanEval that ship each problem with its test cases. If gcd(15, 20) does not return 5, the function is wrong, and nobody argues.

Without a functional check, you compare against reference answers. Exact match breaks fast: accept any output containing “1929” and “September 12, 1929” passes as Anne Frank’s birth date, which was June 12. Lexical similarity (edit distance, BLEU, ROUGE) counts shared words and fails when the references miss a correct answer. Semantic similarity turns each text into a list of numbers, an embedding, and measures how closely the two point the same way (cosine similarity), so “What’s up?” and “How are you?” land close, and it is only as good as the embedding model. The proof comes from code: on HumanEval, BLEU scores for correct and incorrect solutions were similar. Comparing an agent’s diff to the one you would have written measures resemblance. Run the tests.

pass@k rewards one lucky run, and autonomy needs every run

pass@k is the chapter’s code metric: generate k samples per problem, and the problem counts as solved if any sample passes all its tests. Ten problems, five solved with k = 3, and pass@3 is 50%. That is the right number for best-of-N: launch a few agent attempts, keep one that passes the gate.

It is the wrong number for autonomy. An agent that runs unwatched has to pass every time, and the chapter has no metric for that. τ-bench (Yao et al., June 2024) proposed one, pass^k: the chance that all k trials succeed. In its retail domain, even GPT-4o-class agents passed eight of eight trials less than 25% of the time. Same agent, two very different numbers. Move the sliders:

pass@k vs pass^k

At least one run passes (pass@k)

>99.9%

Every run passes (pass^k)

17%
Assuming independent runs: pass@k is 1 minus (1 minus p) to the k, pass^k is p to the k. At 80% a run, eight runs almost surely include a pass, and all eight pass 17% of the time. Push the pass rate to 95% and eight in a row still pass only 66% of the time. Real runs are correlated, which narrows the gap without closing it. Best-of-N lives on the first number. A task you hand over lives on the second.

A judge is a model, a prompt and its settings, so version all three

The case for AI as a judge: fast, cheap next to people, no reference answer needed, and it explains its verdict. In Zheng et al.’s MT-Bench study, GPT-4 agreed with human raters 85% of the time, more than humans agreed with each other (81%). Read that next to chapter 2’s 73%: people often disagree, so matching them is the most a judge can show, and it does not prove the judge right.

There are three ways to ask: score one response alone (1 to 5), check it against a reference (true or false), or pick the better of two (A or B). The prompt states the task, the criteria and the scoring system. Classification beats numbers, discrete beats continuous, ranges wider than 1 to 5 get worse, and each score level should get an example and, if possible, the reason for it.

She states it flatly: change the model, the prompt or the sampling parameters and you have a different judge. Your reviewer is a judge. Keep its prompt in the repo, pin its model, log both with every verdict, and ask yes or no per criterion. A 1-to-10 quality score is the wide range she warns against.

Each judge flaw has a number and a reviewer rule

Inconsistency: the same judge can score the same input differently on two runs. Examples in the prompt raised GPT-4’s consistency from 65% to 77.5% and quadrupled the spend, and consistent can still mean consistently wrong.

Criteria ambiguity: MLflow, Ragas and LlamaIndex all ship a faithfulness judge, scored 1 to 5, 0 or 1, and YES or NO. One word, three scores nobody can compare. A coherence score that moves from 90% to 92% means the app improved only if the judge stayed the same, and a coworker fixing a typo in its prompt changes it. Her tip applies word for word to a reviewer: “Do not trust any AI judge if you can’t see the model and the prompt used for the judge.”

Cost: one judge per criterion multiplies calls, so a response with three judged criteria is four times the calls. Her fixes are cheaper judges and spot-checking a sample.

Bias, in the numbers she quotes:

AI judge biases, as chapter 3 reports them

GPT-4 win rate on its own answers
+10%
self-bias, Zheng et al. 2023
Claude v1 on its own answers
+25%
self-bias, same study
with errors, beat ~50 correct ones
~100 words
verbosity bias, GPT-4 and Claude 1
Measured on 2023 models. Position bias gets no number in the book: AI judges favor the first answer, while people favor the last one.

Self-bias comes from the mechanism that generates: the answer a model finds most likely is the one it scores highest. So never let the session that wrote a diff grade it. A fresh-context subagent drops the conversation that argued for the diff. It keeps the weights, so a reviewer on the same model still likes what that model would have written. Position bias means comparing two plans twice, order swapped. Verbosity bias means the reviewer rewards the bigger plan unless the rubric asks for the smallest diff that meets the spec.

A stronger model can grade a sample of a cheaper one, and the strongest model has nobody above it. Self-critique is a sanity check and a nudge to revise: her example model answers 30 to 10 + 3, is asked whether that is right, and fixes it to 13. That is the “review your own diff before you finish” step. It is cheap and worth having, and it is never the gate. Her research bet is small specialized judges.

Comparative evaluation says which is better and never whether it is good enough

Pointwise evaluation scores each candidate alone. Comparative evaluation puts two side by side and asks which wins, which is easier when quality is subjective. Wins feed a rating algorithm (Chatbot Arena moved from Elo, the chess rating, to Bradley-Terry, which fits all past matches at once), and the ranking is a prediction that the higher model wins more than half its future matches.

She lists three challenges. Pairs grow with the square of the models: 244,000 comparisons for 57 models in January 2024 came to about 153 per pair. The crowd’s signal is weak: 180 of 33,000 published prompts were “hello” or “hi”, and a vote only means something when the voter knows the subject. The third bites hardest. If model A resolves 70% of support tickets and B beats A in 51% of matches, nobody can tell you how many tickets B resolves.

Use pairwise runs to choose between two versions of a skill or a reviewer prompt. Whether the agent may run a type of task without you takes an absolute threshold, which is chapter 4’s job.

Where I part ways: the judge advises, a test or a person decides

Her summary says AI judges should be backed by exact evaluation, human evaluation or both. I take that order. She also reports, without objection, teams using a judge as a production guardrail. For merges, I would not. Every change I ship passes three review layers, each one a method from this chapter, and the harness wires in the first two:

Three review layers, three of chapter 3's methods

  1. 1

    Deterministic checks

    Exact evaluation. Tests, type check and lint, where functional correctness needs no judge. This decides.

    pnpm verify
  2. 2

    AI reviewer in a fresh context

    A judge: model, prompt and settings, versioned in the repo. Yes or no per criterion. Its verdict is advice.

    reviewer subagent
  3. 3

    Me, on the spec and the pull request

    The human evaluation the chapter calls essential in many cases. Owns the decisions and the merge.

    spec + PR
3 layers, each adding to the last.

No AI reviewer blocks a merge anywhere I have worked. A test or a person does. The biases are the reason: a gate that leans toward its own model’s style, the first option and the longer answer turns taste into a blocker. The numbers are dated: GPT-4 and Claude v1 in 2023, and she reports GPT-4 less prone to verbosity bias than GPT-3.5. Read them as directions; today’s models were not tested.

Chapter 4, Evaluate AI Systems: the eval is the other half of the spec

Chapter 4 opens with a question she asks at conferences: which is worse, an app that was never deployed or one that is deployed and nobody knows whether it works? Most people pick the second. It costs to maintain and can cost more to take down. Her method is named after test-driven development: “In AI engineering, evaluation-driven development means defining evaluation criteria before building.” Coding is a common use case in production, she notes, because generated code can be checked for functional correctness. She names the trap too: building only what is easy to measure is looking for your keys under the lamppost.

Spec-driven development says what to build. Evaluation-driven development says how you will know it is done. I tested the cheap version on October 13, 2026: one payments feature, same agent, same model, built twice. A one-line prompt passed 8 of 14 hidden acceptance checks. The spec passed 14 of 14, and the difference was the criteria written down (the run and the template).

All four buckets of criteria apply to a coding agent

Her four buckets: domain capability, generation capability, instruction-following, and cost and latency.

For code, domain capability is functional correctness plus efficiency (BIRD-SQL times the generated query against the reference one) and readability, which has no exact check and goes to an AI judge.

Generation capability is mostly factual consistency, local against a given context or global against open knowledge, where the hard part is deciding what the facts are. Her methods: an AI judge, SelfCheckGPT (sample more answers, flag disagreement, expensive), SAFE (split the answer into self-contained claims, check each against search) and small entailment classifiers, like a 184-million-parameter DeBERTa, that decide whether a claim follows from the source text. Her best tip: find the queries your model hallucinates on and weight the eval toward them. In one of her projects, those were niche knowledge and questions about things that don’t exist.

Instruction-following is slippery, because a bad output can mean a bad model or a bad instruction. IFEval covers 25 instruction types a program can verify, like a word limit or JSON output. INFOBench turns each instruction into yes/no questions that GPT-4 graded better than crowd workers and worse than experts. Her advice: build the set from your own instructions. Your AGENTS.md is that set, and it splits the same way. What a program can check becomes a lint rule, a hook or a CI step that fails. The rest becomes yes/no items for the reviewer.

Cost and latency are a Pareto problem, where no option wins on every axis: filter out what fails a hard requirement, pick the best trade among the rest, and separate the latency you need from the latency you would like.

Chapter 4's criteria, for a coding agent

BucketThe book measuresFor a coding agentChecked by
Domain capabilityFunctional correctness, efficiency, readabilityThe code does what the spec says, fast enough, and the next person can read itTests; a judge for readability
Generation capabilityFactual consistency, local and global; safetyIts report matches its tool log; every package, flag and method it uses existsThe gate reruns the checks; installs resolve
Instruction-followingIFEval's checkable types; INFOBench's yes/no questionsIt obeyed AGENTS.md, stayed in scope, left forbidden files aloneLint, hooks and CI; then the reviewer's yes/no list
Cost and latencyCost per token, time to first token, hard requirement vs idealTokens, turns and wall-clock time per finished taskYour session logs, against both columns
The agent's own report never counts as evidence. The checks it claims to have run get run again.

Choose on hard attributes first, then on your own tasks

Hard attributes are what you cannot or will not change: license, privacy, who hosts the model. Soft attributes are what you can work on, like accuracy. Latency is soft if you host and hard if someone else does. The soft side is easy to misjudge: one of her models sat near 20% accuracy and jumped to 70% once she split the task into two steps. The workflow loops through four steps: filter on hard attributes, shortlist with public data, run your own eval pipeline, monitor in production.

Build versus buy gets seven axes: data privacy, data lineage and copyright, performance, functionality, cost, control and on-device deployment. Then a vocabulary fix: open weight means public weights, open model means public training data too. Control still bites. Commercial models change without always telling you, and prompts quietly stop working. One migration, GPT-3.5-turbo-0301 to 1106, dropped Voiceflow’s intent classification by 10% and improved GoDaddy’s support bot.

Public benchmarks fare worst. Leaderboards pick six or ten benchmarks with no clear reason for the cut, and several correlate strongly (MMLU and WinoGrande at 0.90), which exaggerates their biases. Contamination is mostly accidental: a 13-token overlap with training data marks a sample dirty, and GPT-3 had 13 benchmarks with at least 40% of their data in its training set. Public benchmarks filter out bad models. They will not find your best one.

For a coding agent, you pick a harness plus a model, and the hard attributes are whether code may leave your network and what the contract allows. Her contamination rule covers coding benchmarks built from public repositories: if the fix was public before training, the model may have read it. Your own past tasks are the clean set. Pin the model version and treat a vendor upgrade like a dependency bump: rerun the eval set first.

Step 1: grade the task, then find the broken part

Her pipeline has three steps. The first evaluates the end result and every intermediate output. Her résumé example extracts text from a PDF, then the current employer from the text. Score only the end and a wrong answer cannot tell you which step broke. Weigh the task over the turn: fixing a bug in two turns or in twenty is a different product.

My logs count turns, and a turn is not a task: a median of 3 tool calls per turn I typed, 24 at the 90th percentile, 611 in the longest. Gate on the task outcome. Score the parts (the plan, the files read, the tests chosen) when the outcome fails.

Step 2: the guideline is where evals and specs both fail

She calls the guideline the most important step: an ambiguous guideline gives ambiguous scores. It covers what the app should not do, and it separates correct from good. LinkedIn’s job-fit tool telling a candidate they are a terrible fit is correct and useless. Each criterion gets a scoring system and a rubric with an example per score, validated on people. Then each metric is tied to a business number. Her mapping: 80% factual consistency automates 30% of support requests, 90% automates 50%, 98% automates 90%, and below a usefulness threshold the bot is no use at all. Read that next to the ladder and it becomes a promotion rule: a type of task that clears its threshold runs one rung higher.

Here is that guideline for the spec I tested. The requirements use EARS, a template that forces each one into a trigger and a response (WHEN this happens, THE SYSTEM SHALL do that):

From spec to eval: who checks each requirement

Requirement (EARS)Checked byHow
FR-1. WHEN a merchant POSTs a charge with an Idempotency-Key, THE SYSTEM SHALL create at most one charge per key.Test50 concurrent POSTs with one key; assert one row
FR-2. WHEN the same key is replayed within 24 hours, THE SYSTEM SHALL return the original charge.TestReplay at 23 hours; assert the original body and status
FR-3. IF the amount is <= 0, THE SYSTEM SHALL reject the request with 422.TestZero and a negative amount; assert 422 and no charge row
Errors read like the rest of the API.AI reviewerYes/no item with one good and one bad example; advisory
The key lives on the charge, not in a side table.PersonApproved in the design before any code exists
Code checks what it can, a yes/no item covers taste, and a person owns the decision. The three methods chapter 3 says to combine, sorted by what each one can be trusted with.

It breaks at the criterion nobody wrote. In one run from my comparison of four spec-driven development tools (the BMAD review has it), the request said a transfer takes an idempotency key and never said the key was required. OpenSpec, another of the four tools, made it optional, and I caught it in review. Criteria-first is necessary and incomplete. Her own way to find criteria is to judge answers to real queries, and review is where the missing one shows up. It goes back into the spec as a line and into the eval as a check.

Step 3: mix methods, slice the data, count before you believe

Pick methods per criterion and mix them: a cheap classifier on all the traffic, an expensive judge on 1%. Humans stay the north star in production too, and LinkedIn hand-reviewed up to 500 conversations a day. Slice the data, because the aggregate can lie: her Simpson’s paradox table has model A beating B in both groups and losing overall, 78% to 83%. A was tested mostly on the hard group, B mostly on the easy one, and the total hides the mix. Move the mix and watch the overall winner flip:

Simpson's paradox

Model A

Easy cases
93%
Hard cases
73%

Overall

78%

Model B

Easy cases
87%
Hard cases
69%

Overall

83%

Model A wins both groups and still loses overall.

Group scores from the book's Table 4-6, whose groups are unnamed: hard is the one both models score lower on. Give both models the same share of hard cases and A wins the total too. Slice an agent's eval by task type before you compare two models or two prompts.

Her eval sets, for an agent: past merged tasks with their tests (production), tasks it got wrong before (known failures), vague one-line requests (user mistakes), tasks it must refuse or escalate (out of scope). Her rule: “If you care about something, put a test set on it.”

Then size. Bootstrap: draw 100 cases with replacement from your 100, score, repeat. If one draw says 90% and another 70%, the set is too small. OpenAI’s rough table, below, needs about 100 cases to trust a 10% difference at 95% confidence, and every 3x smaller gap costs 10x the cases. A skill tested on 15 cases only sees gaps of about 26%; slide to 100 cases and the smallest gap you can trust drops to 10 points. With an agent, run each case more than once too, because the same task can pass and fail on the same model.

Eval sample size

Smallest difference you can trust

26%
Difference to detectCases needed
30%~10
10%~100
3%~1,000
1%~10,000
The rows are OpenAI's rough estimate, quoted in chapter 4 (Table 4-7). The big number is 1 divided by the square root of the cases, in percentage points, which fits that table.

Evaluate the evaluation, the person included

Her last step audits the pipeline: do better answers score higher, does the same run give the same result twice, are two metrics redundant, what does the eval add in cost and latency. Log the data, the rubric, the judge prompt and the sampling settings, because any of them moves the score.

One piece aged. Her reproducibility fix is a judge at temperature 0. Thinking Machines Lab (Horace He, September 2025) sampled 1,000 completions of one prompt at temperature 0 and got 80 different ones. The server groups your request with other people’s into a batch, and the GPU math comes out slightly different for each batch size, so your output depends on other people’s traffic. Version everything and run more than once.

One piece is missing. Her pipeline audits the judge in detail and takes the human north star as given. Chapter 8 shows why it shouldn’t: people grade worse late in a session. The person approving the agent’s work is part of the pipeline, so evaluate that layer too.

Chapter 5, Prompt Engineering: the system prompt is only the first tokens

Chapter 5 opens as a tips chapter and closes as a security chapter. The hinge is one paragraph of mechanism: the system prompt and the user prompt become a single sequence before the model reads either. The best practices and the attacks both follow from it.

Stronger models need fewer examples, except for code they never saw

A prompt, in her anatomy, has a task description, examples and the task itself. Teaching through the prompt is in-context learning, the GPT-3 paper’s term from 2020: the model picks up a behavior from the window with no weight update. One example is one shot. None is zero-shot.

For why in-context learning works, she borrows François Chollet’s picture: a foundation model is a library of programs, and the prompt picks which one runs. Her numbers show the need shrinking. Few-shot gave GPT-3 a large gain over zero-shot, while in Microsoft’s 2023 analysis it added little for GPT-4. Stronger models also shrug off perturbations like “5” versus “five”, so you fiddle less. Reasoning models absorbed most of the remaining tricks, since they work the problem before answering whether you ask them to or not. Her exception still pays: examples matter for an API the model rarely saw in training (her case is the Ibis dataframe library). In a coding agent, that is your internal framework, and its examples belong in a skill.

She also fixes a word. The prompt is the whole input, the context is the information the task needs. By mid-2025 the work of building that second part had its own name, context engineering.

System and user prompts end up as one sequence

Her real estate chatbot splits the job the usual way: the agent’s role in the system prompt, the uploaded disclosure and the buyer’s question in the user prompt. A chat template then merges them. Llama 2 wraps the system text in <<SYS>> tags. Llama 3 moved to header tokens such as <|start_header_id|>, each read as one token. Get the template wrong, or add a stray newline, and behavior shifts with no error, because the model still answers something plausible. Her rule: print the final prompt before you send it. For hosted coding agents this part aged, since the API writes those tokens for you. It still bites anyone serving open weights.

Then she says it plainly: “From the model’s perspective, system prompts and user prompts are processed the same way.” She gives two likely reasons for the system prompt’s edge. It goes first, and the model may be post-trained on OpenAI’s instruction hierarchy, which ranks system prompt, user prompt, model output and tool output, in that order.

Claude Code doesn’t even put your memory file in the system slot. Its docs say CLAUDE.md arrives as a user message after the system prompt, with no guarantee of strict compliance. So your AGENTS.md ranks as user input: above a fetched web page, and still one input among many.

A rule typed at turn 12 is buried by turn 40

Context windows grew 2,000 times in five years, from GPT-2’s 1K tokens to Gemini 1.5 Pro’s 2M. Reading them well is another matter. Liu et al. (2023) found that models read the start and the end of a prompt far better than the middle. The test is the needle in a haystack: plant a fact at different depths and ask for it. Her advice is to use a private fact, or the model answers from training and the test measures nothing. If quality drops as the prompt grows, shorten the prompt.

Chapter 2’s transcript breakdown says what sits in that middle: 54.8% of the characters are tool output, 33.3% the agent’s own tool calls, 1.9% what I typed. This site’s AGENTS.md is about 2,000 of the roughly 386,000 tokens in an average Opus 5.5 call.

The harness’s system prompt and the memory file sit at the start. The newest tool output sits at the end. What I type drifts toward the middle as output piles up, so a “leave the migrations alone” from turn 12 is buried by turn 40. Compaction adds a second risk: Claude Code re-reads the project CLAUDE.md after compacting, and an instruction given only in conversation can vanish. A rule that must outlive the session goes in a file or a hook.

The durable practices now live in specs, skills and checks

The best-practices half is distilled from the providers’ own guides, and she flags the tricks that aged, like promising the model a $300 tip. What lasts, with her example and where it lives now:

Chapter 5's best practices, moved into a coding agent

PracticeHer exampleIn a coding agent
Clear, explicit instructionsName the score scale and what to do when unsure. Saw a 4.5? Ask for integers.Acceptance criteria written as checks, like the 14 of 14 run in chapter 4.
A personaAsked to grade as a first-grade teacher, the model can move a two-sentence essay from 2 to 4.A reviewer subagent with its own role and a fresh context. Its verdict is advice.
ExamplesOne tooth-fairy example makes the Santa answer kid-friendly. The arrow format costs 27 tokens where Input/Output costs 38.Worth it for APIs the model rarely saw. Examples of your internal framework go in a skill.
Output formatName the JSON keys. End the input with a marker, or the model keeps extending your list.A schema, a linter or a hook checks the format on every edit.
Enough context, and only the contextInclude the paper. Keeping a Skyrim character ignorant of Starbucks has no prompt-only guarantee.The agent gathers its own context with tools. What it must not read is a deny rule.
DecompositionClassify the intent, then answer with one prompt per intent. GoDaddy split a 1,500-token prompt and got better results for fewer tokens.Phases and subagents, a cheaper model for the easy steps, switched where the context starts fresh.
Time to thinkChain of thought (Wei et al., 2022) and self-critique, paid for in latency.Reasoning models think without being asked. Self-critique became a reviewer in a fresh context.
Iterate, and evaluate in the whole systemVersion prompts and fix the eval data. A prompt can improve a subtask and hurt the system.A skill eval that also checks the skill stays quiet where it should.
Distrust prompt tools30 examples times 10 variants is 300 hidden calls. A LangChain default prompt shipped with typos.Read what the harness actually sends: the context breakdown, the tool schemas, the transcript.
Left: the chapter's own examples, from Prompt Engineering Best Practices. Right: where each practice ends up when the model is a coding agent.

Keep the section on organizing prompts whole. Prompts live outside code, carry metadata (model, date, application, sampling settings, schemas) and get versions. Then the trap: when several applications share one prompt in git, an edit updates all of them, and a team that wants the old version has no clean way to keep it. The fix many teams use, she writes, is a separate catalog that versions each prompt explicitly, and a well-built one tracks which applications depend on each prompt. A skill shared across repos is that shared prompt. This site vendors its shared skills from an upstream repo, keeps site-specific edits in a separate overrides folder and pulls upstream changes with one sync command. A change arrives when someone asks for it, as a diff. Git and a script do the catalog’s pinning.

The attacker writes in the same channel you do

The second half names three attacks: prompt extraction, jailbreaking and prompt injection (she calls both jailbreaking), and information extraction. First on her list of risks is remote code or tool execution, which is a coding agent’s normal day. The cause is the mechanism above. Models are trained to follow instructions, and once everything is one sequence, telling yours from an attacker’s is left to the model.

On prompt extraction, she makes the case that a secret prompt isn’t worth much: extracted prompts are often hallucinated, and a proprietary prompt is a liability that needs rework on every model change. She passes on a friend’s advice to write it as if it will go public, which an AGENTS.md in an open repo already is.

Jailbreaks escalate. Manual hacks come first: misspelled keywords, a poem about hotwiring a car, DAN and the grandma exploit, most of which, she notes, no longer work on most models. Then automation: PAIR uses an attacker model that often breaks the target in fewer than twenty queries. Then indirect injection, where the instruction rides in on something a tool returns. Her passive example is a coding assistant that finds a GitHub repo through web search and suggests importing a function that installs malware. Her active one is an email telling an assistant to forward the whole inbox.

Indirect injection is the coding agent’s threat, and the numbers above show why. More than half of what my agent reads is tool output, the lowest rung of the hierarchy and the one strangers can write into: a README, an issue, a PR comment, a fetched page, a reply from an MCP server (Model Context Protocol, the standard way to plug tools into an agent). I have never seen a real attack on my agents. I have seen the open path many times, an agent reading one of those and treating it as an instruction. In one run of that comparison, a single sentence in my own prompt saying the plan was approved made BMAD skip its approval step. Same weakness, no attacker: plain prose beat the tool’s own rule.

Information extraction covers training data, leaked through tricks like asking a model to repeat “poem” forever, and whatever sits in the context. For a coding agent the context is the part that matters. Whatever enters the window can leave it, so the agent shouldn’t read your .env at all.

Count false refusals, and defend where no prompt can argue

She judges defenses with two numbers. Violation rate is the share of attacks that succeed. False refusal rate is how often the system refuses something it could do safely. Refuse everything and you score zero violations with a useless system. In a coding agent, a false refusal is a permission prompt that didn’t need to fire, and you pay for it in attention. Each needless prompt trains you to click yes.

Defenses come in three layers. The model layer is the instruction hierarchy: training on it made a model up to 63% more robust at little cost to its other skills. That layer belongs to the provider. The prompt layer spells out what is forbidden, repeats the instruction after the user input and names the attacks to expect. Pedro et al. (2023) found LangChain’s default templates so loose that every injection they tried worked. The system layer runs generated code in an isolated VM, requires human approval for impactful commands (her example is SQL with DELETE, DROP or UPDATE) and guards both inputs and outputs.

Her conclusion: “as long as your system has the capabilities to do anything impactful, the risks of prompt hacks may never be completely eliminated.” A coding agent has those capabilities on purpose, so the system layer is the one I count. In Claude Code that means permission rules, hooks and a sandbox. Deny rules are checked first, then ask, then allow, and no paragraph in the window changes that order. A rule can still be routed around: the permissions docs say a rule on git push misses git -C . push, and point to the sandbox for a real boundary. The sandbox does her VM’s job, at the OS level. A minimal start for .claude/settings.json:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(curl *)", "Bash(wget *)"],
    "ask": ["Bash(git push *)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

The deny list covers the usual ways to read a secret and the two usual tools for sending one out. The ask list puts a person in front of every push written the usual way. The hook takes a rule out of prose: each edited file is formatted, every time.

What moves out of AGENTS.md

  • Required:
    Formatting, import order, anything a linter can seeA formatter or lint rule, run by a PostToolUse hook
  • Required:
    Files and commands the agent must never touchDeny rules, plus the sandbox when it has to hold
  • Required:
    Push, deploy, migrationsAsk rules: a person approves each one
  • Required:
    Anything that must be true before mergeA check in CI or in the one verify command
  • Optional:
    Why the code is shaped the way it isStays in AGENTS.md, short and near the top
  • Anti-pattern:
    A paragraph asking the agent to distrust what it readsOne user message against 386,000 tokens, most of them tool output

Where it aged: most of the attack catalog targets chatbots. Misspellings and roleplay lead it, and MCP is absent. For a coding agent the danger is an agent acting with your credentials. I’d also stop calling the prompt layer a defense. It lowers the violation rate. Only the system layer caps what a successful attack can do.

Chapter 6, RAG and Agents: the agent half aged better than the RAG half

A model’s instructions are the same for every query, while its context is built for each one, by RAG or by an agent. Huyen calls context construction the feature engineering of foundation models, the hand work in classic ML of choosing what the model sees. It is context engineering under an older name.

BM25 is hard to beat, and embeddings blur the exact token

A RAG system is a retriever that finds what is relevant and a generator, the model, that answers from it. The retriever decides whether it works. Term-based retrieval ranks documents by shared words: a term frequent in a document matters to it, and a term found in every document, like “for”, tells you nothing. That is TF-IDF. BM25 adds a normalization by document length, and an inverted index makes the lookup fast.

Embedding-based retrieval ranks by meaning. Chunks and query become vectors, and a nearest-neighbor index returns the closest k. It is built to tell “transformer architecture” from the electric device, and finetuning can push it past BM25. It costs more, and embedding can blur an exact token. The book’s example: an error code, EADDRNOTAVAIL (99).

Term-based versus embedding-based retrieval, read for code

CriterionTerm-based (BM25)Embedding-basedOn a codebase
Matches onThe query's exact termsThe query's meaningSymbols, paths and error strings are exact terms
Out of the boxStrong, hard to improveCan beat term-based with finetuninggrep finds the term, the model reads the hits and does the ranking
Exact tokensMatches EADDRNOTAVAIL (99) as typedCan blur itEvery identifier is an exact token
Cost to stay freshMuch cheaperRe-embed whatever changes; vector database spend can reach a fifth or even half of the model API billThe code changes on every edit
The term-based and embedding-based columns come from the book's comparison of retrieval algorithms, Table 6-2 and the text around it. The codebase column is my reading.

Production systems run both as hybrid search: a cheap term pass fetches candidates and a precise pass reranks them, or parallel retrievers merge their rankings with reciprocal rank fusion. Four tactics help the right chunk come back: chunking (recursive, language-aware, with overlap), reranking, query rewriting (so “How about Emily Doe?” stands alone) and contextual retrieval (tagging each chunk with entities like that error code, or with a 50 to 100 token note placing it in its document, as Anthropic did).

An AI judge can score context precision, the share of retrieved documents that are relevant, from the results alone. Context recall, the share of relevant documents retrieved, needs every document labeled against every test query, so some frameworks skip it. Beyond text, it covers images (CLIP) and tables (text-to-SQL, execute, generate).

Coding agents grep, and this chapter has the reasons

Code is made of exact tokens. Boris Cherny of Anthropic’s Claude Code team said on Latent Space in May 2025 that very early versions of Claude Code used RAG over an indexed codebase, and the team moved to agentic search: the model runs glob and grep as often as it needs. It did better internally and dropped an index that drifts out of sync and must be secured, at a cost in latency and tokens. In my logs, 31% of 16,156 shell commands read or search files. In the book’s terms, that is an agent whose tool is the retriever, minus the index. The book itself lists code copilots as a RAG use case and recommends hybrid search, so this is my reading of its mechanism, not its advice.

Huyen’s case for RAG over long context: data outgrows any window, long context is not always used well, and every token costs. She quotes Anthropic’s 2024 rule: under 200,000 tokens, put the whole knowledge base in the prompt. My average Claude Opus 5.5 call carried about 386,000 tokens. A coding agent does both: it retrieves on demand and keeps what it read in the window. The cost leg is weaker than chapter 6 makes it, and chapter 9 has the fix: with the prompt cache, an Opus 5.5 read bills $0.20 per million tokens against $4 fresh. The quality leg holds.

An agent is an environment, tools and a planner, and its errors compound

The agents half calls itself the book’s most experimental part and holds up best. An agent perceives an environment and acts on it, so the environment and its tools define it. SWE-agent, her coding example, has a terminal and a file system and can navigate, search, view and edit: the shape of Claude Code. Success rides on the tool inventory and the planner. The book mentions agent frameworks, and chapter 10 adds orchestrators, but it never treats the code that runs the loop and holds the permissions as a component of its own. That code is the harness.

Agents need stronger models because tools raise the stakes and mistakes compound: at 95% per step, 10 steps succeed 60% of the time and 100 steps 0.6%. In my logs, a turn I typed ran a median of 3 tool calls, 24 at the 90th percentile, 611 at most.

Chapter 6's arithmetic, at my 90th percentile turn

Chance the whole run is right

29%

With the check

89%
1 step
95%
10 steps
60%
100 steps
0.6%
100%0%1100 steps
At 95% per step, a 24-step turn is right 29% of the time. A check that catches 90% of each step's errors (an illustrative rate, not a measured one) lifts it to 89%. Set the check to 0 and push accuracy to 99%: a 100-step run still fails most of the time.

At 24 steps the arithmetic says an unchecked agent goes wrong 71% of the time. My interruption rate barely moves with turn length: 4.7% at 0 to 2 tool calls, 6.1% from 3 to 23, 6.2% at 24 or more. An interrupt is not a failure. But seven bad long turns in ten would have me stopping far more than one in sixteen. The check slider explains the gap: 24.9% of my shell commands are tests, lint or type checks, 29% with builds. The checks live inside the loop, so a wrong step becomes a red test the agent reads next, and the steps stop being independent coin flips.

Reads extend an agent, writes need a gate

Tools come in three kinds. Knowledge augmentation is retrievers, SQL, search and web browsing (choose those APIs carefully). Capability extension covers what models do badly, from a calculator to a code interpreter; Chameleon, GPT-4 with 13 tools, beat the best few-shot ScienceQA result by 11.37%. For write actions, the chapter’s line belongs next to every permissions file: “Just as you shouldn’t give an intern the authority to delete your production database, you shouldn’t allow an unreliable AI to initiate bank transfers.”

In a coding agent that split is the permission model: reads run, writes that leave the machine wait for approval. The browsing warning grew into prompt injection (chapter 5), and the harness is what stops it, with permissions, a sandbox and hooks.

Validate the plan before anything runs

The planning rule is to decouple planning from execution, so a 1,000-step plan that misses the goal never runs for hours on your bill. A heuristic (no missing tools, a step cap) or an AI judge validates the plan first. Humans can write, approve or run any step; set the level of automation per action. The book’s examples of a risky action are updating a database and merging a code change.

My ladder sets that level per rung: L2 approves every diff, L3 the pull request, L4 a gate. It breaks where the approval lives. In the four-tool comparison, all four kept the approval in the prompt, which is how one sentence of mine made BMAD skip it (chapter 5). A gate written as an instruction is one more instruction to weigh.

On whether LLMs can plan, the book answers LeCun’s no by treating planning as search, with backtracking by revision or restart, and bets that foundation-model and reinforcement-learning agents will merge. The bet aged well: DeepSeek-R1, weeks later, trained reasoning with reinforcement learning.

ReAct interleaves thought, action and observation. Reflexion separates an evaluator that scores the outcome from a module that explains the failure, as in code failing a third of its tests until the agent handles all-negative arrays. The book puts self-critique and a separate scorer side by side. Here I part with it: only the separate one closes a task. The agent’s own “done” closes nothing; chapter 3’s three review layers do.

Tool selection is experiment. Inventories run from Toolformer’s 5 tools to Gorilla’s 1,645 APIs, and every tool adds description tokens and makes the rest harder to pick. Drop any tool whose ablation costs nothing, rework the ones the agent misuses, merge tools your logs show running together often: the case for a shell over protocol servers. Voyager, a Minecraft agent, keeps programs that helped finish a task in a skill library and retrieves them later. The same idea shipped on October 16, 2025 as Anthropic’s Agent Skills, folders of instructions and scripts loaded on demand, and Voyager’s admission rule still applies to Claude skills: a skill enters the library after it worked.

Give every failure mode its own metric

Evaluation means listing how an agent fails and counting each. Planning fails on an invalid tool, invalid parameters, wrong values, or the goal itself, like a Hanoi trip that lands in Ho Chi Minh City. Then reflection error: “The agent is convinced that it’s accomplished a task when it hasn’t.” Asked to seat 50 people in 30 hotel rooms, it places 40 and insists it is done. Tools fail with wrong output, a bad translation or a missing tool.

Agent failure modes: the book's metric, and what catches each one in my setup

FailureThe book's metricWhat catches it in a coding agent
Invalid tool or parametersShare of valid tool calls; rate of each invalid typeThe harness validates the call and returns the error as the next observation
Wrong parameter valuesHow often valid tools get incorrect valuesTests and the type checker, run by the agent inside the turn
Goal failurePlanning-failure metrics on a (task, tool inventory) dataset, K plans per task: share valid, plans needed per valid oneAcceptance criteria written as checks
Convinced it is doneNone of its own; it sits under planning failurespnpm verify, then a person on the spec and the PR
Tool failureTest each tool alone; log every call and its outputThe session transcript, every call and output on disk
InefficiencySteps, cost and time per task and per action, against a baselineTool calls per turn (median 3, p90 24) and tokens per task
Middle column from the chapter's section on agent failure modes.

The FIFO trap is now the compaction trap

Memory has three layers: the weights hold internal knowledge, the context holds short-term memory, and external storage reached by retrieval holds long-term memory. Place information by how often it is needed: always in the weights, rarely in storage, right now in the context. The naive way to delete is FIFO, and the book warns that the earliest messages can carry the most information, especially when they state the goal. Summaries with entity tracking do better.

In a coding agent the layers are the model, the session and the files on disk: AGENTS.md, specs, task lists. Compaction is the book’s summary strategy with a milder FIFO trap: the goal from the first message survives as a line in a summary. A spec on disk is long-term memory. The summary never touches it, and the agent can read it again.

Where it aged: tool use before MCP and skills

Tool use is provider function calling with a hand-declared inventory. MCP, announced on November 25, 2024, nine days before O’Reilly released the book, is missing, and Agent Skills came ten months after it. The unit now is the harness (Claude Code, Codex, the open-source pi): one loop where the model reasons, calls a tool and reads the result, with the separate planner surviving as plan mode and spec files. Memory covers agents, but its deletion strategies are framed around conversations, with no instruction files and no compaction.

Free book · 169 pages · PDF + EPUB

AI Engineering says decouple planning from execution. The free book gives you that split as files your agent reads: requirements, design, tasks, and a gate you sign.

Get the free book

Chapter 7, Finetuning: fix the harness before you touch the weights

This chapter is about the one lever a hosted coding agent never hands you: the weights. Read it for the decision rule, the book’s best case for fixing an agent in the harness. Skim the memory math behind every small adapter.

Prompting comes first because a finetune ages faster than you can tune it

Huyen prices finetuning before she sells it. A finetune for one task can degrade the others, and it needs annotated data, training skills and a way to serve the result. Upkeep settles it: “These base models may improve faster than you can enhance your finetuned model.” Her domain example makes the same point: zero-shot GPT-4 beat BloombergGPT, a 50-billion-parameter finance model Bloomberg trained in-house and released the same month (March 2023), 76.48 against 43.41 accuracy on ConvFinQA.

The story practitioners keep telling her: someone insists prompting failed, and the experiments turn out unsystematic, with unclear instructions, unrepresentative examples and poorly defined metrics. So her order is the eval pipeline first, then versioned prompts, 1 to 50 examples, simple term-based retrieval like BM25, and only then a branch on what still fails.

Swap “finetune” for “a better model” and the story fits agents. So does the fix: an AGENTS.md that says what it means, a skill example from the real repo, a metric. Her retrieval advice already holds: my agent searches with grep, no vector database (chapter 6).

A facts failure is a context failure, and a form failure belongs to the harness

Her diagnosis: “In short, finetuning is for form, and RAG is for facts.” An information failure is a missing or outdated fact. A behavior failure is the right facts in the wrong output: irrelevant, malformed or unsafe. On current-events questions (Ovadia et al.), Mistral-7B scored 0.481 alone, 0.875 with retrieval and at best 0.588 finetuned. Her clearest case for finetuning is a syntax with few examples online, like a domain-specific language for a less popular tool.

For a coding agent, a facts failure is a context failure: the agent never opened the migration or the spec, and the fix is context engineering. A form failure belongs to the harness. I have never finetuned for an agent workflow. Every form problem I have hit was cheaper to fix with a skill, a hook or a linter. Even for the rare syntax, a parser in a hook rejects malformed output on every edit and hands the agent the error.

Diagnose the failure before you pick the fix

FailureChapter 7's fixThe coding agent fix
A fact is missing or outdatedRetrieval, term-based firstContext: put the file, the spec or the doc in front of the agent
Output in the wrong format or syntaxFinetune on the formatA linter or parser in a hook, run on every edit
Correct but irrelevant, or unsafeFinetune on good examplesA skill with the procedure, permissions for what must never happen
The rows are the book's split and the middle column its fix. The right column is where I fix each one, and none of it touches the weights.

Training needs several times the memory of inference, which is why LoRA exists

Inference holds the weights plus about 20% for activations and the KV cache (the stored attention state of earlier tokens, chapter 9): a 13B model at 2 bytes per parameter needs 31.2 GB in all. Training adds, for every trainable parameter, a gradient and the optimizer’s state. With Adam, the usual optimizer, that is three more values per trainable weight.

Why training needs more memory than inference

Chapter 7's formula. Fully finetuning a 7B model in 16 bits with Adam: 14 GB of weights plus 42 GB of gradients and optimizer states is 56 GB, before activations. Most consumer GPUs have 12 to 24 GB.

Quantization stores fewer bits per value: the same 13B model is 52 GB of weights in FP32 and 26 GB at 2 bytes. Parameter-efficient finetuning (PEFT) trains only a small share of the parameters. LoRA freezes a weight matrix and trains two thin matrices whose product is added back to it, and a rank of 4 to 64 is usually enough. On GPT-3 it matched full finetuning on several tasks while training 0.0027% of the parameters. Why so few suffice: papers she cites find pre-training leaves a model with a low intrinsic dimension, lower still in bigger models, so the better trained the model, the less it takes to steer it.

None of this reaches a hosted agent. If you self-host open weights, the math decides what fits, and the 20% rule breaks first: activation and KV memory grow with the context, and agent contexts are long (my average Opus call carried about 386,000 tokens). And evaluate the exact build you serve: teams that loaded Llama 2’s BF16 weights as FP16 got a worse model than advertised.

Merging stays in the weights, and its one agent pattern is misfiled

Merging combines several models’ parameters; ensembling combines their outputs, at the cost of more calls. It serves multi-task finetuning: train copies in parallel and merge, because training task after task makes a model forget the earlier ones. One item is misfiled: the book puts Together AI’s Mixture-of-Agents under layer stacking, but in the MoA paper each agent reads the previous layer’s outputs. That is an ensemble, the one pattern here a coding agent uses: a reviewer subagent buys a second opinion with extra calls, and its verdict stays advice.

Start with the strongest model you can afford

Test feasibility on the strongest model you can afford: if it fails, weaker ones will likely do worse, and if it passes, it becomes their benchmark. OpenAI’s progression path, which she cites (the cheapest model for the code, a mid-tier one for the data, the best to push), survives without the training: prove the task on the frontier model, then run a cheaper one on the same eval. The distillation path, training a cheap model on a strong one’s outputs, needs weights.

Caching retired the token argument, and RL changed the recipe

Finetuning used to save tokens: put the examples in the weights, send a shorter prompt. She concedes prompt caching weakened that. For a coding agent it is gone: 99.1% of my Opus input was read from cache (chapter 9 has the bill).

The bigger gap is the recipe. Post-training here is supervised plus preference finetuning, and reinforcement learning appears only to maximize human preference. DeepSeek-R1 (chapter 2) trained reasoning with reinforcement learning and reported its gains on tasks a program can check: math, coding competitions, STEM. Her warning that base models outrun a finetune reads stronger in October 2026.

Chapter 8, Dataset Engineering: your eval set is a dataset, so curate it like one

The chapter is for people building training sets. With coding agents you have none. You have a golden set, a rubric for the reviewer and a stream of agent output to check, and the rules fit all three. Its premise is data-centric AI: hold the model fixed and improve the data, the only mode a hosted agent leaves you.

Quality, coverage and quantity are the three tests for a golden set

LIMA finetuned Llama 65B on 1,000 curated examples, and annotators rated its answers equal to or better than GPT-4’s in 43% of cases. Of her six marks, the one to steal is alignment with the task, a word she chose over accuracy on purpose: a correct answer that runs long is a bad label when the task wants concise ones.

Chapter 8's six marks of quality, applied to an eval case

  • RelevantTaken from your own repos and requests
  • Aligned with the taskThe expected output is the one you want, which can differ from merely correct
  • ConsistentTwo reviewers would grade the case the same way
  • Correctly formattedFixtures in the shape the agent actually sees
  • Sufficiently uniqueNo case that paraphrases an example inside the skill or prompt it tests
  • CompliantNo secrets or customer data in the fixtures

Coverage means the data varies the way your users vary: long and short requests, typos, languages. Zhou et al. trained one 7B model on three 2,000-example sets, and only the diverse, high-quality one won. On quantity, start with about 50 good examples. If they show nothing, a bigger set rarely helps. If they help, train on 25%, 50% and 100% and read the slope.

For agent evals, start with 20 to 50 real cases from your own history, the source she ranks first, beginning with bugs caught in review. The optional idempotency key from chapter 4 is that kind of case: nobody would invent it at a desk. Coverage includes the times a skill should stay quiet, which is half of the 20 queries in how to test a Claude skill.

Annotation guidelines are evaluation guidelines

The hard part of annotation is the guideline. Can a response be correct and still unhelpful? What separates a 3 from a 4? Then the payoff: “The good news is that these guidelines are the same as those for evaluation data, as discussed in Chapter 4.”

For an implementing agent, the guideline is the spec’s acceptance criteria, like the 14 checks in chapter 4’s spec run. For a reviewer subagent, the guideline is the rubric, and if you cannot say what separates a 3 from a 4, its score is noise.

Kern et al. found annotations made late in a session are worse. Approving an agent’s diffs is annotation too, so the same fatigue applies: keep sessions short, and put the gate where you still read what you approve.

Generating data is cheap, and verifying it is the work

Synthesis comes from three places. Rules: a template filled by Faker, or a real example perturbed. Simulation: for tool use, run several action sequences and keep the most efficient. AI: paraphrase or translate real examples, or let models play against each other. Back-translation checks the result: translate the output back, and if it no longer matches the original, drop it. Llama 3 did that for code, turning a snippet into an explanation and the explanation back into code. Its pipeline for writing coding problems from scratch is the best case study:

Llama 3's coding-data pipeline, read as an agent loop

Input

AI writes a programming problem

  1. AISolve

    A solution per problem and language, with coding rules and step-by-step reasoning in the prompt

  2. linterParse and lint

    Catches syntax errors such as missing imports and uninitialized variables

  3. AI-writtenUnit tests

    Catches runtime errors

  4. feedbackRevise

    The model gets the problem, its failed solution and the linter and test output

  5. Gate:Filter

    Only examples that pass every check enter the dataset

Output

Over 2.7 million coding examples for Llama 3.1. About 20% of the solutions were wrong at first and fixed themselves.

Read as an agent loop, it is my L4 rung, where the agent plans, implements, evaluates itself and delivers at a gate. It is pnpm verify plus a retry (the agentic SDLC has the team version). People synthesize the data they can verify, she notes, so most of Llama 3’s synthetic data is code. Her summary: “It’s hard to automate data generation, but it’s even harder to automate verifying it.” Where no test exists, copy NVIDIA’s fix for judge bias: ask twice with the answer order swapped, and keep the verdict only if the same answer wins both times.

Let the agent write tests, and keep the grading tests out of its reach

Llama 3’s unit tests were AI-written too. For a training set that is a fair trade: a wrong test costs one example out of millions. In a repository, a wrong test ships a wrong feature, and the tests an agent writes for its own code inherit whatever it misunderstood. So let the agent write tests, and keep three things human: the spec, a held-out set of acceptance checks it never sees, and the rubric the reviewer grades against.

Model collapse is how a wiki the agent writes for itself drifts

Of her limits on synthetic data, collapse matters most to agents. Shumailov et al. trained models on their own output, generation after generation, and they degraded: probable events got over-represented, rare ones faded. Mixing real data back in seems to prevent it, though no paper she cites gives a safe ratio. Add lost lineage and you have the mechanism behind an LLM wiki the agent writes, reads back and writes from again. Pages drift toward the common pattern, rare facts fade, nobody can tell which page came from a source, and every page stays fluent. The fix: keep real data in the loop (the transcript, the commit) and the source on every page, which is what my LLM wiki rules do.

Skip distillation, steal the inspection and the dedupe

Distillation, training a small model on a big one’s outputs, needs weights, and many model licenses forbid it. Processing transfers. Inspect first: she says 15 minutes of staring at data usually saves her hours, and inspecting 28 days of my transcripts showed tool output at 54.8% of the characters and my own prompts at 1.9%. Then deduplicate. Exact copies fall to a hash. Near copies need a similarity check (n-gram overlap, fuzzy match or embeddings), or a hash like MinHash that only compares examples landing in the same bucket. Repeating 0.1% of the data 100 times dragged an 800M-parameter model to the level of a 400M one in an Anthropic study, and duplicates on both sides of a train and test split inflate the score. In a skill eval, a test query that paraphrases a training query flatters the description.

Chapter 9, Inference Optimization: a coding agent’s bill is a prompt cache problem

Most of chapter 9 is for people who run their own inference servers: chips, kernels, compilers, ways to split a model across GPUs. If you drive Claude Code against an API, you will touch none of it. Read it anyway. It explains, from the hardware up, why an agent’s call costs what it costs.

Prefill runs in parallel, decode runs one token at a time, and an agent is almost all prefill

A transformer answers in two phases. Prefill reads every input token at once, so the chip’s operations per second set its pace: it is compute-bound. Decode writes one token at a time, and each token means moving the model’s weights from high-bandwidth memory to the compute units. Little math, a lot of data movement, so decode is memory bandwidth-bound, and slow. The book’s example: a 7B model in 16-bit precision writing 100 tokens a second reads 7 billion weights at 2 bytes, 100 times a second. That is 1.4 TB/s, 70% of an A100’s 2 TB/s. The book prints 700 GB/s for that product, a slip; its 70% matches 1.4 TB/s. An Anyscale experiment it cites found that one output token weighs on latency like 100 input tokens.

A coding agent sits at the far end of that curve. In my logs, Opus 5.5 read about 390 input tokens for every token it wrote. Each call is a long prefill (tools, system prompt, AGENTS.md, every file and test log so far) ending in a short decode: a tool call or a small diff. Cost and wait follow the context it resends, and the lever that skips most of that prefill is the prompt cache.

Measure the token you wait for, in percentiles

Latency splits in two. Time to first token (TTFT) is the prefill, time per output token (TPOT) is the decode, and total latency is TTFT plus TPOT times the output length. When a model plans and calls tools before it answers, the first token it generates comes long before the first one you see, which some teams track as time to publish. For a coding agent, the token you wait for is the diff that passes the gate.

Read latency in percentiles: the book’s nine requests near 100 ms and one at 3,000 ms average 390 ms, a number that describes none of them. Throughput without a latency target misleads, so the book borrows goodput from networking: of 100 requests a minute, 30 met the target, so goodput is 30 a minute. For an agent, count the tasks that pass the gate inside their time and token budget. MFU and MBU are compute and bandwidth used, over peak. MFU exists because nvidia-smi reports a GPU 100% busy at one operation a second out of a hundred; MBU does the same job for memory bandwidth. The book’s three big numbers on a chip’s spec sheet are FLOP/s, memory size and memory bandwidth, and decode lives on bandwidth.

Online APIs optimize for latency. Batch APIs trade hours of turnaround for price: 50% off at OpenAI and Gemini when the book was written, 50% off at Anthropic today, on top of the cache discounts. An agent loop is online by definition, because the next call waits on this one’s tool result. An eval suite or a translation pass belongs in batch.

The model-level tricks you will never run still explain your agent

Model-level optimization changes the model, so it can change quality: Figure 9-8 shows the same Llama models scoring differently by provider. Weight-only quantization is by far the most popular (16 bits instead of 32 halves the memory, and one bit is the floor), distillation is common, and pruning is less common.

Three techniques attack one-token-at-a-time decoding. In speculative decoding, a small draft model proposes tokens and the target model verifies them in one parallel pass. Acceptance runs higher on code, and DeepMind’s 4B draft cut Chinchilla-70B’s latency by more than half. “Speculative decoding effectively turns the computation profile of decoding into that of prefilling.” Inference with reference copies spans from the input instead, with bug fixing as the book’s example and about twice the speed. Parallel decoding (Lookahead, Medusa) guesses several positions at once. A harness applies the copy idea one level up: Claude Code’s edit tool sends the text to replace and its replacement, so an edit never rewrites the whole file in output tokens. Those cost two to four times input in the book, and five times on Opus 5.5 ($4 against $20 per million).

The KV cache keeps the keys and values of every earlier token so decode never recomputes them. Attention compute grows with the square of the length. The cache grows linearly, from a large base:

KV cache memory, before any optimization (chapter 9)

The 2 is one key and one value per token per layer.

KV cache size

Llama 2 13B · 40 layers · 5,120 model dimension

Memory for the cache alone

53.7 GB

1 × 80 GB GPUs just to hold it

The book's own example: Llama 2 13B (40 layers, dimension 5,120), batch 32, 2,048 tokens, FP16 is about 54 GB. Drag the context to 386k, my average Opus call, with a batch of 1: about 316 GB, four 80 GB GPUs for the cache alone. Grouped-query attention is how modern models shrink it.

The fixes: attention designs that store fewer keys and values (multi-query and grouped-query attention, local windows, sharing across layers; Character.AI combined three of these to cut its cache more than 20 times), cache management like vLLM’s PagedAttention, and kernels like FlashAttention. A prompt cache, the book notes, takes memory the same way. Keep that in mind when your bill shows a write price and an expiry.

Batching and disaggregation are the provider’s job, and the cache is yours

Service-level optimization leaves the model alone. Static batching waits until every seat on the bus is full. Dynamic batching leaves when full or when a time window closes. Continuous batching (the Orca paper) returns each response the moment it ends and fills the seat, so a 10-token answer stops waiting on a 1,000-token one. Separate prefill and decode machines keep a new prefill from stealing compute from running decodes; for long inputs where TTFT matters, the book’s ratio is two to four prefill machines per decode machine. Agent traffic is exactly that. Parallelism (replica, tensor, pipeline, context, sequence) spreads big models across chips.

None of that is yours to run. The prompt cache is yours to keep. It stores the processed form of a shared prefix so the provider computes it once. “Without a prompt cache, your model needs to process the system prompt with every query.” The book’s arithmetic: a 1,000-token system prompt over a million daily calls is a billion repeated input tokens a day.

Every call resends the context, so the cache is the bill

A coding agent is that example at the limit. The API is stateless, so every call resends the whole conversation and adds a little at the end. My average Opus 5.5 call carried about 386,000 tokens: 18,772 Opus calls and 7.25 billion input tokens in 28 days, 99.1% read from the cache, every write at the 1-hour lifetime. At October 2026 list prices the cache turned $29,355 into $2,335, 12.6 times less. Most of those tokens are tool output, which is where agent tokens die.

The prompt cache bill (October 2026 list prices)

Without the cache

$29,356

With the cache

$2,329

The cache cuts the bill by 12.6×

Hits bill at the cached price, misses are written to the cache at the 1-hour rate (what Claude Code used in every one of my sessions), and output is one token per 390 input. Drop the hit rate from 99% to 90% and the bill on the same tokens is more than three times higher. The block's simplified model shows $2,329; my measured bill was $2,335.

The rules that set the hit rate live in Anthropic’s prompt caching docs and Claude Code’s own page, and the book has none of them. The cache is a prefix match: one changed byte invalidates everything after it. The prefix renders as tools, then system prompt, then messages. In the raw API, a tool change rebuilds everything and a system prompt edit spares only the tools. Claude Code keeps its tool definitions in the system prompt layer, so a change to either rebuilds the whole prefix. Its tool search keeps the tool list fixed for the session, so an MCP server that connects mid-session no longer breaks it. A model switch always starts from zero. A write costs 1.25 times base input at the 5-minute lifetime and twice base at the 1-hour lifetime. A read costs a tenth of base on Haiku 5.5, a twentieth on Opus 5.5 and Sonnet 5.5 and a fortieth on Fable 5.1, and it resets the timer for free. Of 23,927 calls across all Claude models in my logs, 169 missed:

What broke my cache in 28 days

CauseMissesWhy it breaks
Pause over 1 hour79The entry expired. 33.7M tokens rewritten at the 1-hour write price, about $270
Compaction56The harness replaced the history with a summary, so every message after the system prompt is new bytes
Other: tools, system prompt, edits27In Claude Code, a tool list or system prompt change rebuilds the whole prefix
Model switch5A cache belongs to one model. The new one starts from zero
Pause between 5 minutes and 1 hour2Inside the 1-hour lifetime, which every read resets. On the 5-minute default, a gap this long expires the entry
Claude Code main sessions, September 18 to October 16, 2026. 169 misses in 23,927 calls, and 76 compactions in the period.

The 1-hour lifetime is why pauses under an hour almost never cost me anything. Claude Code requests it by default only on a Claude subscription within plan usage. On an API key the default is five minutes, and setting promptCacheTtl to 1h raises it. The expensive miss is the long break: each of the 79 rebuilt about 427,000 tokens, roughly $3.40 at a time. Compaction rebuilds by design, trading one rewrite for room in the window. The rest is discipline: a fixed tool list inside a session, one more reason to keep the tool set small, and model changes only at a phase or subagent boundary, which is how a model-per-phase pipeline stays cheap.

Where it aged: the cache section stops at the promise

The caching pages are the most dated part of the chapter that still matters. They quote Anthropic’s 2024 promise of up to 90% savings and Gemini’s 75% discount plus an hourly storage fee, and say nothing about write prices, lifetimes or invalidation, the mechanics that decide an agent’s bill now. Even the promise undersells today. My Opus bill came out 92% lower, because an Opus 5.5 read costs a twentieth of the input price, and the 90% figure assumed a tenth.

The TPOT target is dated too: about 120 ms per token, a fast reader’s pace. Nobody reads an agent’s stream. Each decode step blocks the next tool call, and Anthropic sells faster Opus 5.5 output at double the price (fast mode, $8 and $40 per million). Your side of the book’s latency and cost trade-off depends on the rung. At L2 you wait on every turn. At L4 the cost per finished task is what counts.

Chapter 10, Architecture and User Feedback: read it backwards and you get a harness

This is one of the four chapters I would hand someone who starts with Claude Code tomorrow. It builds an AI application in five steps, each added when the design before it hits a wall. Then it treats users as the system’s best source of data, and shows how that data misleads.

Five steps, each one added to fix the last one’s problem

It starts with a query, a model and a response. Step 1 enhances context with retrieval and tools, chapter 6’s context construction.

Step 2 adds guardrails. Input guardrails keep private data from leaking to an external API and bad prompts from getting in. Her pattern for the first is worth copying: swap the sensitive value for a placeholder like [PHONE NUMBER], keep a reverse map, restore the value in the response. Output guardrails catch quality failures (broken format, hallucination) and security failures (toxicity, leaked data, responses that trigger tool or code execution), with a policy per failure. Retry, since the model is probabilistic. Send two calls in parallel to hide the retry’s latency. Hand off to a person after a set number of turns or when the user gets angry. Guardrails add latency, and streaming shows tokens before an output guardrail can judge them.

Step 3 adds a router and a gateway. The router is usually a small, fast intent classifier that picks the model, refuses out-of-scope queries and asks when one is ambiguous; for agents it becomes a next-action predictor. The gateway is one interface over many models, with access control (people get gateway access, never the company’s API keys), budgets, fallback when a provider fails, and logs.

Step 4 adds system caches. An exact cache returns a stored answer for an identical query. A semantic cache matches similar queries through embeddings and a threshold, and she calls its value dubious, because a wrong hit is a wrong answer. Her warning on exact caches: a personalized answer cached as generic serves one user’s data to the next.

Step 5 adds agent patterns: loops, branches, and write actions like sending an email or moving money, granted with the utmost care.

Read backwards, the five steps are the anatomy of a coding agent

She adds the agent last, the progression she says she commonly sees in production. With a coding agent, the loop is what you install on day one. Claude Code, Codex and the open-source pi ship it with partial versions of the other four steps, and your work runs the list in reverse. What an agent harness is names the same parts as loop, tools, context and controls.

Her five steps, read backwards as a coding agent harness

  1. 5

    Agent patterns and write actions

    The loop ships with the harness. What it may write is the rung: edit files, open the PR, deliver at a gate, deploy.

    L2 edits, L3 opens the PR, L4 a gate, L5 production
  2. 4

    Caches

    Her step caches responses, and an agent rarely sends the same request twice. The cache that matters is the provider's prompt cache, kept warm by a stable prefix.

    99.1% of my Opus input read from cache
  3. 3

    Router and gateway

    A model per phase, switched where the context starts fresh. The unified tool interface she left out is what MCP standardized.

    model per phase, one door for tools
  4. 2

    Guardrails

    Permissions, sandbox, and hooks that check a tool call before it runs. On the input side, the secrets the agent should never read.

    deny Read(./.env), PreToolUse hooks
  5. 1

    Context

    AGENTS.md, skills, the spec, the files it reads and what its tools print back.

    tool output: 54.8% of my transcripts
5 layers, each adding to the last.

The book misses two tensions. Her router sends easy queries to cheap models, and chapter 9’s cache belongs to one model, so every switch pays a rebuild. Her guardrail trade-off flips, too. A chat stream reaches the user before a guardrail reads it, while an agent’s tool call can be checked by a hook before it runs.

Her tool note aged the most. She leaves a tool gateway out as “not a common pattern as of this writing.” Anthropic announced MCP on November 25, 2024, days before O’Reilly released the book, and it made tools pluggable across harnesses. It also brought chapter 9’s cost along. Claude Code now defers MCP tool definitions until the agent needs one, but every connected server still adds its tool names and instructions to every call. My case for a shell over a protocol is the same arithmetic.

The orchestrator is the nearest thing to a harness in the book

An orchestrator, in her definition, declares the components (models, data sources, tools, evaluators) and chains them: function composition with a format check between steps. Start without a framework, she says, because it hides how the system works, and choose one later for integrations, branching, error handling and no hidden API calls. Same for a harness: if you cannot read what it sends, you cannot debug it.

A chain passes data along. A harness also runs the loop, holds the permissions and decides whether each step may run, the gap this review opened with. The book has every part and no name for what holds them together.

If you don’t know your change failure rate, the agent should not merge

Monitoring watches outputs. Observability instruments the system so that logs and metrics explain what went wrong without shipping new code. She grades it with three DevOps metrics: mean time to detection (MTTD), mean time to response (MTTR) and change failure rate (CFR), the share of changes that need a fix or a rollback. “If you don’t know your CFR, it’s time to redesign your platform to make it more observable.” Evaluation and monitoring are one loop: a failure found in production becomes an eval case.

Her practice transfers whole. Design metrics around the failure you fear. Break each one down by release, prompt version and time. Log everything: model, sampling settings, final prompt, every tool call and its output, with IDs. Read production data by hand every day. Trace each request with time and cost per step. Watch three drifts: the system prompt, user behavior, and the model behind an unchanged API (chapter 4’s Voiceflow case).

For a coding agent the drift list reads: an AGENTS.md or skill edit, a harness release that changes a system prompt you do not own, developers prompting differently, a model updated behind its name. Claude Code writes every session to a transcript on disk, her log-everything record, and the log numbers in this review come from mine.

What to measure on agent-authored changes

  • Required:
    Change failure rate of agent-authored changesThe share that needed a fix or a rollback, next to the human baseline
  • Required:
    Time to detect and time to respondMTTD and MTTR for incidents traced to an agent's change
  • Required:
    The versions behind every changeModel, harness, AGENTS.md and skills, so drift has a suspect
  • Optional:
    Interruptions and corrections per taskEarly termination and error correction, chapter 10's cheapest signals
  • Anti-pattern:
    Lines written or PRs opened per dayCounts output. Her rule is to design metrics around failures

A developer editing the agent’s diff is the strongest signal she names

Explicit feedback (thumbs, stars) is sparse and skews toward people who complain. Implicit feedback is abundant and noisy. Her conversational signals: early termination, error correction (a reply that opens with No or I meant), complaints, sentiment, regeneration, conversation length and dialogue diversity. In the FITS dataset she cites, the largest group, 26.54%, is users restating what they asked for. One signal she calls very strong: a user who corrects generated code is saying the code was not quite right, and each edit is a preference pair, the generated version losing to the edited one.

Collect it inside the workflow, she says: at onboarding, when something goes wrong, when the model is unsure. Copilot’s faded suggestion is her example, where Tab accepts and typing on rejects. Her complaint about chat apps is that ChatGPT cannot know whether the email it drafted was sent. A coding agent works in git, where whether its diff merged and stayed merged is on record.

Her signals, in a coding agent

Signal in chapter 10In a coding agentWhat it tells you
Early terminationEsc, or stopping the agent at a tool call5.4% of my turns (137 of 2,535)
Error correctionA reply that opens with No or I meantThe turn missed the intent
User edits the outputFixing the diff by hand before commitVery strong: the edited code was not quite right
RegenerationRerunning the taskWeaker: it can be curiosity
Conversation lengthTurns and tool calls per taskLong is bad in a productivity tool
Dialogue diversityThe same failing test, again and againA stuck loop
Was the output used?Merged, reverted, rolled backGit sees it. Chat apps cannot
Signals from chapter 10's feedback section, mapped to a Claude Code workflow. The interruption rate is from my 28 days of logs.

At L5 the feedback loop starts grading itself

Feedback carries biases: leniency (Uber’s average driver rating was 4.8 in 2015, and below 4.6 a driver risked deactivation), randomness, position, and a preference for the longer answer. Worse is the degenerate feedback loop she brings over from recommender systems. A system only gets feedback on what it showed, that feedback trains the next version, and a small bias grows until the app is all cat photos. Trained on human feedback, models drift toward sycophancy.

L5 runs from spec to production and back into the loop, which makes it a feedback system, and both failures show up in code. Agent-written tests grading agent-written code are a degenerate loop: the code passes the checks the same model thought of, and the criterion nobody wrote stays unchecked. An agent that folds whenever the reviewer pushes back is sycophancy aimed at the reviewer. What breaks both loops is a check the agent did not write and a judge it cannot flatter: acceptance tests written before it starts, and chapter 3’s review layers.

Her epilogue says the hardest part of technical writing is asking the right questions, not finding the answers. At L5 that is the job that stays with the person: setting the intent the agent works toward.

What aged since the book came out

The book went to print just before the agent tools it would have needed to describe.

What happened around the book

  1. Anthropic announces MCP

    Nine days before O'Reilly's first release. Not in the book.

  2. Done: AI Engineering ships

    First release on O'Reilly, paperback on January 7, 2025. Agents get about 25 pages, which she calls more experimental than the rest of the book.

  3. Claude Code launches

    As a research preview, under three months after the book.

  4. Mid 2025Context engineering becomes the word

    The book calls it context construction, in chapters 5, 6 and 10.

  5. Current: Nov 2025Chip Huyen's Coding with AI keynote

    Her newer thinking on coding agents, in a talk, not a book.

Claims to read with care in 2026

  • Optional:
    Tool use is plain function callingNo MCP and no Agent Skills. Multi-agent shows up as a planner, validator and executor, or as an actor with an evaluator
  • Optional:
    Post-training is supervised finetuning plus preference finetuningRL against checkable answers, the reasoning-model recipe since DeepSeek-R1 (January 2025), is not covered
  • Optional:
    Tool gateways are not a common patternMCP made a shared tool interface the standard
  • Anti-pattern:
    Claude 3.5 Sonnet has 70B parametersAnthropic never published a parameter count

What Chip Huyen says about coding agents now

The most useful thing Chip Huyen has said about coding agents is not in the book. In her Coding with AI keynote (Agents in Production, November 2025), she uses levels of coding automation that she borrowed from Graham Neubig, who borrowed them from self-driving cars, and says most work today sits between levels one and three. She says she has “not seen level four.” She borrows interruption rate from self-driving cars too, as the metric for how autonomous an agent really is: how often you have to take the wheel. She says she is very bullish on spec-driven development, and that developers avoid giving an agent more than about 20 tools.

Her scale runs from autocomplete at level one to full automation at level five, with level four as the AI doing everything except niche work like legacy systems or low-level CUDA. It is not the ladder I use, but both put the hard part near the top. She has not seen level four, and my L4 is where the agent must be trusted at a gate.

The ladder I use (her scale is a different one)

  1. L1

    Assisted

    The agent drafts and completes. The developer writes and decides everything.

    Where most developers started

  2. L2

    Supervised

    The agent changes files on request. A person reviews every diff.

    Chapter 5: the prompt is only input

  3. L3

    Pull request

    The agent takes a whole task, edits many files, opens the pull request. A person reviews the pull request.

    Chapter 6: checks in the loop, a plan gate

  4. L4

    Autonomous

    The agent plans, implements, grades itself and delivers behind an approval gate. A person approves at the gate.

    Chapter 4: the eval is the gate

  5. L5

    Full agentic

    From spec to production, re-entering the loop on its own. The human defines intent and is on call.

    Chapter 10: monitoring and feedback

5 levels, from the most basic (Assisted) to the most advanced (Full agentic).

So I measured my own interruption rate, the way she proposes, from the same logs: every turn I typed, and every turn I cut off before the agent finished, with Esc or by stopping it at a tool call.

My interruption rate, 28 days of Claude Code

turns interrupted
5.4%
137 of 2,535
interactive sessions
90
Sep 18 to Oct 16, 2026
sessions with at least one
43%
39 of 90
as the session goes on
Flat
6.2% in the first hour, 5.0% after three
One person, all my repos mixed. A turn is not a task. Esc also covers "stop, I changed my mind", and 53 messages typed while the agent kept running are not counted.

The line is flat: 6.2% of turns in the first hour, 5.0% after three hours. Two readings fit it. The agent does not get worse as the session grows, or I stop watching as closely. The number cannot tell them apart. Chapter 8’s finding on tired annotators makes the second plausible. In her talk, the rates she saw in other people’s logs ran from 0% to almost 30%, and up to 50% for some, though her unit may not be my turn. Interruption rate measures how often you take the wheel. It does not measure whether you should have. That is what the eval is for.

AI Engineering versus Designing Machine Learning Systems

The two books share an author and almost no chapters. Designing Machine Learning Systems (2022) is about training and serving your own models: features, data distribution shift, monitoring a model you built. AI Engineering is about adapting someone else’s model: prompts, context, evaluation, agents. The repo has a section on reading them together. If you build with coding agents and read only one, read AI Engineering. If you are choosing between it and Designing Data-Intensive Applications (second edition), they solve different problems: that one is about the systems your agent writes, this one is about the agent.

Frequently asked questions

Is AI Engineering by Chip Huyen worth it in 2026?

Yes, if you read it selectively. Chapters 4, 5, 6 and 10 (evaluation, prompts, agents, architecture) transfer directly to building with coding agents. The parts about training and hosting models matter only if you do that work.

Is AI Engineering outdated?

Partly. O'Reilly released it in December 2024 and the paperback followed on January 7, 2025, before Claude Code launched and without MCP, and it gives agents about 25 pages. Evaluation, compounding errors, prompt injection, prompt caching and the five-step architecture still hold.

Do I need a machine learning background to read it?

No. Chapter 2 and parts of chapters 7 to 9 are technical about models, and you can skim them. The chapters that matter most for coding agents need software engineering experience, not ML.

Is there a second edition of AI Engineering?

Not as of October 16, 2026. The first edition, from December 2024, is the current one. The author's newer thinking on coding agents is in talks, such as her Coding with AI keynote from November 2025.

How many pages does AI Engineering have?

532 pages in print, ten chapters plus an epilogue.

Is AI Engineering available in Portuguese or Spanish?

Yes. The Portuguese edition is Engenharia de IA (Novatec) and the Spanish edition is Ingeniería de IA (O'Reilly, May 2026). It has 13 translations.

Is there free official material from the book?

Yes. The companion repo chiphuyen/aie-book on GitHub has the table of contents, chapter summaries, study notes and resources. Her blog post on agents is adapted from chapter 6.

Does AI Engineering cover coding agents like Claude Code?

No. Coding appears as a use case in chapter 1, and agents get one section in chapter 6. The book predates Claude Code. Its evaluation, agent and caching chapters are still the best background for using one well.