Claude Code
From first steps to work that holds up

How to use this guide and demonstrate progress

This is a progressive reference for working with Claude Code. It starts with readers unfamiliar with a terminal and reaches extension, integration, evaluation, and operating decisions. Zero to Hero means demonstrable skills here, not a promise that reading alone creates a software engineer.

Three teaching examples connect the material: a small service-quote calculator, a private WordPress request, and an assistant reviewing a campaign brief. Fictional examples are labeled; they are not claims about client results or a launched SaaS.

For each chapter, understand the concept, try the relevant example in a demonstration project, and record evidence. If you cannot explain the result, revisit the underlying idea before expanding the project.

Availability can vary by build, account, provider, interface, and organization policy. Review reference files before copying them. Running a local example is distinct from verifying live Claude account integration.

Projects files paths and the command line

A project is a collection of files serving a purpose. A file is a named unit of content; a folder groups files; a path identifies a location. src/quote.mjs is relative to a working directory. An absolute path identifies a location from the filesystem or drive root.

A terminal hosts command interaction. A shell, such as PowerShell or Bash, interprets commands. A CLI is a program’s command interface, such as claude. An IDE, such as VS Code, combines editing and development tools. The Claude Code editor panel and the editor’s integrated terminal are different interfaces.

cd changes the working directory. Starting in the wrong directory can expose a different project or miss its settings. Know the folder and its contents before starting. Windows and Bash paths do not always share the same syntax.

package.json describes a JavaScript project and its scripts. A dependency is another library the project uses. Installing the coding assistant is different from installing an application’s dependencies. A runtime executes code; Node.js runs JavaScript outside the browser.

Practice: create an empty demonstration folder, open its terminal, and request a file inventory before changes. Explain the difference between the program executing a command, its working directory, and the files it will change.

Models tokens context and the agent loop

The model generates decisions and responses. Claude Code supplies the working environment around it: tools, context management, and an agentic loop. Harness is the useful English term for this surrounding runtime. Translating it literally as a strap loses the technical meaning.

Goal: add a service quote calculator
Check: the expected result for a known input

Think of a task as a feedback loop: inspect relevant material, choose an action, observe what actually happened, and check the result. If an action fails, the next step should respond to the evidence.

In BriefDesk, an agent may inspect the calculator, run a failing check, patch validation, and run the check again. The important artifact is the verified behavior and its supporting files. The number of tool calls is secondary.

A useful diagnostic: If the same task fails repeatedly, ask whether the missing piece is a business rule, a file, an execution tool, an acceptance check, or model capability. Switching models is one possible response; it does not replace finding the missing piece.

Read on: The next chapter explains how to supply the smallest useful body of context without turning every request into a document dump.

An LLM generates outputs from available input. Inference runs a model on a request; including a file does not retrain the model on it. A token is a processing unit, not a fixed word, and language or content changes the ratio.

A tool call is a structured request with a name, input, and result. A file read returns content; a test command returns evidence. Results enter the working context and inform the next action. This is an educational model of observable behavior, not a disclosure of private model reasoning.

Repeated requests can vary. Verify application behavior through independent checks, and repeat task evaluations when language quality matters.

Install it and make one controlled first move

Use the official installer for your operating system. These commands install software on your own machine; read the official setup page if your organization manages installations.

macOS, Linux, or WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Then open a fresh terminal, check the installation, and enter your project.

claude --version
claude doctor
cd your-project
claude

Native installation does not require Node.js merely to launch Claude Code. Our optional JavaScript demo and hook do require Node.js. On Windows, distinguish PowerShell from CMD and from WSL; commands and paths are not interchangeable. Git for Windows is recommended for Bash access; current documentation describes a PowerShell fallback when it is absent.

For the first session, ask: “Map this project. Explain its entry points, how to run its checks, and where the quote rule belongs. Do not modify files.” Read the response against the actual files.

Check which account and billing route you are using. Access, limits, and organization controls vary. Avoid starting with a production server or a folder containing unrelated client exports.

Finish this chapter when: you can identify the working folder, installed version, and one existing project check. Installing ten extensions is not a prerequisite.

Interfaces your first session and essential commands

Claude Code runs in the terminal, editors, Desktop, and the web. Interface choice does not make execution environments identical. A local session operates on your machine; a cloud session has its own files, setup, and network. Begin with one route and identify the copy being changed.

Ask the first session to explain purpose, entry point, run command, and checks without editing. An entry point is where execution begins: perhaps an HTML page, a server route, or a script. Do not infer its location from the technology name alone.

