CI/CD Integration

Official Exam Guide Objectives

Knowledge of

• The -p (or --print) flag for running Claude Code in non-interactive mode in automated pipelines
• --output-format json and --json-schema CLI flags for enforcing structured output in CI contexts
• CLAUDE.md as the mechanism for providing project context (testing standards, fixture conventions, review criteria) to CI-invoked Claude Code
• Session context isolation: why the same Claude session that generated code is less effective at reviewing its own changes compared to an independent review instance

Skills in

• Running Claude Code in CI with the -p flag to prevent interactive input hangs
• Using --output-format json with --json-schema to produce machine-parseable structured findings for automated posting as inline PR comments
• Including prior review findings in context when re-running reviews after new commits, instructing Claude to report only new or still-unaddressed issues to avoid duplicate comments
• Providing existing test files in context so test generation avoids suggesting duplicate scenarios already covered by the test suite
• Documenting testing standards, valuable test criteria, and available fixtures in CLAUDE.md to improve test generation quality and reduce low-value test output

What You Need to Know

Running Claude Code inside a pipeline changes what it is. There is no operator, no conversation, and nothing that can pause for a decision — it becomes an automated review and generation step. Five concepts are tested here, and the -p flag is the most directly examinable single fact in the domain (it is Question 10 in the sample question set).

The -p Flag: Non-Interactive Mode

By default Claude Code opens a conversational interface and waits for you to type. A CI runner has nobody to type, so the process sits there until the job times out — no error, no output, just a job that never finishes.

# WRONG — hangs in CI
claude "Analyse this pull request for security issues"

# CORRECT — runs non-interactively
claude -p "Analyse this pull request for security issues"

-p (equivalently --print) selects print mode: the prompt is processed, the result goes to stdout, the process exits.

There is nothing to reason about here — it is recall. Items describe a stalled job with logs showing Claude waiting on input, and the answer is -p. The distractors are inventions: CLAUDE_HEADLESS=true is not a variable, --batch is not a flag, and redirecting stdin from /dev/null does not change the mode Claude Code is running in.

Structured Output for CI

Output in a pipeline is consumed by software, not read by anyone, so it needs to parse. Two flags cover it:

• --output-format json — returns the run inside a JSON envelope carrying the result text alongside the session ID and cost/usage figures, rather than prose meant for a terminal
• --json-schema — checks the agent's final output against a schema you supply, and is available in print mode only

claude -p \
  --output-format json \
  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"},"message":{"type":"string"}}}}}}' \
  "Review this PR for security issues"

One detail costs people marks: the schema-conforming data sits in the envelope under structured_output, so it is jq '.structured_output' rather than reading the top level. What you get back is validated enough to act on:

• Parse programmatically
• Post as inline PR comments at the exact file and line
• Filter by severity for different notification channels
• Track across review runs

Session Context Isolation

Asking the session that wrote the code to review the code is weaker than asking a fresh one, and not marginally.

Why self-review is weaker:

Generating code leaves a session holding its own reasoning — the approach it settled on, the alternatives it dismissed, the trade-offs it accepted. Reviewing inside that same session means every one of those decisions arrives already justified, and a decision that has been justified is one the reviewer is disinclined to reopen.

The fix: independent review instances

Invoke a second time, with no access to the first session's reasoning. The reviewer then meets the code as code, with no attachment to why it looks the way it does.

# Session A — writes the code
claude -p "Implement the token refresh middleware"

# Session B — separate invocation, no sight of A's reasoning
claude -p "Audit the token refresh middleware: auth bypasses, unhandled failures, edge cases"

The same principle appears in Domain 4 as multi-instance review architecture and in Domain 5 as context management; here it is tested specifically in a pipeline.

Incremental Review Context

Reviews fire on every push, and a review with no memory re-derives its findings from scratch each time. The issues genuinely fixed drop off by themselves, because the code that triggered them is gone. The ones that persist are those the developer read and decided against — and a context-free scan cannot distinguish a rejected suggestion from a new problem, so it raises them again on every push.

Carrying the previous findings forward, with an instruction to report only what is new or still outstanding, is the fix:

claude -p \
  --output-format json \
  "Review this PR. The previous run reported the following:
  ${PREVIOUS_FINDINGS}

  Return only two categories:
  1. Anything not present in that list
  2. Anything from that list still unresolved in the current diff

  Say nothing about items the developer has evidently seen and chosen to leave."

What is at stake is whether anyone reads the output. Five identical comments arriving on every push teach the team that the comments carry no information, and once that lesson lands the genuinely important finding is skipped with the rest.

CLAUDE.md for CI Context

A CI-invoked run reads the project's CLAUDE.md files exactly as an interactive one does, which makes CLAUDE.md the mechanism for giving an automated run the context it cannot ask for:

• Testing standards: which patterns the team writes tests in, and which it has decided against
• Available fixtures: what already exists to build test data from, and what each one contains
• Review criteria: where the line sits between something worth blocking a merge for and a style preference
• Existing test coverage: what is already exercised, so suggestions land on the gaps

Absent that, generated tests are plausible and worthless — assertions about behaviour nobody was worried about, duplicating coverage that already exists. With it, they follow the conventions the team already uses and test what is actually uncovered.

# .claude/CLAUDE.md — CI-relevant section
## Testing Standards

- Build test data through the factories in test/factories/, never inline literals
- Integration tests reach the database through test/setup/db.ts
- Assert against public API contracts; private internals are not a test surface
- New code is expected to reach 80% branch coverage
- Fixtures on hand: test/fixtures/users.json, test/fixtures/orders.json

CLI Flags Reference

-p is the flag the exam tests hardest, but a headless run is shaped by several others: what form the output takes, which system prompt is in force, and how far permissions and tools extend. Everything below works with claude -p in CI and equally with the interactive claude.

System prompt flags. Four exist, and the distinction under test is append versus replace:

Append when Claude should remain a coding assistant that additionally follows your rules — the default tool guidance, safety instructions and coding conventions all survive, so you write only the difference. Replace when the role genuinely is not Claude Code's: a non-coding agent running in a pipeline nobody is watching. Replacing discards the whole default prompt, which means anything the task still depends on is now yours to supply.

Headless output and limits (print mode).

Permissions, tools, and context.

Session and start-up. -c / --continue picks the most recent conversation in the current directory back up, while -r / --resume <id|name> targets a specific one. --bare is the minimal mode: auto-discovery is skipped entirely — hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md are all left unloaded — so a scripted call starts quickly with only the Bash and file read/edit tools in hand. It suits scripted runs where speed and predictability matter more than having project configuration present.

Providing Existing Tests to Avoid Duplication

Test generation in CI needs the existing tests in context, and for a reason that only shows up in review: without them Claude Code has no way to know what is already covered, so it proposes tests that duplicate ones already in the suite. Every duplicate costs a developer the time to read it and reject it. Supplied with the current tests, the same run identifies gaps instead.

Batch API vs Real-Time for CI Workflows

The Message Batches API costs 50% less and takes up to 24 hours, with no guaranteed latency SLA. Those two facts together draw a sharp line:

The distinguishing question is whether anybody is blocked. A pre-merge check holds up both a developer and a merge, and "up to 24 hours, no guarantee" is not a wait a review gate can absorb — so those go to the real-time API however attractive the saving looks. Work that runs on a schedule and is read whenever someone gets to it is exactly what the 50% discount is for. The exam tests this distinction directly (Sample Question 11).

Deep Dive

--bare mode for reproducible CI runs

--bare reduces startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md — useful for CI and scripts that need the same result on every machine, independent of what happens to be installed locally. Anthropic states --bare is "the recommended mode for scripted and SDK calls, and will become the default for -p in a future release." This trades away exactly the CLAUDE.md context this lesson otherwise relies on — reach for --bare only when reproducibility matters more than project context.

Sourcecode.claude.com › headlessfetched 2026-07-30

JSON output fields: cost tracking and structured_output

With --output-format json, the response payload includes total_cost_usd and a per-model cost breakdown, letting scripted callers track spend per invocation. Combining --output-format json with --json-schema puts the schema-conforming data specifically in the structured_output field, alongside session ID and usage metadata — extract it with jq -r '.structured_output', not from the top level of the envelope. As of v2.1.205, an invalid JSON Schema makes claude exit with an explicit error rather than silently falling back to unstructured text.

Sourcecode.claude.com › headlessfetched 2026-07-30

dontAsk mode for locked-down CI runs

The dontAsk permission mode denies anything not already in your permissions.allow rules or the built-in read-only command set — recommended specifically for locked-down CI runs where nothing should be improvised. In non-interactive -p runs generally, auto mode aborts the session when the classifier repeatedly blocks actions, because there's no user available to prompt.

Sources: https://code.claude.com/docs/en/headless (dontAsk for CI) · https://code.claude.com/docs/en/permission-modes (repeated blocks abort a -p session) (fetched 2026-07-30)

Operational limits worth knowing for CI

Piped stdin into claude -p is capped at 10MB (as of v2.1.128); exceeding it produces a clear error and non-zero exit status. Stopping a claude -p run with SIGTERM aborts the in-progress turn, terminates the process tree of any running Bash command, runs SessionEnd hooks, and exits with code 143. The stream-json output format's last line is always a result message carrying the final response text, cost, and session metadata.

