Claude Code Complete User Handbook
Listen
Radio episode about this paper
Transcript
Introduction to the show: ident: Computer Science. The day in computer science: software, systems and theory on arXiv.
Tom: We're looking at the paper: "Claude Code Complete User Handbook".
Title and authors: Jane: We’ve seen that the book is named the Claude Code Complete User Handbook, and it’s written by David Soldani. It’s presented as this verified practitioner's reference for agentic work, which is a big deal because it aims to be an actual operational guide rather than just theoretical talk.
Lu: The authors are framing this not just as a set of tips but as a system for building reliable workflows, emphasizing that capability isn't the constraint, but verification is >.
Tom: It’s about moving past the idea that you can just throw everything at an agent and expect it to work perfectly; this book is focused on establishing verifiable practices >.
Meng: I’m wondering how they handle the practicalities of setting up these controls, because in my experience, the setup phase is often where things fall apart if you don't get the permissions right initially >.
Lalam: They spend time detailing exactly how to install and verify credentials before you even start a project, which makes sense because getting authentication right is fundamental to any reliable system >.
Jane: So, this isn't just about writing good prompts; it’s about setting up the entire operating environment—the installation, the verification—to be robust from the beginning >.
Tom: It sounds like they are treating the setup process itself as a critical part of the work, not just a prerequisite hurdle to jump over >.
The paper's summary: Jane: Now that we know what it is, let’s look at what they actually summarize in terms of Claude Code Complete User Handbook. They boil down the core idea to this control stack—a four-layer model separating advisory guidance from the enforced control you have over the system >.
Lu: That separation is key because conflating those layers is what leads to losing control, so it’s like having a suggestion layered on top of a hard security rule, and that’s where most agents fail >.
Tom: So, the summary suggests that we need to be really careful about mixing advisory advice with actual enforcement mechanisms; that sounds like a necessary piece of engineering advice for anyone building these things >.
Meng: I'm curious about how they define those layers in practice, because if they’re too vague, it won't help me debug why my deployment keeps hitting unexpected errors >.
Lalam: They emphasize that permissions and sandboxing are distinct layers, not one big thing where you just turn a switch on and everything is controlled >.
Jane: And they tie this into the concept of the "four-element brief," which acts as an invariant structure for every single instruction or thread you have with Claude Code >.
Tom: That’s important because if you don't define that outcome, context, boundaries and evidence upfront, the system doesn't know what it’s trying to achieve >.
The paper's improvements: Jane: The paper also points out several ways they have improved the original concept of agentic work by suggesting specific mechanisms for better governance and delivery. They talk about evidence-gated delivery, which is their way of ensuring results are actually verifiable >.
Lu: Evidence-Gated Delivery is a method where you don't just accept an agent’s final statement as truth; instead, you go through an eight-stage process to produce deliverables based on actual evidence >.
Tom: That sounds like a very rigorous way to approach output; it forces the system to show its work and not just assert something it thinks is correct >.
Meng: From an engineering standpoint, that sounds like a good safeguard against hallucination or simply making up plausible-sounding answers when I need something concrete for production >.
Lalam: They also suggest treating external tools and skills—like plugins or MCP servers—as software supply-chain dependencies, which means you have to govern those just as carefully as your own code >.
Jane: And they talk about how to manage secrets and permissions with layered controls, like combining least privilege with permission deny rules and sandboxing credentials on top of that >.
Tom: So it’s not just one big fix; it’s a whole strategy for managing the entire lifecycle, from the initial brief to the final deployment gate >.
Conclusion: Jane: Wrapping up this discussion on the Claude Code Complete User Handbook, we see that these instructions are fundamentally about moving toward verifiable execution and clear system boundaries. The implication is that building reliable agentic work requires a deliberate structure from day one to manage the complexity of interacting with these powerful tools >.
Lu: I think the biggest shift they propose is realizing that the unit of trust in this kind of work isn't some closing statement from an agent, but rather observed evidence and documented controls >.
Tom: So, we’re moving from a system where we just supervise attention to one where we build explicit control stacks and demand measurable outcomes >.
Meng: For deployment, it means documenting the system and naming an accountable human before you even think about pushing anything live to production because that’s now a build-time concern >.
Lalam: It boils down to using things like `/usage` reports to track allocation and `/context` reports for window occupancy so we can measure the actual cost of running these agents >.
Jane: Exactly, so the final goal is to build a verified research-brief agent through eight stages, culminating in a human release gate where you have documented everything >.
Tom: So, remember that this whole framework—the four-element brief and the control stack—is the blueprint for operating safely and productively with Claude Code Complete User Handbook >.
David Soldani
cs.NI, cs.SE
Submitted: 2026-08-27
Updated: 2026-11-15
Comments: 258 pages, 34 chapters, 14 appendices, 7 figures, 51 tables, 117 references, 14 worked exercises. v2 is Version 1.1: re-verified against Claude Code 2.1.322 (12 Nov 2026), every chapter re-adjudicated; six new sections; six errata to Version 1.0 listed in the front matter. v1 was Version 1.0: baseline Claude Code 2.1.241 (23 Aug 2026), re-verified against 2.1.246 (26 Aug 2026)
License: http://creativecommons.org/licenses/by/4.0/
Importance score: 92/100
The gist: Claude Code is presented as an agentic work environment, a language model operating within a loop that integrates filesystem access, shell execution, browser control…
Key concepts
- Four-Element Brief
- This is the invariant structure for every agentic instruction. It requires defining the Outcome (what to achieve), Context (the background information), Boundaries (what is allowed/not allowed), and Evidence (how success will be measured). This prevents vague instructions from leading to uncontrolled execution.
- Agentic Control Stack
- A four-layer model separating advisory guidance from enforced control. Layer 1 is preference, while Layer 2 is permission rules. Conflating these layers is the primary cause of losing control over an agent's actions, ensuring clear separation between suggestion and mandate.
- Evidence-Gated Delivery
- An eight-stage method for producing verifiable deliverables based on evidence rather than mere assertion. This process ensures work is released only after meeting specific verification checkpoints, culminating in a human release gate before final deployment or publication.
Terminology
Summary
Claude Code is presented as an agentic work environment, a language model operating within a loop that integrates filesystem access, shell execution, browser control, scheduled and cloud execution capabilities, external tool connections via the Model Context Protocol (MCP), and multi-agent orchestration. p. 7 Interfaces, limits, plan entitlements and preview features change on a weekly cadence;
Appendix K states the re-verification procedure and should be run before this book is
relied upon for a consequential decision. Abstract
Claude Code is an agentic work environment: a language model operating in a loop with
filesystem access, shell execution, browser control, scheduled and cloud execution, external
tool connections through the Model Context Protocol, and multi-agent orchestration [2],
[3]. Abstract
Claude Code is an agentic work environment: a language model operating in a loop with
filesystem access, shell execution, browser control, scheduled and cloud execution, external
tool connections through the Model Context Protocol, and multi-agent orchestration [2],
[3]. Its capability envelope now exceeds what a single practitioner can supervise by
attention alone, and its failure modes are systemic rather than local: an unreviewed hook,
an over-scoped connector, a stale completion condition, an autonomous routine inheriting
every credential on an account. Abstract
Claude Code is an agentic work environment: a language model operating in a loop with
filesystem access, shell execution, browser control, scheduled and cloud execution, external
tool connections through the Model Context Protocol, and multi-agent orchestration [2],
[3]. Its capability envelope now exceeds what a single practitioner can supervise by
attention alone, and its failure modes are systemic rather than local: an unreviewed hook,
an over-scoped connector, a stale completion condition, an autonomous routine inheriting
every credential on an account.Where the paper says it
Where the paper says it
Where the paper says it
The book serves as a task-oriented reference for operating this system safely and productively by advancing four core propositions:
-
Productivity is not achieved without a defined and observable completion condition. p. 7
Where the paper says it
It advances four propositions. First, that capability without a defined and observable completion condition is not productivity.
-
Instruction, permission enforcement, sandboxing, and operating-system isolation constitute distinct layers of a control stack; conflating these layers is the primary cause of loss of control. p. 7
Where the paper says it
First, that capability without a defined and observable completion condition is not productivity. Second, that instruction, permission enforcement, sandboxing and operatingsystem isolation are four distinct layers of a control stack, only two of which are enforced, and that conflating them is the most common cause of loss of control.
-
Third-party skills, plugins, marketplaces, channels, and MCP servers must be governed as software supply-chain dependencies. p. 7
Where the paper says it
Second, that instruction, permission enforcement, sandboxing and operatingsystem isolation are four distinct layers of a control stack, only two of which are enforced, and that conflating them is the most common cause of loss of control. Third, that thirdparty skills, plugins, marketplaces, channels and MCP servers are software supply-chain dependencies and must be governed as such.
-
The correct unit of trust in agentic work is observed evidence rather than an agent’s closing statement. p. 7
Where the paper says it
Third, that thirdparty skills, plugins, marketplaces, channels and MCP servers are software supply-chain dependencies and must be governed as such. Fourth, that the correct unit of trust in agentic work is observed evidence, not an agent’s closing statement.
The scope covers Claude Code across various interfaces—terminal CLI, VS Code and JetBrains extensions, desktop application, web and mobile surfaces, and Remote Control—detailing extension mechanisms (MCP, skills, subagents), autonomy mechanisms (goals, workflows), and governance mechanisms (managed policy). p. 9 The book covers Claude Code as delivered through the terminal CLI, the VS
Code and JetBrains extensions, the desktop application, the web and mobile surfaces,
and Remote Control, at the verification baseline stated above. It covers the extension
mechanisms — MCP, skills, subagents, hooks, plugins, output styles — the autonomy
mechanisms — goals, workflows, three distinct schedulers, agent teams — and the
governance mechanisms — managed policy, data retention, telemetry and accessibility.Where the paper says it
The book is structured into four reading paths:
-
The essential path (Chapters 1–12): Guides the reader from installation to a controlled working method, focusing on bounded context projects with reviewed plans, enforced permissions, version control, and durable project knowledge.
-
The extension path (Chapters 13–19): Covers mechanisms that expand reach through connectors, secrets management, reusable procedures, delegated agents—and packaged plugins—with every chapter treated as a supply-chain consideration.
-
The autonomy path (Chapters 20–30): Addresses browser control, persistent goals, multi-agent workflows (including three distinct scheduling mechanisms), and remote/cloud execution.
-
The governance path (Chapters 31–33 and Appendices D, F, K): Targets readers accountable to external parties by detailing managed policy, data residency/retention rules, observability requirements, audit trails, and accessibility standards.
Key concepts introduced include the four-element brief
(Outcome, Context, Boundaries, Evidence) as the invariant structure for agentic instructions; the agentic control stack
(Figure 1), a four-layer model separating advisory guidance from enforced control; and Evidence-Gated Delivery
(Chapter 34), an eight-stage method for producing verifiable deliverables based on evidence rather than assertion.
The book emphasizes that capability is not the constraint, but verification is. p. 7 Its capability envelope now exceeds what a single practitioner can supervise by
attention alone, and its failure modes are systemic rather than local: an unreviewed hook,
an over-scoped connector, a stale completion condition, an autonomous routine inheriting
every credential on an account. This book is a task-oriented reference for operating that system safely and productively,
written for practitioners who are accountable for the result. Its capability envelope now exceeds what a single practitioner can supervise by
attention alone, and its failure modes are systemic rather than local: an unreviewed hook,
an over-scoped connector, a stale completion condition, an autonomous routine inheriting
every credential on an account. This book is a task-oriented reference for operating that system safely and productively,
written for practitioners who are accountable for the result.Where the paper says it
/usage reports (session cost, plan limits, activity), while context is monitored via /context. It stresses that A brief with headings makes omissions visible before they become incidents,
and that Queue a correction and it applies after the active tool call; press Esc only when it cannot wait.
The final goal is to build a verified research-brief agent through eight stages, culminating in a human release gate. Governance is now framed as a build-time concern, requiring documentation of the system, evidence of controls, and naming an accountable human. p. 7Where the paper says it
Green — the paper says it, and the page is printed. Red — no passage carries it, so treat that sentence as unverified. The same check runs on your own text: check a summary against its source, $5.
Improvements for AI systems
-
Make every statement of product behavior explicit by ensuring four elements are stated: Outcome, Context, Boundaries, and Evidence. This prevents
capability without a defined and observable completion condition
from becoming a productivity drain. -
Implement a four-layer control stack to clearly separate advisory guidance from enforced control, resolving the most common cause of loss of control by treating an instruction as a preference (Layer 1) versus a permission rule (Layer 2).
-
Establish an Evidence-Gated Delivery method with named gates for producing agentic deliverables, ensuring work is released on evidence rather than mere assertion.
-
Integrate raw-source adjudication and machine-checked apparatus to verify product claims against primary documentation, using an explicit UNVERIFIED class for claims that cannot be settled against documentation at the verification date.
-
Define a
four-element brief
(Outcome, Context, Boundaries, Evidence) as the invariant structure for every agentic instruction and thread it through the plan contract and release gate. -
Use /usage to measure allocation and /context to measure window occupancy separately to avoid conflating token quantity with actual context usage.
-
Structure CLAUDE.md modularly using path-scoped rules with frontmatter, ensuring instructions load only when relevant files are read, thereby reducing context cost by avoiding the loading of irrelevant information at launch.
-
Ensure that permission rules are evaluated in the order deny, then ask, then allow to prevent a broad deny rule from blocking a narrower allow rule and to avoid allowing exceptions for denies.
-
Enforce layered controls for secrets by combining least privilege with permission deny rules, sandbox credential controls (masking or denying), network restriction (deny curl/wget), and output discipline.
-
Require explicit human confirmation before any publication, payment, credential change, production deployment, destructive deletion, merge, or direct push to a protected branch as an operationalized Evidence-Gated Delivery principle.
Abstract
Claude Code is an agentic work environment: a language model operating in a loop with filesystem access, shell execution, browser control, scheduled and cloud execution, external tool connections through the Model Context Protocol, and multi-agent orchestration. Its capability envelope now exceeds what one practitioner can supervise by attention alone, and its failure modes are systemic rather than local: an unreviewed hook, an over-scoped connector, a stale completion condition, an autonomous routine inheriting every credential on an account. This book is a task-oriented reference for operating that system safely and productively, written for practitioners accountable for the result. It advances four propositions. First, capability without a defined and observable completion condition is not productivity. Second, instruction, permission enforcement, sandboxing and operating-system isolation are four distinct layers of a control stack, the first advisory and the other three enforced, and conflating them is the most common cause of loss of control. Third, third-party skills, plugins, marketplaces, channels and MCP servers are software supply-chain dependencies and must be governed as such. Fourth, the correct unit of trust in agentic work is observed evidence, not an agent's closing statement. Thirty-four chapters run from installation to a fully verified capstone, with a governance part on managed policy, data residency and retention, observability and accessibility. Every product claim carries a citation to a primary source; an evidence ledger records where a claim in circulation was found wrong, what a later re-verification changed, and what remains unverified. Controls are mapped to seventeen external frameworks in a crosswalk, and an organisational adoption maturity model is proposed. Claims not confirmable from primary sources are labelled UNVERIFIED rather than softened.
Sources
Related papers
- Predicting Networks Before They Happen: Experimentation on a Real-Time V2X Digital Twin
- MultiMoQ: Multi-Access Media-Over-QUIC for Robust Immersive Video Streaming
- HiFiNet: Hierarchical Fault Identification in Wireless Sensor Networks via Edge-Based Classification and Graph Aggregation
- Flux: Optimal Scheduling of Optical Circuit Switches for LLM Training
- Tutorial on Closed-Loop and Application-Aware Digital Twins for Future Wireless Networks
- Bringing dApps to OCUDU: An E3 Controller for Real-Time Open RAN Intelligence