explainx / blog
How to integrate Claude Code into CI/CD for automated code review, test generation, and PR feedback — Domain 3 of the Claude Certified Architect exam.
Jul 16, 2026
The levels.io-style VPS-and-tmux setup for autonomous publishing solves a problem you probably don't have if your app already deploys through Railway. Here's the alternative design — Claude Code on the web or phone for authoring, GitHub as the trigger, and a small CI safety net — plus the one real tradeoff it introduces.
Jun 28, 2026
Pieter Levels spent almost a year coding solely on a VPS with Claude Code — no laptop open, overnight /goal runs, and live production edits with only two ~10-second outages. explainx.ai unpacks the manifesto, deploy evolution, security checklist, and when teams should refuse this pattern.
Jul 22, 2026
Jack Dorsey announced Buzz on July 21, 2026 — a self-hostable, open-source workspace where humans and AI agents share one identity system across chat, Git, and workflows. Every message and code event is a signed Nostr event. Here's what's real, what's early, and why it matters for anyone running Claude Code, Codex, or Goose on a team.
Claude Code is designed for interactive use by default. Drop it into a CI/CD pipeline without configuration and the job will hang waiting for user input that never comes. The fixes are specific and non-obvious — which is why they appear directly in Domain 3 of the Claude Certified Architect – Foundations exam (Claude Code Configuration & Workflows, 20% weight).
This guide covers the four technical requirements for reliable CI/CD integration: the -p flag, JSON output, CLAUDE.md for project context, and session isolation for independent review.
Claude Code operates in two modes. In interactive mode (the default), it waits for the user to review proposed changes, approve commands, and provide additional direction. In a CI job, there is no user — so the process blocks indefinitely on the first approval prompt.
The --print flag (short form: -p) switches Claude Code to non-interactive print mode:
claude -p "Review the diff in the last commit for security vulnerabilities. Output findings as JSON."
In print mode, Claude Code:
This is the minimum change required to make Claude Code usable in a pipeline. Without it, the CI job times out.
The --print flag is not equivalent to "trust all operations." Claude Code in CI still respects the permission model defined in CLAUDE.md and the project's .claude/settings.json. Non-interactive mode means no approval prompts, not no restrictions.
Raw text output from Claude Code is not machine-processable in a pipeline. The --output-format json flag produces structured output that downstream steps can parse:
claude -p "Analyze this file for issues" \
--output-format json \
--json-schema ./schemas/review-findings.json \
src/auth/token-validator.ts
The --json-schema flag takes a path to a JSON Schema file that Claude must conform to. This gives you schema validation at the pipeline level — if Claude's output does not match the schema, the command exits with an error code.
A minimal review findings schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["findings", "summary", "riskLevel"],
"properties": {
"findings": {
"type": "array",
"items": {
"type": "object",
"required": ["file", "line", "severity", "description", "suggestion"],
"properties": {
"file": { "type": "string" },
"line": { "type": "integer" },
"severity": { "enum": ["critical", "high", "medium", "low", "info"] },
"description": { "type": "string" },
"suggestion": { "type": "string" }
}
}
},
"summary": { "type": "string" },
"riskLevel": { "enum": ["critical", "high", "medium", "low", "clean"] }
}
}
The structured output feeds into downstream steps: a GitHub Actions step that posts findings as PR comments, a Slack notification on riskLevel: critical, or a database write for trend tracking across PRs.
The exam tests your ability to design the schema alongside the prompt — specifically, knowing that severity as an enum prevents Claude from inventing severity levels that downstream code does not handle.
Every Claude Code run in CI starts cold. Without project context, Claude Code does not know:
CLAUDE.md provides this context automatically. Claude Code reads CLAUDE.md files at project startup and incorporates them into its operating context. In CI, this means your review prompts do not need to repeat boilerplate about the project — CLAUDE.md carries it.
A CI-focused CLAUDE.md section:
## CI Review Context
### Auto-generated files (skip review)
- `src/generated/**` — protobuf outputs, do not flag
- `dist/**` — build artifacts
- `coverage/**` — test coverage reports
### Security standards
- All external API calls must use the approved HTTP client in `src/lib/http.ts`
- No hardcoded credentials — use environment variable references only
- SQL queries must use parameterized form via `src/db/query-builder.ts`
### False positive reduction
- Console.log statements in `src/scripts/**` are acceptable (not production code)
- Type assertions (`as SomeType`) are acceptable in test files only
The CLAUDE.md path hierarchy matters in CI: Claude Code reads the root CLAUDE.md first, then any subdirectory CLAUDE.md files for the specific files being reviewed. This means you can have project-wide standards in root and component-specific guidance in subdirectories.
Task Statement 3.6 in the exam directly references using CLAUDE.md to reduce false positives in automated review — a concrete scenario where the CLAUDE.md content filters out known acceptable patterns.
A session isolation pattern runs code generation and code review in separate Claude Code instances:
# GitHub Actions example
jobs:
generate:
runs-on: ubuntu-latest
steps:
- name: Generate implementation
run: claude -p "$GENERATION_PROMPT" --output-format json > generated.json
review:
needs: generate
runs-on: ubuntu-latest
steps:
- name: Independent review
run: claude -p "$REVIEW_PROMPT" --output-format json > review.json
# This instance has NO context from the generation session
The review instance has no shared context with the generation instance. This is intentional. A reviewer that shares context with the generator inherits the generator's assumptions — including its blind spots. The same reasoning error that caused a bug during generation will cause the same reasoning error during review if context is shared.
Independent instances read the diff or the files as an external reviewer would: without knowing what the generator was "trying to do." This surfaces bugs that shared-context review misses.
The exam frames this as a reliability question in the Claude Code in CI/CD scenario: "What is the most effective way to catch logic errors in AI-generated code before merging?" The answer is session isolation, not self-review with shared context.
A single Claude Code invocation reviewing a 3,000-line PR produces lower-quality findings than structured multi-pass review. Context dilution is real — findings from the first file in a large diff get less attention by the end.
The multi-pass pattern:
# Pass 1: Per-file security review
for file in $(git diff --name-only HEAD~1); do
claude -p "Security review for $file. Check: injection, authentication, data validation." \
--output-format json \
--json-schema ./schemas/security-findings.json \
"$file" > "findings-$(basename $file).json"
done
# Pass 2: Integration review across the full diff
claude -p "Review the full diff for cross-cutting concerns: API contract changes,
shared state mutations, error propagation gaps. Reference per-file
findings in findings-*.json." \
--output-format json \
--json-schema ./schemas/integration-findings.json \
$(git diff HEAD~1) > integration-findings.json
# Pass 3: Aggregation
claude -p "Synthesize findings from all per-file and integration passes.
Deduplicate, prioritize, and produce final PR summary." \
--output-format json \
--json-schema ./schemas/pr-summary.json \
findings-*.json integration-findings.json > pr-summary.json
Each pass has a focused scope. The integration pass explicitly knows it is looking at cross-cutting concerns, not re-reviewing individual files. The aggregation pass deduplicates rather than re-analyzing.
This pattern aligns with Task Statement 3.6 (optimizing automated review quality) and Domain 4 Task Statement 4.5 (structured output across pipeline stages).
CI/CD creates two distinct review timing requirements:
Pre-merge checks (blocking): Must complete before the PR can merge. Latency matters. Use the synchronous API directly. Maximum 5-minute review time is acceptable for blocking checks.
Overnight reports (non-blocking): Comprehensive analysis run on merged code, large historical diffs, or weekly security sweeps. Latency does not matter. Use the Batch API.
The Batch API offers:
The exam tests this tradeoff directly in Task Statements 4.5-4.6: "A team wants to run comprehensive security analysis across 200 files nightly. Which API mode is appropriate and why?" Answer: Batch API — the 50% cost savings are significant at scale, the 24-hour SLA is acceptable for overnight reports, and blocking developers is not required.
Pre-merge checks use synchronous API for low-latency feedback. Overnight and batch reporting use Batch API for cost efficiency. Mixing these up — using Batch API for pre-merge checks — produces a pipeline that blocks deploys for up to 24 hours.
The CI/CD scenario frame tests across Domain 3 (Claude Code) and Domain 4 (structured output):
-p/--print flag: non-interactive mode and why it is required--output-format json with --json-schema: structured pipeline outputCLAUDE.md: project context delivery and false positive reductionThe exam does not test deep knowledge of CI/CD tools (GitHub Actions, Jenkins, etc.) — it tests your understanding of how Claude Code features map to pipeline requirements.
--print/-p for all CI/CD invocations. Without it, the job hangs on the first approval prompt.--output-format json with --json-schema for machine-parseable output with schema validation.CLAUDE.md with CI-specific context: auto-generated directories to skip, project security standards, false-positive reduction guidance.This is a core topic in Domain 3 of the Claude Certified Architect – Foundations exam. Build fluency with these patterns using CCA practice exams on explainx.ai.
Update — July 16, 2026: For a content-only pipeline rather than a full code-review pipeline, see how a small GitHub Actions MDX-validation workflow plus Railway's "Wait for CI" setting keeps broken posts out of production without a VPS.
Exam domain weights and task statements are based on the Claude Certified Architect – Foundations Certification Exam Guide published by Anthropic Academy. Verify current content on Anthropic Academy before your exam date.