Slash commands belong inside a session; claude ... commands run from the shell. If something is missing, check build, interface, and configuration before assuming an old reference applies.

Remote work and visual checks: controlling an existing local session differs from running an independent cloud copy. Identify machine, files, and identity in each case. Browser tools, where available, can exercise pages and inspect interface errors; backend and data checks still depend on the task. GitHub or CI integration introduces additional effects, configuration, and billing scope.

Write a task contract before a long prompt

A useful prompt states what must become true, what evidence exists, and where discretion ends. The following is an original teaching template, not a special Claude command.

Goal: Add a quote preview to the local demo.
User: A service-business owner reviewing a request.
Inputs: Quantity, approved unit price, setup fee.
Constraints: Use integer halala; do not invent prices.
Acceptance: Invalid inputs are rejected; the total is reproducible.
Evidence: List changed files, checks run, and remaining limitations.
First inspect the existing project. Change only what this task needs.

For a WordPress project, replace the quote goal with: “A visitor can submit a request, an authorized manager can read it, and another visitor cannot.” For a marketing task: “Produce three draft angles using only the approved offer, and mark missing evidence.”

Ask a question when the answer would change implementation, price, permissions, or acceptance. Routine details can use stated assumptions. Requiring a question before every small action can interrupt useful work without improving the result.

A practical completion report has four parts: what changed, what was checked, what remains uncertain, and what decision the evidence supports. This keeps a polished closing message from standing in for verification.

Exercise: Take “make the landing page better” and name one user, one desired action, one constraint, and one check. If you cannot choose a check, inspect the business problem before rebuilding the page.

Separate intent, context, constraints, and acceptance criteria. Identify the source of business facts. A request to write an offer differs from a request to use approved prices and flag missing information.

Structured output follows a schema such as JSON. Valid structure does not establish correct values: a valid price: 100 can still be unsupported. Check source and value separately from formatting.

Solved exercise: “Improve the form” becomes “Reject a missing title, show an Arabic explanation, retain entered fields, and demonstrate valid and empty cases.” The change now has a boundary and an observable check.

Planning architecture and task boundaries

Architecture distributes responsibilities, data, and connections across a system. A plan explains what changes, why, what waits, and how to verify the effect. File size or count alone does not establish sound architecture.

Use Plan mode when exploration and a decision should precede implementation. A narrow repair may need only a focused inspection, change, and check. Match planning effort to the consequences of the work.

Split a request tool into a small vertical journey: valid input → validation → persistence → authorized display. Add notification afterward. This exposes frontend, backend, and storage relationships early.

An ADR, architecture decision record, captures the problem, choice, alternatives, consequences, and review trigger. Example: local storage serves a one-person prototype; team sharing will require a different storage and access design.

Record dependencies. A schema change may precede its screen. Two tasks editing the same function do not become independent merely because different agents receive them.

Check: explain where the calculation rule, display, and approved price live. Putting all three into a prompt can make stable rules harder to change and test.

Understand web code and data without memorizing it all

HTML describes content and elements; CSS appearance; JavaScript behavior. The frontend is the user-facing part. The backend handles server-side rules, access, and data. PHP is commonly used with WordPress and Laravel; SQL works with databases.

A button may send an HTTP request to an endpoint and receive a response. An API defines a software interaction contract. REST is a common style for HTTP interfaces, not a particular service.

For example, the browser sends a quantity, the server validates it, calculates from approved rules, and returns a total. Browser validation supports usability; server validation enforces the rule when the interface is bypassed.

Authentication establishes identity. Authorization defines what that identity may do. Logging in does not authorize access to another user’s request. This distinction applies to client sites, marketing tools, and SaaS.

Ask Claude Code to trace one input from field to result with file references. Change a small rule in the demonstration project and check it again. You learn the code you depend on by connecting it to behavior.

The money example uses integer halala for teaching. Real tax, rounding, discount, and production rules require explicit domain definitions; the example is not a print-business pricing policy.

Git diffs sessions and recovery

A repository holds files and their history. A branch is a line of work, a commit a recorded point, and a diff a description of changes. Inspect files and values before recording them; later exclusion does not automatically erase a secret from history.

git status
git diff

Read the diff as a decision: did it change the requested behavior only? Did an unexpected dependency or setting appear? Request an explanation, then run the relevant checks. A universal 300-line rule does not replace understanding responsibilities.

A session preserves conversation context; a repository preserves code history. Resuming a conversation does not restore a database or recall a sent message. Rewind has a defined tracking scope; version control and recovery procedures still matter.

Before handing off, record objective, decisions, files, checks, and next action. Use /resume for a conversation and /clear for a genuinely new context after preserving what is needed.

