PaperlayerView exact revision on arXiv

Source-linked AI summary

Claude Code Complete User Handbook

David Soldani

arXiv:2608.26742v1cs.NIcs.SE

TL;DR

The book covers remote and cloud operation, channels, artifacts, parallel sessions, agent teams, governance, observability, and a verified research-brief agent capstone.

  • Problem

    The book addresses the practical need to operate agentic work across distributed sessions, cloud sessions, channels, parallel sessions, and agent teams.

  • Method

    The book provides task-oriented chapters covering remote control, cloud sessions, channels, artifacts, parallel sessions, agent teams, governance, observability, and a capstone.

  • Results

    The book culminates in building a verified research-brief agent and includes chapters on data governance, observability, and accessibility.

  • Takeaways & Limitations

    Readers can use the book's coverage to address distributed operation, scaling, governance, observability, and verification tasks.

Abstract

from arXiv · show

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, only two of which are 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.

Part 0 — Superseded guidance and common misconceptions

This section lists later chapters covering distributed operation, cloud sessions, channels, artifacts, parallel sessions, agent teams, governance, observability, and a verified capstone.

  • Part VIII — Governance, assurance and compliance: Chapters 32 and 33 address data governance, residency, retention, observability, cost control, and accessibility.
  • Part IX — Capstone: Chapter 34 presents a verified research-brief agent as the capstone.
  • Part IX — Capstone: The closing perspective follows the capstone before the appendices and references.

I Glossary

This glossary-related material frames the handbook around verification, enforceable controls, observable evidence, explicit versioning, and stated limits on what documentation establishes.

  • Verification: Claude Code behaviour is verified against official documentation at a stated baseline and later release.
  • Control stack: The control stack distinguishes project instructions, permission rules, sandboxing, and managed policy by enforcement strength.
  • Evidence: Permission decisions, mode changes, connector connections, plugin loads, authentication events, and refusals are exportable through OpenTelemetry.
  • Scope limits: Documentation-based verification does not establish the behaviour of a running system across platform, plan, organisation, or implementation differences.
  • Verification limits: Claims that documentation cannot settle are labelled UNVERIFIED and paired with local checks.
  • Scope limits: The maturity model and exercises are author-proposed constructions without empirical validation or claimed external validity.

List of figures and tables

The figures and tables organize the handbook’s operating model: controls, context, delegation, workflows, scheduling, extensions, distributed operation, governance, verification, and adoption maturity.

  • Controls: Figure 1 separates the agentic control stack into product layers and operating-system layers.
  • Operating model: The figures map tool-call decisions, context persistence, untrusted-content entry points, delegation topologies, and research workflows.
  • Operating choices: The tables compare scheduling mechanisms, surfaces, permission modes, instruction locations, knowledge placement, and conversation-shaping mechanisms.
  • Extensions and automation: Additional tables cover MCP scopes, skill fields, subagent precedence, delegation mechanisms, plugins, output styles, workflows, loops, and scheduling.
  • Distributed operation and governance: Later figures and tables address channels, artifact constraints, parallel execution, managed policy, data flows, retention, exported metrics, framework mappings, corrections, and observed items.

Superseded guidance and common misconceptions

This section corrects widely circulated Claude Code guidance by distinguishing verified positions from superseded claims and directing readers to authoritative chapters and evidence records. It emphasizes that safe use requires bounded practice, observable execution, and a human release gate.

  • Claude Code changes weekly, and guidance written against an older release can invert the intended action.Twenty-one such claims were in wide circulation at the verification date.
  • The register pairs each common claim with its documented correction and the chapter that develops the verified position.Each entry also appears in Appendix J’s evidence ledger, generated from the same record.
  • The essential path establishes bounded context, reviewed plans, effective permissions, version control, and durable project knowledge before extensions or autonomy.The autonomy path asks how operators will know what the system did, while the governance path covers policy, retention, observability, audit, accessibility, and re-verification.
  • Chapter 34 combines the system into a verified deliverable accompanied by a release checklist.The worked workspace maintains an evidence ledger, uses independent review, renders an output, and stops at a human release gate.
  • Practice should begin in a disposable folder rather than a production repository or home directory.The examples use a non-programming Research Brief Workspace with separate source, draft, deliverable, policy, and configuration areas.

PART I · CHAPTER 1