Sourcecode.claude.com › headlessfetched 2026-07-30

GitHub Actions integration

A simple @claude mention in any PR or issue lets Claude analyse code, create PRs, implement features, and fix bugs while following the project's standards; the integration is built on the Claude Agent SDK. Quick setup runs /install-github-app interactively; manual setup installs the Claude GitHub app, adds ANTHROPIC_API_KEY as a repository secret, and copies the example workflow into .github/workflows/. The app needs read & write on Contents, Issues, and Pull requests. The v1 action auto-detects interactive mode (responding to @claude mentions) versus automation mode (running immediately with a prompt), exposes a unified prompt input plus claude_args for CLI passthrough, defaults its trigger_phrase to "@claude", and defaults --max-turns to 10 inside claude_args.

Sourcecode.claude.com › github-actionsfetched 2026-07-30

CI gate on MCP/plugin load errors

The stream-json format's system/init event carries plugin_errors and mcp_server_errors fields whose keys are omitted entirely when there are no errors — so a CI gate can simply fail the job when either array is non-empty, without needing to distinguish "no errors" from "empty array."

Sourcecode.claude.com › headlessfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Set Up a CI/CD Pipeline with Claude Code

Difficulty: Advanced (3/4)

45 minutes

1. Write a CI script that runs Claude Code with the -p flag for non-interactive PR analysis

Why: The -p flag is the single most directly testable fact in Domain 3. Without it, the CI job hangs indefinitely waiting for interactive input. This is Question 10 in the official sample questions.

You should see: A CI script (GitHub Actions YAML, GitLab CI, or similar) that invokes claude -p with a review prompt. The job completes successfully without hanging. The output is printed to stdout and captured by the CI system.

2. Add --output-format json and --json-schema to produce structured findings with file, line, severity, and message fields

Why: CI output must be machine-parseable. Automated systems need structured JSON to post inline PR comments, filter by severity, and track findings across runs. Human-readable text output cannot be reliably parsed by downstream tools.

You should see: The Claude Code output is a JSON envelope whose structured_output field conforms to the specified schema. Each finding has file, line, severity, and message fields. Piping the output to jq .structured_output extracts the validated data without errors.

3. Configure the pipeline to parse the JSON output and post findings as inline PR comments

Why: Inline PR comments at exact file and line numbers provide actionable feedback. Generic PR-level comments are ignored. Structured JSON output makes precise inline commenting possible.

You should see: Each finding from the JSON output appears as an inline comment on the PR at the exact file and line number. Severity levels are visible. Developers can see the finding in context alongside the code it references.

4. Add a section to CLAUDE.md documenting testing standards, available fixtures, and review criteria for CI-invoked Claude Code

Why: Claude Code reads CLAUDE.md in CI just as in interactive mode. Without project context, CI-invoked test generation produces low-value boilerplate. With testing standards and fixture documentation, generated tests follow team patterns.

You should see: The CLAUDE.md file contains a clearly marked CI-relevant section with testing standards, available fixture paths, and review severity criteria. CI-invoked Claude Code produces tests using the documented factories and fixtures rather than generic boilerplate.

5. Set up two separate Claude Code invocations: one for code generation and an independent one for review (no shared session context)

Why: The same session that generated code is less effective at reviewing it because it retains reasoning context that biases it toward its own decisions. Independent review instances evaluate code on its own merits without prior justification bias.

You should see: Two distinct claude -p invocations in the CI script: one for generation and one for review. They share no session context. The review invocation analyses the generated code independently. The review findings are more thorough than self-review in the same session.

6. Implement incremental review: store previous findings, include them in the next review run, and instruct Claude to report only new or still-unaddressed issues

Why: Without incremental context, each review run analyses the entire PR from scratch and produces duplicate comments. Duplicate comments erode developer trust — when the same five issues appear on every push regardless of fixes, developers stop reading them.

You should see: The first review run produces findings and stores them (as a JSON artifact or file). Subsequent runs include the previous findings in context. The output contains only new issues or issues that remain unaddressed. Previously fixed issues do not reappear as comments.

Sources

• Claude Code CLI Reference — Anthropic
• Claude Code Headless Mode Documentation — Anthropic
• Claude Code GitHub Actions Documentation — Anthropic
• Claude Certified Architect Foundations Exam Guide — Task Statement 3.6 — Anthropic
• Claude Certified Architect Foundations Exam Guide — Sample Questions 10 and 11 — Anthropic
• Anthropic Message Batches API Documentation — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Write a CI script that runs Claude Code with the -p flag for non-interactive PR analysis

Why: The -p flag is the single most directly testable fact in Domain 3. Without it, the CI job hangs indefinitely waiting for interactive input. This is Question 10 in the official sample questions.

