Contents

10 / 10Operator22 min lesson + capstone

Operate in CI and Ship the Capstone

Turn one proven interactive workflow into bounded automation with machine-readable output, CI controls, operating receipts, and a clear path back to human review.

By the end

A production-minded Claude Code workflow that can run interactively or in CI with explicit inputs, tools, credentials, budgets, stopping conditions, verification, escalation, and rollback.

Automate only a stable contract

Automation multiplies the quality of the workflow it receives. Before moving Claude Code into CI, run the task interactively on representative normal and failure cases. Stabilize the input, task packet, project instructions, tool permissions, expected artifact, verification command, and exception path. If a human still rescues the run with undocumented judgment, that judgment is part of the workflow and must remain an explicit gate.

Choose read-only or proposal-producing automation first: summarize a change, classify an issue, draft a review, or prepare a patch on an isolated branch. External messages, merges, deployments, data writes, permission changes, and other consequential effects require stronger evidence, credentials, and approval design. An automated pull request is a review surface, not proof that the change should merge.

Use non-interactive mode as an API contract

Claude Code's `-p` or `--print` mode runs a prompt non-interactively and can return text, JSON, or streaming JSON. This makes the agent callable from scripts and pipelines, but removes the normal opportunity for an operator to answer an unexpected question. The run therefore needs predeclared tools, permission behavior, turn limits, structured output, and a failure path that stops rather than guessing.

Treat input as data with provenance. Issue text, pull-request comments, logs, webpages, and repository files may contain hostile or irrelevant instructions. Keep the trusted system task separate from untrusted content, restrict tools and network access, and validate the returned structure before another process uses it. Never make free-form model text the sole authorization for a consequential command.

Design the CI job

A CI job runs on a specific event with a clean checkout, configured identity, secrets, time and cost limits, permissions, and artifacts. Pin the event and branch scope, grant the GitHub token and Anthropic credential only the access required, and keep secrets in GitHub Secrets or the approved provider mechanism. Check out the repository before invoking project skills or reading source-controlled instructions.

Anthropic's supported GitHub Action uses `anthropics/claude-code-action@v1`. Its prompt can invoke a project or plugin skill, and CLI behavior can be passed through `claude_args`. Review the current action documentation before copying configuration because inputs and product capabilities change. Treat third-party action dependencies and plugins as supply-chain code that also need review and version policy.

Operate with observability and budgets

Record the event, repository, commit, prompt or skill revision, model configuration, allowed tools, session identifier where available, duration, usage, exit status, produced artifacts, and verification results. Logs must help reconstruct the run without exposing secrets or sensitive user data. Machine-readable output should be schema-validated and retained according to the organization's data policy.

Bound cost and time with event filters, concurrency controls, turn limits, job timeouts, and clear stopping conditions. Monitor failure rate, retries, human rejection, false-positive findings, and time saved by job class rather than celebrating the number of agent runs. A workflow earns broader use when evidence shows stable outcomes and inexpensive recovery.

Close the capstone loop

The capstone combines the guide into one trustworthy vertical loop. Start with a real workflow you understand and an accepted `SPEC.md`. Orient to the canonical repository, write concise project context, establish permissions and sandboxing, isolate the branch, implement with a failing-to-passing check, review the diff, and use an independent verifier. Only then encode the repeatable, low-risk portion as a skill or CI job.

Finish with an operating review. Can another person locate the source of truth, run the workflow, understand each approval, inspect the evidence, recover from failure, and disable the automation? If not, the system is still dependent on invisible human memory. Keep autonomy at the level the receipts support and schedule a review date because Claude Code, connected tools, and the surrounding project will continue to change.

Intent: a written user outcome and bounded specification.
Truth: canonical repository, project instructions, and current source evidence.
Execution: least-privilege tools in an isolated branch or worktree.
Control: permissions, sandbox, budgets, approvals, and stopping conditions.
Proof: diff, tests, build, runtime observation, independent review, and deployment evidence when required.
Recovery: disable, retry, resume, revert, and escalate paths owned by named people.

Working reference

Commands and patterns

Run a bounded non-interactive review

claude -p "Review the current diff against SPEC.md. Return evidence-backed findings only. Do not edit files." --output-format json --max-turns 5 --allowedTools "Read" "Grep" "Glob" "Bash(git diff:*)"

A read-oriented example with machine-readable output, a turn cap, and an explicit tool allowlist. Validate the JSON and process exit status before using the result.

Minimal GitHub Action shape

name: Claude review
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: /review-change
          claude_args: --max-turns 5

Illustrative reviewed-PR workflow. Confirm current action inputs, pinning policy, permissions, secrets, skill availability, and organization requirements before adoption.

Inspect CLI automation options

claude --help
claude -p --help

Use the installed version's help alongside the current official CLI and headless documentation before relying on flags in automation.

When the happy path breaks

Failure modes

Symptom

A CI agent makes inconsistent decisions that an operator routinely fixes by hand.

Likely cause

An unstable interactive workflow was automated before its inputs, acceptance criteria, examples, and exception path were explicit.

Recovery