Practice: record a working demonstration version, make a small change, inspect it, and rehearse an appropriate recovery. Understand what a reset or deletion would remove before using it.

Debug the behavior and prove the repair

Suppose a request appears twice in the dashboard. “Please fix it” gives little guidance about the trigger. Start with the smallest reproduction: one submit, one retry, two records. Look for event duplication, a retry without an idempotency key, or a second persistence path.

Reproduce the duplicate-request bug with the smallest available example.
Identify where the second write is triggered. Propose a narrow fix,
then verify that a repeated request does not create a second record.
Do not change unrelated screens or replace the existing architecture.

Separate the explanation from the check. A plausible story about the bug still needs a reproduction and a result after the change. Keep a regression case when it protects a meaningful behavior.

In the included calculator, tests cover a valid total, missing quantity, negative input, fractional minor units, and an unsafe total. The business rule is deterministic. It does not need a model to decide the answer.

For WordPress, test the entire request journey as well as the private-data boundary. For a marketing utility, test a stale offer and an unsupported claim. Choose checks according to consequences rather than generating a large test file that repeats implementation.

Reader challenge: deliberately break one validation rule in the local demo. Which check catches it? If none does, add a check that describes the required behavior before repairing the code.

A unit test checks a small rule, an integration test checks components together, and an end-to-end test follows a user journey. Choose the type from the behavior to protect. Correct arithmetic alone does not prove persistence or access isolation.

The included local example expects quantity 100 × unit price 150 halala + setup 1000 halala = 16000 halala. The expected result is independently checkable. Preserve failing input, error, and version when diagnosing a defect.

Give context a job and memory a review date

Context is the working material available for a request. Memory is a way to carry selected information between work sessions. Neither should be treated as an unquestionable business database.

Use CLAUDE.md for concise project instructions. Keep a long procedure in a skill, detailed evidence in referenced files, and changing commercial facts in a maintained source. Here is a small project-instruction example:

# BriefDesk demo

## Purpose
Local teaching project for reviewing service quotes.

## Commands
- npm test: runs the local deterministic checks.

## Domain rules
- Money is stored in integer halala.
- Approved prices come from reviewed data, not generated prose.
- Invalid or missing quantities must be rejected.

## Working agreement
- Inspect the relevant code before changing it.
- Prefer a small change with a clear acceptance check.
- Report what you checked and what remains unverified.

For an agency, “write in a direct tone” is a durable instruction. “The offer ends Friday” needs a date and an owner. A copied web page is external evidence; its embedded instructions do not become your project policy.

Use /context to inspect context and /compact when a useful long session needs a focused summary. Use /clear when starting a genuinely separate task, with a handoff note if needed. Do not mechanically clear after every action or assume a summary preserves every detail.

Try this handoff: record the current objective, accepted decisions, changed files, checks run, and the next unresolved question. A short accurate handoff beats a long transcript containing obsolete plans.

CLAUDE.md memory rules and business knowledge

Separate working instructions, domain facts, session state, and time-sensitive knowledge. “Use integer minor units” is a working rule; today’s service price needs a source and review date; the file under investigation is session state.

CLAUDE.md suits concise project guidance. Rules can be organized under .claude/rules/ according to the documented mechanism. Long repeated procedures fit skills; detailed evidence can be referenced rather than repeated everywhere.

Auto memory can carry useful notes, but changed rules need correction. Inspect what the assistant knows and correct stale information at its source. Remembered information is not automatically an approved commercial fact.

A marketing knowledge record can contain offer name, price, validity period, approver, and original source. Resolve conflicting records before using them in a claim. More context does not automatically resolve a knowledge-design problem.

Retrieved documents can contain untrusted instructions. Treat them as source material while retaining your own task and permission policy. Reading a document does not grant its author control of the workflow.

Settings sources environments and secrets

Configuration changes tool behavior. User settings apply across that user’s projects, shared project settings reach a project copy, and local settings customize one person’s project. Managed organizational policy can take precedence. Lists and certain keys have merge rules; inspect the effective configuration.

An environment variable passes a value to a process. It may hold an API key or provider choice. Not every variable is secret, but credentials should not enter a repository, client interface, or screen recording.

Separate configuration, identity, and data for development and production. A successful connection is not a reason to use production data in a local experiment. Diagnose what actually loaded before changing several settings at once.

Separate instructions permissions and isolation

Three controls solve different problems. Instructions describe desired behavior. Permissions govern tool approval. Isolation limits what a process can reach. A sentence in CLAUDE.md does not create an operating-system boundary.