Chapter 1 frames Claude Code as an agentic work environment whose broad capabilities require explicit outcomes, context, boundaries, and evidence. It introduces the control stack and recommends reversible first tasks that are cheap to inspect.

  • What Claude Code is, and what it is not: Claude Code inspects and edits files, executes tools, reaches configured services, publishes pages, schedules future turns, and delegates to other instances.The chapter distinguishes this agentic environment from a conventional chat interface or code-completion assistant.
  • What Claude Code is, and what it is not: The agent has broad tool access, variable judgement, no inherent knowledge of unstated intent, and a strong disposition to report success.The book treats the agent’s account of its own actions as the least reliable artefact it produces.
  • 1.1 Four things that must be explicit: Every instruction should state the Outcome, Context, Boundaries, and Evidence needed to check the result.These elements become the book’s brief, plan, machine-checked completion condition, and release checklist.
  • 1.4 Appropriate first tasks: First tasks should be reversible and cheap to inspect, while work touching accounts that cannot safely be altered should be avoided.Capability should expand only after verification habits do.

PART I · CHAPTER 2

Chapter 2 covers installation, verification, authentication, and platform trade-offs. It warns that installer behavior and feature availability depend on the installation path, operating system, and authentication method.

  • Install, verify and authenticate: Claude Code supports macOS 13+, specified Windows and Linux versions, at least 4 GB of RAM, network access, and a supported shell.A Pro, Max, Team, Enterprise, or Console account, or a configured cloud provider, is required.
  • Install, verify and authenticate: Sandboxing does not run on native Windows, while Chrome integration is unsupported under WSL.Windows-native projects and Linux toolchains therefore involve different feature trade-offs.
  • Install, verify and authenticate: The native installer auto-updates, whereas Homebrew and WinGet installations require explicit upgrades.Package-manager installations therefore have a different maintenance path from the official native installer.
  • Install, verify and authenticate: Verification consists of checking the version, running claude doctor, starting with the intended account, identifying update behavior, and knowing the authentication path.The installation itself should be treated as a configuration state to inspect before productive use.
  • Install, verify and authenticate: Chrome integration, artifacts, routines, cloud sessions, and teleport require a claude.ai subscription login and may be unavailable behind an API key.When a documented command is missing, the authentication path should be checked before the version.

PART I · CHAPTER 3

Claude Code treats the opened folder as a working boundary, not a security sandbox. Safe repository setup therefore requires deliberate boundary extension and controls for inherited monorepo instructions.

  • Boundaries: The opened folder is the default working boundary, but Claude Code can request directories, run commands, reach the network, and use connected services.Manual mode restricts writes inside the folder, while auto mode reads outside it without asking.
  • Boundaries: Never open a home directory as a project because a permission mistake could expose the entire personal filesystem.Trust acceptance there is session-only and reappears at every launch.
  • Monorepos: In monorepos, nested CLAUDE.md files from ancestor directories can introduce other teams’ instructions into the session.Use claudeMdExcludes, path-scoped rules, and per-package skills to keep guidance local.
  • Practice workflow: A safe practice task asks Claude Code to inspect the workspace without modifying it or accessing anything outside the folder.The worked response names only files inside the practice folder and proposes rather than performs changes.

PART I · CHAPTER 4

Claude Code’s model, effort, usage, and permission controls are independent and can vary by surface. Practical operation therefore depends on observing configuration-specific behavior rather than treating help text or effort as guarantees of safety or correctness.

  • Independent controls: Permission mode, model, effort, and output style are independent controls; changing one does not change the others.Effort changes deliberation, not what the system is permitted to do.
  • Surface differences: Effort vocabulary differs across surfaces, with ultracode and auto among the values whose availability or handling varies.Table 3 records observed acceptance by surface on Claude Code 2.1.246.
  • Verification: claude --effort auto is refused but falls back to default effort, so a script receives neither its requested setting nor a hard failure.ultracode is accepted by the flag even though claude --help does not list it.
  • Usage: /usage measures allocation and /context measures conversation occupancy; they answer different operational questions.Long sessions can increase usage superlinearly because each request carries accumulated history.
  • Optimisation: Optimise by removing irrelevant material, persisting durable outputs, bounding delegation, measuring integrations, and starting a clean session when the task changes.Verification should not be skipped merely to reduce cost.

A safe working method

