Guides · Series · 12 parts
The Claude Code Engineering Playbook
Claude Code has four layers — context, skills, subagents, hooks — and the variable that decides which one you need is enforceability, not capability.
The common mistake is layer selection
Most teams that struggle with Claude Code are not misconfiguring it. They are reaching for the wrong layer. A workflow the agent keeps forgetting gets written as a longer prompt when it should be a skill. A policy that must hold every time gets written as a skill when it should be a hook. A task that pollutes the main session gets run inline when it should be a subagent.
The layers are not interchangeable and they are not a hierarchy of sophistication. They differ on one axis that matters more than any other: enforceability. A skill is a suggestion the model may follow. A hook is a gate it cannot see and cannot argue with. Confusing those two is where most production agent failures come from, because it produces a system whose safety guarantees are probabilistic while everyone believes they are absolute.
This playbook works through each layer, what it is genuinely for, and how to tell which one your problem needs.
Operating model, not configuration
The other half of the series is about running the thing. Context engineering determines whether the agent can do the task at all — prompt engineering tells the model what to do, context engineering decides whether it is equipped to. Subagents let you parallelise inside a session without poisoning the parent’s context. Observability is how you find out what actually happened, since most Claude Code failures leave no trace by default. Testing tells you whether your setup produces consistently good output, which skill-level evals cannot.
And when the human leaves the loop entirely — headless runs in CI — every safety net that depends on a person is gone: no approval, no rewind, nobody reading the output. What is left is exactly what you enforced in advance. That is the sharpest possible statement of the series’ argument, which is why it comes last.
Which part solves my problem
The series reads in order, but if something is already broken, start here.
- “The agent has the right instructions and still cannot do the task.”Part 1 →
- “I am re-teaching the agent the same workflow on every single call.”Part 2 →
- “One big exploratory task fills the context and derails everything after it.”Part 3 →
- “I told it never to do X in the prompt, and it did X.”Part 4 →
- “I do not know whether this problem needs a skill, a subagent, or a hook.”Part 5 →
- “My setup works but I am nowhere near the throughput I see other people getting.”Part 6 →
- “Something went wrong in a long session and there is no trace of why.”Part 7 →
- “My skills pass their evals and the output quality is still inconsistent.”Part 8 →
- “I cannot tell which of my guardrails are actually binding.”Part 9 →
- “I have been relying on /rewind as if it were version control.”Part 10 →
- “I want to run this in CI with no human watching it.”Part 11 →
The series
12 of 12 published
Context Engineering: The Skill That Separates Production Agents from Demos
Prompt engineering tells the model what to do. Context engineering determines whether it can actually do it.
Agent Skills Are Not Prompts. They Are Production Knowledge Infrastructure.
Every team is re-teaching their agent the same workflows on every call. Skills are how you stop paying that tax.
Subagents: How to Run Parallelism Inside a Single Agent Session Without Poisoning the Parent
Every subagent burns its own context so the parent doesn't have to. That's the entire architecture.
Hooks: The Enforcement Layer That Turns Agent Policy Into Agent Fact
Prompts suggest. Hooks enforce. Until you know the difference, your agent's safety guarantees are probabilistic.
Which Claude Code Layer Solves Your Problem? A Diagnostic Guide for AI Engineers
Reaching for a subagent when you needed a skill is the most common mistake teams make. Here is how to stop making it.
Four Habits from the Creator of Claude Code That Will Change How You Ship
Boris Cherny runs 10-15 parallel sessions, ships 20-30 PRs a day, and calls his setup 'surprisingly vanilla.' The gap is not configuration. It is operating model.
You Can't Debug What You Can't See: Observability for Claude Code Sessions
Most Claude Code failures leave no trace. Here is how to build the audit trail that tells you exactly what happened, why it went wrong, and how to stop it happening again.
How to Know Your Claude Code Setup Actually Works: Testing Beyond the Skill Level
Skill evals tell you a skill works in isolation. They do not tell you whether your agent produces consistently good code. That requires a different kind of test.
Skills vs Hooks in Claude Code: Enforceability Is the Design Variable
A skill is a suggestion the model may follow. A hook is a gate it cannot see and cannot argue with. Most production agent failures come from confusing the two.
Checkpoint Complacency: Claude Code /rewind vs Git Commits
Checkpointing feels like git. It covers a fraction of what git covers - and that gap is exactly where real work gets lost.
Headless Claude Code: When the Human Leaves the Loop, Hooks Are All You Have Left
Running Claude Code in CI strips away every safety net that needs a human - approval, rewind, reading the output. What's left is what you enforced in advance.
Claude Code Subagent Token Cost: The Preamble Never Stops
I measured 856 Claude Code subagent spawns. The preamble is not a one-time fee. It recurs on every turn, and it comes to about a quarter of the bill at every scale.
Other guide series
GenAI Architectures
There are eight architectures and seven boundaries between them. Every boundary is a yes-or-no question about the task — not a judgment call about the design.
Chat Templates
A chat template is the contract between your messages and the exact token stream the model was trained on. Get it wrong and nothing raises — the model just gets quietly worse.
Agentic AI with LangGraph
An eight-part guide to the part of agent engineering nobody demos: making the thing survive a restart, a concurrent write, a bad tool call, and a Tuesday deploy.
LangGraph Agent Evals
Every layer of an agent eval stack is a measuring instrument with its own error rate — the grader included — and none of them should gate a deploy until it has been scored against known faults.
Harness Engineering
AI systems do not fail at the model layer. They fail in the code around it — and that code is a designable layer with its own architecture.
RAG Engineering
Most RAG failures happen upstream of the LLM, accumulate invisibly, and only surface as an incident. This series names each one.
AI Control Plane
A fleet of agents needs a layer that is not itself an agent — observability, policy, orchestration, versioning, cost, and audit, built as infrastructure.
Agentic AI in the Data Center
In physical infrastructure, an agent’s autonomy is capped by reversibility and jurisdiction — not by how good the model is.
Codebase to Architecture Doc
A three-pass methodology for compressing any codebase into validated diagrams and decisions — and then a LangGraph pipeline that runs it for you.
Federated AI Agents
Every call that crosses from one owner to another is a seam, and a seam has five properties — contract, authority, state, failure, and accountability — that are free inside one deployment and have to be built across it.