Defaults differ by setup. Inspect your current mode instead of assuming a tutorial’s default applies.

Project settings can live in .claude/settings.json; private overrides in .claude/settings.local.json; user settings in ~/.claude/settings.json. Managed policy has higher authority. Lists may merge, so “the project file replaces every global rule” is too simple.

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",
      "Bash(npm test)"
    ],
    "deny": [
      "Read(./.env)"
    ]
  }
}

This teaching configuration approves two named commands and denies one direct file-read pattern. Review npm test before approving it: a project script is executable code. A path rule is not a complete secret-protection system. Confirm the effective configuration with /permissions and diagnostics.

Decision exercise: Which actions in your project need approval: editing a draft, changing approved prices, publishing an ad, or deleting customer data? Write the boundary before connecting tools.

A sandbox constrains process access according to its mechanism; a worktree separates code checkouts; containers and VMs have their own isolation characteristics. These are different layers. Choose based on the work and data, and inspect managed policy.

External text does not acquire the authority of your request. Prompt injection is an attempt by input content to redirect the assistant. Limit impact through tool scope, access, and action verification rather than relying on one sentence as a complete defense.

Choose the smallest extension that solves the problem

Many confusing setups begin with choosing an extension before identifying the missing capability. Use this decision map as editorial guidance, not as a product requirement.

Suppose you repeatedly ask for the same campaign review. That suggests a procedure with criteria and examples. If the missing information is the live offer in a CRM, a skill alone cannot supply that connection. If the requirement is a repeatable check before a file edit, a hook may be appropriate.

For each proposed addition, write one sentence: “This component supplies ___, and I will know it helped when ___.” If that sentence is vague, try the built-in workflow first.

The following chapters explain the choices through working examples and the failure modes that matter most.

Turn repeated judgment into a skill

A skill is a reusable procedure with a recognizable purpose. A helpful skill states its inputs, steps, output, and exceptions. Our quote-review example is intentionally small.

Review this campaign offer
using our usual checklist

Save the following as .claude/skills/inspect-quote/SKILL.md in a demonstration project, after reviewing it:

---
name: inspect-quote
description: Review the quote calculation and explain edge cases in this demo.
disable-model-invocation: true
---

Inspect $ARGUMENTS and the tests that exercise it.
Explain the calculation, identify one plausible failure,
and point to evidence in the files. Do not change files.
If the evidence is incomplete, state what is missing.

Invoke it with /inspect-quote src/quote.mjs. The example requests read-only behavior, but the prose itself is not a hard tool restriction. For stronger tool narrowing, use a suitably restricted subagent or explicit tool configuration.

A subtle permission detail: a skill’s allowed-tools pre-approves named tools for its invocation turn. It does not, by itself, make every other tool unavailable. This differs from a subagent’s tools allowlist. Read the field’s contract before using it as a control.

Make the skill’s value measurable. Give it one correct case, one missing input, and one ambiguous business rule. Inspect whether it distinguishes “wrong,” “unknown,” and “not checked.”

Example worth expanding: a campaign-review skill that checks offer dates, unsupported claims, audience fit, and missing measurement. Add real criteria and approved examples before expanding its length.

The YAML header at the start of SKILL.md is frontmatter. Fields such as name and description identify the skill; disable-model-invocation: true controls user-led invocation under its documented contract. $ARGUMENTS carries invocation input. Preserve exact field names.

Bundle examples, scripts, and references where useful. Test when the skill should and should not trigger, then inspect its output. Length is not value. Claude-specific fields are not automatically portable to every Skills-compatible host.

Use hooks for repeatable event checks

A hook runs at a defined lifecycle event. For our teaching example, we want the Write and Edit tools to refuse changes to approved-prices.json. The project root is the launch directory, and Node.js must be available on PATH.

PreToolUse
An attempted file edit

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/guard-approved-data.mjs",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The package includes guard-approved-data.mjs. It parses the event JSON, resolves the target file, and exits with code 2 when the protected path is targeted. It also rejects malformed event input. Copy the reviewed script into .claude/hooks/ only when intentionally activating this example; the downloaded package does not activate it for you.

The hook is deliberately scoped to Write and Edit. Shell commands, alternate integrations, configuration changes, and operating-system access require their own controls. This is a workflow demonstration, not a complete data-security boundary.

For PreToolUse, exit code 2 blocks the tool call. Other hook events have different contracts; a PostToolUse failure cannot reverse a tool that already ran. The included onFailure: "block" is an explicit failure policy for this blocking example.