Safe work with Claude Code makes objectives, inputs, boundaries, outputs, and completion evidence explicit, then steers execution and verifies the resulting evidence. Plan mode is especially useful for uncertain or consequential work, but approval does not replace permission controls.

  • Briefing: A structured brief specifies the objective, source scope, output file, boundaries, and a completion condition tied to named evidence.Headings make omissions visible before they become incidents.
  • Steering: Early steering checks whether Claude Code reads intended files, attempts unrequested external actions, interprets completion correctly, and delegates with an appropriate brief.Once direction is stable, continuous observation is unnecessary; unattended work needs tighter boundaries and stronger completion tests.
  • Interruption: Interruption stops current work but does not undo completed file changes or recall an external action.Inspect the diff or checkpoint state after interrupting.
  • Evidence: /export is the supported way to retain session evidence, whereas raw JSONL transcript format is internal and changes between releases.The exported transcript is preferable for audit retention.
  • Planning: Plan mode reduces uncertainty before edits and should identify outcomes, inputs, changes, steps, decisions, tests, side effects, and rollback.For reports, verification includes source coverage, link checks, spelling, and rendering; for software, it includes tests and behavioral observation.
  • Approval and verification: Approving a plan is not blanket permission for any method, because auto mode remains classifier-assisted rather than a sandbox or guarantee.Completion reports must distinguish checks that ran from checks merely described, followed by independent evidence inspection.
  • Controls: Permissions govern tool use, while prompts and CLAUDE.md influence attempts without granting or revoking access.Managed settings override other configuration levels, including command-line arguments.

PART III · CHAPTER 11

Engineer context as a deliberate, durable system: distinguish what reaches the current turn from what merely exists on disk, and preserve critical state across session operations. Treat context operations, project scope, permissions, and connectors as controls whose effects must be explicitly verified.

  • Engineer context deliberately: Context comprises prompts, tool descriptions, instructions, files, tool results, and history available in the current turn.A file on disk is not known merely because Claude could read it.
  • Engineer context deliberately: Durable findings, plans, decisions, and open questions belong in project files rather than conversation history.A conversation is a working surface, not a database.
  • Engineer context deliberately: A clean-session handoff should state the objective, completed work, approved decisions, open issues, file references, verification, and next safe action.Exclude conversational history that does not affect the task.
  • Engineer context deliberately: /compact is lossy, so explicitly preserve approved decisions, contradictions, file paths, verification results, and the human approval gate.It forces a summarisation request over the full history and invalidates the prompt cache.
  • Extending Claude Code: Project-scoped MCP servers require interactive approval, and trusted settings—not a cloned repository—control whether approval is enabled.This prevents a malicious pull request from silently connecting a server.
  • Environment variables and secrets: A .env file is not a security boundary: readable secrets can enter tool output, transcripts, or subprocesses despite instructions not to read them.Layer least privilege, deny rules, sandbox credential controls, network restriction, output discipline, git hygiene, and rotation, then test the controls.

PART IV · CHAPTER 17

Claude Code’s automation mechanisms span deterministic hooks, output-style customization, browser staging, completion evaluation, effort controls, workflow replay, scheduling, and monitors. Safe operation depends on understanding each mechanism’s trigger, authority, limits, and failure behavior.

  • Hooks: Hooks run configured actions at lifecycle events, with handlers for commands, HTTP, MCP tools, prompts, and agents.Events include prompt submission, tool calls, permission requests, configuration changes, session boundaries, and post-tool outcomes.
  • Hooks: PreToolUse hooks can block calls, but permission rules still override hook approvals; exiting 2 stops evaluation before permission rules.This supports allowing Bash broadly while blocking narrowly matched destructive commands.
  • Output styles: Output styles change Claude Code’s role, tone, and response format, and can remove its built-in software-engineering instructions.They are suited to research, operations, analysis, and writing tasks.
  • Browser control: Browser automation shares authenticated browser state, so safe staging should progress from observation through verification before human-controlled submission.Plan mode permits read-only browser calls while prompting for state-changing ones, and web pages remain untrusted input.
  • Completion conditions: Completion evaluators inspect only what Claude surfaced, so conditions should specify deliverables, checks, evidence, exclusions, and bounds.Goals do not alter permission modes, background work defers evaluation, and /goal is disabled by certain hook settings.
  • Autonomous execution: Scheduled and delegated work has explicit operational limits: workflows replay unfinished fan-outs, schedules require an idle running client, and monitors stream output without polling.Resume is session-bound; scheduling includes jitter, no catch-up, seven-day expiry, and a fifty-task session limit.