Disable or reduce the job to a proposal-only role, capture the hidden human decisions, and rebuild the task suite before reintroducing automation.

Symptom

Untrusted issue or pull-request text changes the agent's behavior or tool use.

Likely cause

External content was treated as trusted instruction and the run had unnecessary credentials or broad tools.

Recovery

Separate trusted task instructions from untrusted data, restrict tools and network access, validate outputs, and require human approval before consequential effects.

Symptom

A key, token, or sensitive payload appears in CI logs or artifacts.

Likely cause

Secrets were interpolated into prompts, commands echoed values, or logs retained raw tool input and output.

Recovery

Stop the job, rotate the credential, remove exposed artifacts where possible, audit access, and redesign secret injection plus log redaction before rerunning.

Symptom

The action posts a confident approval even though tests, builds, or runtime checks did not run.

Likely cause

Model judgment was mistaken for deterministic verification and missing checks were not represented as failure.

Recovery

Make required checks explicit CI gates, parse their actual status, and require the agent to report missing evidence as a blocker rather than infer success.

Hands-on lab

Ship the trustworthy Claude Code capstone

Implement one valuable vertical slice, prove it interactively, then automate a read-only or proposal-producing portion with CI-grade controls.

01Choose a repeated workflow you understand and complete the agent-ready specification from Chapter 3.
02Create the project orientation map and high-signal CLAUDE.md; verify both from a clean session.
03Implement and test the slice in an isolated worktree under the authority matrix from Chapters 5 and 6.
04Produce the debugging and verification ledger, including a regression case and the proof layer the user requested.
05Use a fresh read-only verifier to challenge the diff and receipts; repair accepted findings.
06Turn one stable, non-consequential part into a project skill and a bounded `claude -p` command with structured output.
07Add a CI job on a narrow event with least-privilege repository permissions, secret handling, timeout, turn cap, and no merge or deployment authority.
08Test success, malformed input, hostile input, missing secret, timeout, tool denial, failed verification, and disable/rollback paths.
09Run an operator handoff with someone who did not build it and record every place they still need undocumented help.

Deliverable: A repository-based capstone containing the specification, project context, isolated implementation, reviewed commit, checks, verifier report, reusable skill, bounded CI workflow, operator runbook, and evidence-backed autonomy level.

Reusable artifact

Claude Code operating runbook

The final contract for running, observing, verifying, recovering, and governing one agent-assisted workflow.

# Workflow identity
Owner: [person or team]
User outcome: [observable result]
Repository and path: [canonical source]
Specification: [versioned file]

# Trigger and inputs
Trigger: [manual / PR event / issue / schedule]
Trusted instructions: [source and revision]
Untrusted inputs: [issue text, logs, web content, etc.]
Input validation: [schema and rejection path]

# Execution
Mode: [interactive / claude -p / GitHub Action]
Model configuration: [alias or governed setting]
Allowed tools: [exact list]
Permissions and sandbox: [effective policy]
Credentials: [names, owners, minimum scopes]
Turn/time/cost limits: [bounds]

# Output and proof
Expected artifact: [schema or file]
Deterministic checks: [commands and required status]
Human approval: [decision, approver, binding]
Receipts retained: [diff, test, build, runtime, review, version]

# Operations
Logs and metrics: [location, redaction, retention]
Known failures: [symptom -> response]
Retry and idempotency: [safe conditions]
Resume or escalation: [owner and state]
Disable: [kill switch or workflow toggle]
Rollback: [code, configuration, data, external effects]
Review date: [freshness owner + date]
Autonomy level: [proposal / isolated edit / PR / other]
Evidence required to increase autonomy: [measured threshold]

Before you move on

Receipt checklist

The complete workflow succeeds interactively on representative normal and failure cases before CI adoption.
Non-interactive input, tools, permissions, output schema, turns, timeout, and stopping behavior are explicit.
CI credentials and repository permissions are least-privilege and no secret appears in logs or artifacts.
Deterministic checks and independent review gate the completion claim; model prose alone cannot authorize merge or deployment.
A second operator can run, diagnose, disable, and roll back the workflow from the runbook.
The documented autonomy level matches current evidence and has a named review date.

Primary sources

Continue with the source

Run Claude Code programmaticallyAnthropic Claude Code DocsOfficial non-interactive CLI usage, structured output, streaming, sessions, tools, limits, and programmatic patterns.Claude Code GitHub ActionsAnthropic Claude Code DocsSupported action setup, v1 inputs, skills, custom automation, authentication, security, permissions, costs, and troubleshooting.CLI referenceAnthropic Claude Code DocsCurrent interactive and print-mode commands, output formats, model and tool flags, sessions, worktrees, and permission options.Manage costs effectivelyAnthropic Claude Code DocsFirst-party usage tracking, team limits, context management, model selection, and cost-control guidance.MonitoringAnthropic Claude Code DocsOpenTelemetry metrics and events for operating Claude Code usage in team and automated environments.SecurityAnthropic Claude Code DocsSecurity architecture, prompt-injection considerations, permissions, sandboxing, and user responsibility for reviewed tool use.