Local exercise: run the supplied hook tests. Inspect the permitted-file case, protected-file case, malformed-input case, and a path containing spaces. Then repeat the integration inside your own Claude Code environment before publishing a claim about it.

Read the supplied script with its configuration and test valid and malformed payloads. Post-action events suit logging and checking; they do not automatically reverse an earlier effect. A Stop hook can continue work, so an impossible stopping condition can create an unwanted loop.

Document event, input, effect, dependencies, failure policy, and exclusions. The sample does not resolve symbolic links or cover every editing route. Silencing every error with exit 0 does not establish a successful check.

Connect MCP only when a task needs the connection

MCP means Model Context Protocol. It standardizes interaction with tool servers; it does not clean a database, authorize every action, or guarantee that returned information is current.

List the available project files

Start by inspecting what is already connected:

claude mcp list
claude mcp --help

The general HTTP shape below is a template, not a working endpoint. Replace both placeholders using the service’s current official instructions:

claude mcp add --transport http <name> <verified-provider-endpoint>

In BriefDesk, an integration could read the current approved offer and create a draft. A separate approval step controls sending or publishing. Describe required operations before choosing the server: read offer, read date, draft content, request approval.

For a WordPress workflow, distinguish the website’s application permissions, the capability exposed by its adapter, the connecting user, and the assistant’s approval policy. “MCP connected” does not mean “everything should be editable.”

The current reference includes tool search for large tool sets. Avoid unsupported universal rules such as “accuracy collapses after ten tools.” Measure your task and keep the useful tool descriptions and permissions understandable.

Try next: choose a read-only external task, confirm the source and identity, inspect its output, and document a failure case before adding writes.

stdio runs a local server through standard input and output; HTTP connects to a remote server. The reference covers other transports too. Server address, identity, tool scope, and settings source are separate choices.

After adding a server, inspect /mcp, authenticate as documented, try a limited read, and check disconnection or expired credentials. Keep database passwords out of published examples and command history.

Before enabling a write, ask whether it can be repeated safely, where approval appears, and how completion is verified. Those are integration-contract questions even when the connection succeeds.

Plugins marketplaces and reusable setup

A plugin packages components for distribution. A marketplace is a catalog of packages and their sources. Catalog inclusion does not establish suitability for your project. Review publisher, version, code, commands, and connections.

/plugin

A standalone skill serves one project. A package becomes useful when distributing several skills, hooks, or agents together and maintaining versions. Plugin skills may be namespaced, such as /package:review, to avoid collisions.

Before publishing your package, test a clean installation, document dependencies and known versions, create success and failure cases, and compare with a no-package baseline. Documentation and evaluation are part of what students or buyers receive.

Distinguish a Claude Code plugin from the editor extension displaying Claude Code inside VS Code: one extends capabilities; the other provides an interface.

Code intelligence mods and interface extensions

Text search locates written names. Code intelligence uses language information to navigate symbols, definitions, references, and type diagnostics. LSP enables integration with a language server. Setup depends on language, package, and environment.

A mod extends supported interface or behavior through a programmable hooks module. It may add a pane or command where the surface supports it. October brought documented RTL properties for particular elements, not universal support for every widget.

A useful teaching prototype is a panel showing the approved offer source and check state. Review long text, Arabic, and missing-state behavior.

Use these capabilities for an observed need, such as symbol navigation in a large codebase or exposing a useful state. They are not prerequisites for the first tool.

Subagents and bounded delegation

Delegation helps when a task has a clear boundary and a result you can review. A focused researcher can inspect the quote rules while you investigate the request workflow. Two agents rewriting the same calculation at once can create coordination work instead.

A minimal custom subagent definition for .claude/agents/quote-reader.md:

---
name: quote-reader
description: Inspect quote rules and tests without editing the demo.
tools: Read, Glob, Grep
---

Find the quote calculation and its tests.
Return the rule, the relevant file references,
one missing edge case, and the evidence needed to resolve it.
Do not claim a test passed unless you have its execution result.

Inspect availability through /agents. Tools vary across environments and execution modes. A successful definition is not evidence that a subagent ran the project’s tests.

Use a worktree when separate edits need separate checkouts:

claude --worktree quote-preview

A Git worktree separates file changes and branches. It is not an operating-system sandbox and may share credentials or external services.

Agent teams coordinate peer sessions and remain experimental in the reviewed reference. Dynamic workflows put orchestration into a script and fit larger repeatable jobs. Choose them for an observed need; the smallest useful team for a local bug may still be one session.

Commission a good review: give the reviewer a question, relevant files, permitted actions, output format, and evidence standard. Ask for the strongest reproducible concern, not a dramatic list of speculative problems.