PART V · CHAPTER 24

Choose among three non-interchangeable scheduling mechanisms by what must already be true when work runs, especially machine availability and access to local files or software. Cloud routines run autonomously, so their connectors, identity, permissions, payload handling, failure signals and operating limits require explicit design review.

  • Choosing a mechanism: Three scheduling mechanisms are not interchangeable; choose based on the conditions that must hold when the work runs.The decision begins with runtime requirements rather than frequency.
  • Cloud routines: Routine triggers include schedules, API calls and filtered GitHub events, and a single routine can combine all three.Scheduled options range from hourly to a single future timestamp; API firing uses a per-routine endpoint with a bearer token.
  • Cloud routines: A cloud routine runs autonomously with all connected connectors included by default and can perform writes under the user's linked accounts.Routine design should remove unnecessary connectors and use least-privilege accounts.
  • Cloud routines: API-triggered or manually fired text is wrapped as untrusted data and remains inert unless the routine prompt explicitly opts into using it.The wrapper is intended to reduce injection risk when someone holding the bearer token supplies text.
  • Verification: A green routine status means only that the session started and exited without infrastructure error, not that the task succeeded.Blocked requests, missing tools and task failures appear in the transcript, so inspect runs rather than trusting the status indicator.
  • Desktop scheduled tasks: A local scheduler invoking headless Claude Code is a separately secured system, requiring explicit controls for identity, directory, permissions, logging, retries, cost and trust verification.It is not equivalent to a built-in scheduling feature.

Governance, assurance and compliance

Governance turns agentic operation into an accountable control system by separating enforceable policy from advice, connecting controls to evidence, and defining verification before release. It also makes data handling, observability, retention, and organisational boundaries explicit.

  • Enterprise configuration and managed policy: Managed settings are the only policy tier users cannot unset, but multiple managed sources can be silently skipped when a higher-priority source supplies a policy key.Cloud sessions require server-managed settings because they do not read device MDM profiles or files.
  • Data governance: Data governance must distinguish training terms, provider-specific encryption, local transcript caching, retention periods, and flows covered by Zero Data Retention.Local transcripts are plaintext by default, and auto memory is outside the cleanup sweep.
  • Observability: OpenTelemetry exports metrics, logs, and beta traces with prompt identifiers that allow an instruction’s activity to be reconstructed for assurance review.Content logging is disabled by default; enabling it places prompts and code in the telemetry pipeline and changes its classification, retention, and access requirements.
  • Assurance and release: Evidence-Gated Delivery requires an inspectable result, independent review, visible disagreements, tested failure paths, removal procedures, and verification rather than reliance on an agent’s completion statement.The capstone is complete when the evidence exists, not when Claude says it is complete.
  • Adoption principles: Governance is a build-time concern because managed policy, retention, residency, audit, and accessibility each have precedence orders, failure modes, and gaps.The book’s practical guidance is to start small, add autonomy only with defined completion and failure conditions, and verify the artefact rather than the final message.

APPENDIX B

The appendices provide operational reference material for interfaces, configuration locations, managed controls, security settings, telemetry, retention, and evidence-based completion. They emphasize checking precedence, scope, and observable evidence rather than relying on defaults or instructions alone.

  • CLI reference: Claude Code exposes interactive commands, subcommands, and flags whose documented availability and accepted values require version- and interface-specific checking.Some flags appear only inside other descriptions, while --effort accepts values beyond those enumerated by --help.
  • Files and configuration: Project, user, managed, MCP, plugin, hook, transcript, memory, team, channel, and instruction files occupy distinct paths with different review and commit expectations.Managed instruction content cannot be excluded, while auto memory is excluded from the retention sweep.
  • Precedence: Managed settings outrank command-line, project, and user settings, while permission rules independently evaluate deny, ask, then allow.No level, including command-line arguments, overrides a managed permission rule.
  • Readiness and assurance: Operational readiness requires a narrow working directory, clean baseline, least-privilege permissions, tested denies, sandboxing, protected credentials, reviewed third-party components, and evidence-based completion conditions.The appendices frame completion as an evidence requirement rather than an assertion.

APPENDIX G