You should see: A CI script (GitHub Actions YAML, GitLab CI, or similar) that invokes claude -p with a review prompt. The job completes successfully without hanging. The output is printed to stdout and captured by the CI system.

Example GitHub Actions step:
- name: Review PR
  run: |
    claude -p "Analyse the changes in this pull request for security issues, error handling gaps, and test coverage."
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Step 2. Add --output-format json and --json-schema to produce structured findings with file, line, severity, and message fields

Why: CI output must be machine-parseable. Automated systems need structured JSON to post inline PR comments, filter by severity, and track findings across runs. Human-readable text output cannot be reliably parsed by downstream tools.

You should see: The Claude Code output is a JSON envelope whose structured_output field conforms to the specified schema. Each finding has file, line, severity, and message fields. Piping the output to jq .structured_output extracts the validated data without errors.

Update your CI command:
claude -p \
  --output-format json \
  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"},"message":{"type":"string"}}}}}}' \
  "Review this PR for security issues"

Step 3. Configure the pipeline to parse the JSON output and post findings as inline PR comments

Why: Inline PR comments at exact file and line numbers provide actionable feedback. Generic PR-level comments are ignored. Structured JSON output makes precise inline commenting possible.

You should see: Each finding from the JSON output appears as an inline comment on the PR at the exact file and line number. Severity levels are visible. Developers can see the finding in context alongside the code it references.

Example pipeline script:
FINDINGS=$(claude -p --output-format json --json-schema '...' "Review this PR")
echo "$FINDINGS" | jq -r '.structured_output.findings[] | "\(.file):\(.line) [\(.severity)] \(.message)"' | while read finding; do
  # Post as inline PR comment using gh api
  gh api repos/:owner/:repo/pulls/:pr/comments ...
done

Step 4. Add a section to CLAUDE.md documenting testing standards, available fixtures, and review criteria for CI-invoked Claude Code

Why: Claude Code reads CLAUDE.md in CI just as in interactive mode. Without project context, CI-invoked test generation produces low-value boilerplate. With testing standards and fixture documentation, generated tests follow team patterns.

You should see: The CLAUDE.md file contains a clearly marked CI-relevant section with testing standards, available fixture paths, and review severity criteria. CI-invoked Claude Code produces tests using the documented factories and fixtures rather than generic boilerplate.

Add to .claude/CLAUDE.md:
## Testing Standards (CI Context)

- Use factory functions from test/factories/ for data creation
- Integration tests use the test database via test/setup/db.ts
- Do not test private implementation details
- Coverage target: 80% branch coverage for new code
- Available fixtures: test/fixtures/users.json, test/fixtures/orders.json

## Review Criteria
- Critical: security issues, data loss risk, authentication bypass
- Major: missing error handling, uncovered edge cases
- Minor: naming conventions, style inconsistencies

Step 5. Set up two separate Claude Code invocations: one for code generation and an independent one for review (no shared session context)

Why: The same session that generated code is less effective at reviewing it because it retains reasoning context that biases it toward its own decisions. Independent review instances evaluate code on its own merits without prior justification bias.

You should see: Two distinct claude -p invocations in the CI script: one for generation and one for review. They share no session context. The review invocation analyses the generated code independently. The review findings are more thorough than self-review in the same session.

CI pipeline steps:
# Step 1: Generate (Session A)
- name: Generate tests
  run: claude -p "Generate unit tests for src/auth/middleware.ts"

# Step 2: Review (Session B — independent)
- name: Review generated tests
  run: claude -p "Review the test file at src/auth/middleware.test.ts for coverage gaps, edge cases, and assertion quality. Do not assume the tests are correct."

Step 6. Implement incremental review: store previous findings, include them in the next review run, and instruct Claude to report only new or still-unaddressed issues

Why: Without incremental context, each review run analyses the entire PR from scratch and produces duplicate comments. Duplicate comments erode developer trust — when the same five issues appear on every push regardless of fixes, developers stop reading them.

You should see: The first review run produces findings and stores them (as a JSON artifact or file). Subsequent runs include the previous findings in context. The output contains only new issues or issues that remain unaddressed. Previously fixed issues do not reappear as comments.

Implementation pattern:
# Load previous findings if they exist
PREV=$(cat previous-findings.json 2>/dev/null || echo "[]")

# Run review with incremental context
claude -p --output-format json \
  "Review this PR. Previous findings: $PREV
  Report ONLY:
  1. New issues not in previous findings
  2. Issues from previous findings still present
  Do NOT re-report fixed issues."

# Save current findings for next run
cp output.json previous-findings.json

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the pipeline you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Pipeline Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the pipeline you actually wrote.