Worktrees agent teams and meaningful parallelism

Parallel work needs a decomposition whose results can be combined. One worker can review validation while another reviews documentation, provided shared edits are coordinated. Review and check the merged result.

A worktree is a linked Git checkout. It separates branch changes but can still share credentials or an external service. File separation is not account isolation.

Agent teams coordinate peer sessions through leadership, messaging, and tasks. The reviewed reference describes them as experimental and disabled by default, enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Enabling them can also change ordinary delegation behavior; understand that before adopting them.

Sequential work and same-file changes may fit one session better. Compare total time, cost, and merge quality rather than agent count. Request evidence and unverified limits from each result.

Decision exercise: classify three tasks as independent or dependent and define merge order. A task requiring an unapproved data design is not ready for parallel implementation.

Dynamic workflows and repeatable orchestration

In ordinary delegation, the assistant chooses subsequent steps during the conversation. A dynamic workflow moves orchestration into a script: what runs, what waits, and how results combine. This can suit many-file checks or repeated work.

Value comes from inspectable, repeatable coordination. Define inputs, output contract, concurrency, failure and resumption policy, and independent verification for important findings.

Example: inspect specification files for undefined pricing rules, return location and evidence, then have another phase verify candidate findings. This is a proposed teaching plan, not an actual PrintOS audit result.

Try a small run before scaling. Three simple files may need only a normal sequence. Consult current availability and controls before copying a workflow configuration.

Set a goal with an end state and a stopping policy

The /goal feature keeps working toward a completion condition, with model-based checks of whether the condition has been met. That makes the quality of the condition important.

/goal The quote calculation rejects invalid inputs, the local tests pass, and the final report names the checks actually run.

“Improve the entire product” has no useful finish line. “Reject invalid quantities, pass the named checks, and report what remains unverified” is easier to inspect. Keep the external verification even when a model judges the goal complete.

Long-running work also needs a bounded operating policy: permitted files, available credentials, action scope, expected checks, and limits appropriate to the environment. A workflow that waits for a deployment should respond to status events or supported monitoring rather than blindly repeating destructive steps.

Monitor became available across additional providers in 2.1.310. That is a provider-availability update, not the first appearance of event-driven work. A useful lesson shows one event, one response, and a clean stop condition.

Exercise: write a goal for a landing-page change that can finish without claiming improved sales before an actual experiment. Separate technical completion from the business result you will measure later.

Distinguish a goal completion condition, Monitor event/output observation, and a scheduled task triggered by supported timing or events. Repeating a prompt in an open session is not automatically a cloud service that survives closing your computer.

Define approval ownership, effect and cost boundaries, duplicate prevention, and missing-information behavior. This guide explains automation design; it does not create scheduled tasks in your account.

Evaluate the contribution of a skill or plugin

Evals are task-based evaluations. They help answer a narrower question than “is this AI impressive?” For example: does our campaign-review procedure reliably identify a missing offer date without inventing a replacement?

Plugin evals can compare a plugin with a no-plugin baseline. They use real model calls, so they consume account usage or API spend. The reviewed reference documents the command from version 2.1.269; check your current availability.

claude plugin eval init
claude plugin eval . --no-publish

Run these from an appropriate plugin directory; init creates a suite through an interactive process. --no-publish keeps the report from automatic publishing where that option applies. The bundled calculator’s unit checks are separate from this feature.

Design three original cases: a complete brief, a missing price, and an expired offer. Define the expected behavior before seeing the answer. Keep numerical checks deterministic where possible, and calibrate subjective judgments against a human reviewer.

If both the baseline and the plugin succeed, that case does not establish the plugin’s value. If an AI judge likes a fluent but unsupported claim, the grader itself needs work. Repeat trials where variation matters, and report the sample’s limits.

Question to investigate: would a shorter instruction produce the same result at lower cost?

Build domain cases: current offer, expired offer, missing price, conflicting sources. Define expected behavior first and retain evaluation cases separate from worked examples.

A function test checks a deterministic result; a campaign evaluation may judge factuality, relevance, and style. Calibrate language-model graders against human examples. Do not let an important rule violation disappear inside a high average.

Measure the cost of a completed task

Track the unit that matters to the user: a reviewed brief, a repaired issue, or a validated quote. Token totals help explain cost, but do not establish value by themselves.

In the reviewed documentation, /usage includes session and plan information. A displayed dollar estimate is not automatically an additional subscription charge. Your account’s billing page and actual usage route remain authoritative.