The troubleshooting and reference appendices map common symptoms to likely causes and safe checks across authentication, scope, configuration, MCP, delegation, scheduling, concurrency, cloud execution, artifacts, and governance. They also connect operational controls to external frameworks while marking unsupported mappings as unverified.

  • First checks: Safe troubleshooting checks authentication path, working directory, settings source, session reload, MCP state, and feature availability before changing configuration.Some documented features silently disappear when API credentials take precedence over a claude.ai login.
  • Instructions and delegation: Configuration symptoms often arise from scope, caching, precedence, unmatched path rules, or parent permission modes rather than from the instruction or agent definition itself.Instructions are read at session start, conversation-only instructions can disappear after compaction, and parent modes can override reviewer behavior.
  • Automation and concurrency: Automation and parallelism require explicit safeguards because loops can miss intervals, sessions can collide, routines can succeed without doing the intended work, and cloud runs cannot reach local software.Use durable scheduling when timing matters, separate writers with worktrees, and inspect transcripts and artifacts.
  • Framework mapping: The framework crosswalk is an assurance starting point rather than a certification claim, and a present control is not evidence that it is effective.ISO/IEC 27001:2022 Annex A identifiers remain unverified because only secondary summaries were available.
  • Definitions and verification: The reference material defines agentic concepts and records verification status, including confirmed sources, unresolved standards details, and changes such as the OWASP GenAI Security Project’s 2026 edition.These records preserve uncertainty instead of implying that every cited detail was verified.

Corrections applied at re-verification

The re-verification process corrected release-specific claims, closed some installation-specific uncertainties, and retained explicit boundaries around documentation, version drift, and unverified behavior. It also established that help output can under-report accepted values, so omissions are not refusals without observed rejection.

  • Corrections applied at re-verification: A 26 August 2026 re-verification against Claude Code 2.1.246 changed statements where the earlier adjudication differed or omitted conditions.Each change was checked against the raw text of the governing documentation page.
  • Corrections applied at re-verification: Three previously UNVERIFIED items were settled by direct observation, but each verdict applies only to one configuration, date, and named surface.Behavior outside those observations remains open.
  • Corrections applied at re-verification: A zero delta across two releases showed that the claude --help flag surface did not move during the compared interval.The comparison records stability relevant to later re-verification.
  • Corrections applied at re-verification: The product accepted ultracode for --effort and default for --permission-mode even though the corresponding help or error enumerations omitted those values.The second omission was explained by manual being a documented alias for default in later releases.
  • Corrections applied at re-verification: An unlisted value is treated as unestablished rather than refused unless refusal itself was observed, as with claude --effort auto.The rule is stated for the specific surface on which the values were observed.
  • Corrections applied at re-verification: The book retains UNVERIFIED claims because documented behavior can diverge from running installations across platforms, plans, organizations, and flags.Three installation-dependent items remained open at the release, and later behavior may change as Claude Code evolves weekly.

Chapter 11 — a handoff that survives a clean session

The handoff exercise tests whether a clean session can recover working state from a structured artifact rather than from the old transcript. Its broader exercises apply the same discipline to connections, skills, workflows, and verification: preserve boundaries, expose assumptions, compare decision value, and check reality outside the conversation.

  • Handoff design: The handoff records goal, completed and remaining work, open decisions, rejected approaches, the next check, and active boundaries.It omits history so the new session receives what is true rather than what happened.
  • Handoff design: Item 5 prevents a clean session from re-proposing rejected approaches, while restating boundaries keeps constraints from remaining only in the old transcript.The exercise therefore treats omissions as failures in the handoff itself.
  • Handoff verification: The clean session must independently identify completed work and its evidence, the blocking decision, and the next check with its expected proof.Any answer requiring supplied information reveals a missing handoff section.
  • Connection governance: A connection threat model must distinguish documented facts from assumptions about reachable data, writes, credentials, scope, approvals, logging, and revocation.Rows unsupported by provider documentation remain assumptions rather than being filled by inference.
  • Connection governance: An MCP server is both a capability and an injection surface because its tool descriptions and returned content reach the model.Approval depends especially on resolving scope, write operations, and revocation.
  • Workflow evaluation: Only a changed decision demonstrates workflow value; better organization of the same conclusion, especially at several times the cost, adds confidence rather than decision value.The comparison pairs multi-agent and single-agent outputs under the same requirements.
  • Evidence-gated completion: Eight of thirteen exercise solutions require verification outside the transcript because reported completion can differ from filesystem, browser, git, settings, or artefact reality.The external check is the basis for deciding whether the work is complete.
Loading 2608.26742v1…