Prompt caching reuses matching request prefixes. It is not permanent factual memory. Model switches and other changes can affect cache behavior, so the cheapest-looking choice per request may not minimize the whole task’s cost.

For a learning experiment, record model, input type, retries, total elapsed time, estimated cost, and acceptance result. Compare like with like. If an inexpensive model needs several repairs or fails the acceptance check, count that work too.

OpenTelemetry can export usage and tool activity; some tracing functionality is explicitly beta in the current monitoring reference. Start with the information needed to diagnose the task. Avoid exporting full customer prompts or documents merely because telemetry supports more detail.

Exercise: compare two approaches on the same five teaching cases. Report completed tasks, failures, and total observed cost. Do not turn that small sample into a universal claim about model superiority.

Select models through task evidence. Effort controls supported reasoning effort; it does not guarantee correctness. Fast mode has availability and billing conditions; do not assume a free universal setting.

For a product, include successful and failed attempts, storage, hosting, service fees, and support against a clear value unit. A one-time course sale is not recurring SaaS revenue.

Logs traces and understanding system behavior

A log records an event, a metric aggregates a measurement, and a trace connects task steps. Observability is the ability to understand behavior from such evidence. Call count or changed lines alone do not establish value.

Begin with task identifier, time, stage, outcome, duration, and estimated cost. Connect errors to input and version for reproduction. Separate tool failure, unsuitable output, and bad input.

Claude Code documents OpenTelemetry export; some tracing is beta and destinations follow configuration or policy. Collect enough for diagnosis, define access and retention, and review logs before publishing cases or recordings.

Practice: classify three failures as timeout, missing input, or false claim. A single “AI failed” category does not identify a useful repair.

Programmatic execution JSON and run boundaries

Headless execution suits a program invoking a task without the normal conversational interface. Start with a bounded request and understand output and error handling.

claude -p "Explain the local quote rule. Do not change files." --output-format json

JSON structures a response; it does not establish completion. Check the output contract, terminal result, and errors for your build. Turn or estimated-cost limits are operational controls, not necessarily hard billing caps or an external timeout.

Use explicit tool selection where required and inspect settings or MCP connections that can load. Do not interpolate untrusted user text directly into shell commands. Separate input, command, and approval.

A read report on teaching data is an appropriate first case. Account creation or payment needs a different authorization and verification design.

Move to headless execution or the Agent SDK deliberately

Use interactive Claude Code when a person is steering the work. Use headless execution for a bounded programmatic task. Use the Agent SDK when your own application must control sessions, tools, limits, and the user experience.

claude -p "Explain the local quote calculation. Do not change files." --output-format json

That command returns structured CLI output; it does not give your application a complete approval interface. Handle failures and inspect the current output contract before automating decisions from it.

The package includes a Python SDK example that exposes only Read, Glob, and Grep, uses explicit setting sources, and sets turn and estimated-cost limits. It requires the SDK and authorized API access; it was syntax-checked, not run against an account during preparation.

Three details matter: allowed_tools controls pre-approval, not the entire available tool pool; the tools option selects tools. setting_sources=[] opts out of user/project/local filesystem settings, but does not erase managed policy or every global configuration source. A client-side budget estimate can overshoot and is not a hard provider billing cap.

For production, implement your application’s approval path through the documented permission callback and user-input handling. Do not assume AskUserQuestion alone supplies authentication, authorization, or a complete product UI.

Product question: does your feature need an autonomous filesystem agent, or would one deterministic function plus an ordinary model call be easier to operate?

Read examples/sdk_readonly.py in full. It selects tools and approvals, setting sources, MCP policy, and estimated limits. It does not establish whole-machine filesystem isolation; process isolation is a separate operating concern.

In TypeScript, the general query({prompt, options}) pattern yields events your application can consume. Python uses async for over query. Record task identity and terminal outcome, and design a clear approval interface for external effects. Personal subscription login is not automatic authorization for a third-party product.

Three projects that connect engineering to business

A private WordPress request

The visible page collects a request. The real acceptance boundary includes server validation, private storage, authorized management access, and a response to the visitor. Test a second visitor trying to read the first request. A polished admin table is only one part of the product.

An approved-offer campaign draft

Inputs include the approved offer, its review date, audience, and constraints. Output is a draft with unsupported claims flagged. A human approves publication. Later, actual performance can be attached to the experiment; exporting the draft is an early usefulness signal, not proof of revenue.

A print-quote teaching calculator

The local example uses quantity × approved unit price + setup fee, in integer halala. It excludes tax, discounts, shipping, material waste, and real print-production rules. These omissions are explicit teaching boundaries. Do not insert the formula into a real print business without its approved rules.

Across all three, the consulting skill is the same: identify the business decision, define who owns the data and approval, choose a small system boundary, and ask for observable evidence. Domain expertise helps write better acceptance checks; it does not remove the need to test.

Portfolio format: show the problem, baseline, decision, relevant artifacts, checks, result, and remaining limits. Use fictional labels for teaching data and permission before publishing a client case.

Laravel practice: map one request through validation, authorization, persistence, and tests in the actual repository. Do not assume every project uses identical folders. In PrintOS, approved rules, decisions, and implementation authority guide the work; work in progress is not evidence of a launched profitable system.

WordPress practice: separate content, design, and logic. Define private and public information and permissions before exposing endpoints or MCP capabilities. Use staging for the integration exercise.

Marketing practice: approved sources → brief → draft → factual check → approval → measured experiment. Sales conclusions require actual data and an attribution model with stated limits.

SSH provides a connection for commands on a remote machine; it differs from MCP’s tool-capability interface. Before work on WordPress hosting, identify account, directory, environment, and recovery copy. Begin with known reads and checks on staging. File upload, permission changes, and migrations are distinct actions requiring appropriate authority.

Release operation and team handoff

A local version needs an operating definition before real use: who runs it, who can access it, where data lives, what it depends on, and how releases change. A migration changes data structure; a rollback follows a defined recovery plan. Reverting files does not automatically reverse every data change.

Prepare a concise runbook covering requirements, non-secret configuration, startup, health check, backup, restoration, and service boundaries. Reproduce it on a clean copy.

For a team, assign rule ownership, review, deployment approval, and incident response. Codex reviewing Claude Code work can help when it examines files, diffs, and check results; agreement without evidence does not decide correctness.

Turn recurring failures into improvements, checks, or authorized teaching cases. Limit launch scope to support capacity. Define review and update commitments you can actually provide.

Build the local lab and inspect the evidence

The downloadable source package contains a small dependency-free JavaScript lab. It runs locally with Node.js 20 or later and does not need a model API call.

1. Open the examples folder from the extracted package.
2. Read quote.mjs and its teaching boundaries.
3. Run npm test.
4. Read the hook tests separately from the quote tests.
5. Change one validation rule and observe which check fails.
6. Restore the rule and verify the result.

The original examples are prepared as reference files. settings.example.json, skill-example.md, and subagent-example.md are not silently installed or activated. The guide explains their intended destination if you choose to try them.

The SDK example requires installing the current SDK and configuring authorized API access through your environment. Reading or syntax-checking that file does not establish live SDK behavior, authentication, billing, or provider compatibility.

The point of the lab is to practice a professional habit: make the claim small enough to inspect, and keep the evidence beside it.

Capstone: choose a user and task, write a one-page specification, implement one rule and a small journey, then deliver files, acceptance evidence, cost note, and a two-minute explanation. Have someone else reproduce it.

Suggested 100-point rubric: problem 20, function 20, data/access 20, checking 15, usability 15, operation/cost 10. A critical access defect or failed core function prevents completion regardless of total. This is a proposed educational rubric to calibrate in use.

Commands troubleshooting and common questions

Availability can vary by surface and configuration. Use the live menu and current reference when a command differs.

Can rewind replace Git? No. Its tracking has specific scope and retention. External effects, database mutations, and untracked changes still need their own recovery approach.

Should every file be below 300 lines? Treat size as a review signal. Cohesion, dependencies, testability, and change boundaries are better architectural questions than a universal line limit.

Should I connect every available tool? Connect what the task needs and test the integration. Keep source identity and approval boundaries understandable.

Is a low-cost third-party route equivalent to the official product? Do not assume that. Compatibility, features, authentication, model behavior, terms, and limits need separate verification. This guide makes no zero-cost service promise.

An actionable report names steps, expected and actual behavior, build, environment, and smallest reproducing input. Remove credentials and client information before sharing.

What changed in October and why it matters

Release notes become useful when you connect a change to a task. Here are three verified October milestones, not an exhaustive release history.

Do not date every interesting feature to October. Plugin evals, dynamic workflows, and agent teams have earlier histories. They belong in this edition because they affect current practice. Availability may still depend on your build, provider, surface, or organization settings.

Consider a tutorial saying a Windows hook blocks a file edit. A reliable article records the build, shell, sample input, and observed result. A release badge alone does not establish that the example works on every machine.

Try next: Record your installed version and operating environment before following a feature tutorial. When an option is missing, compare your setup with the feature’s reference page rather than guessing an undocumented command.

An 80-term reference