Claude Code in CI/CD

Claude Code in CI/CD is non-trivial — a misconfigured pipeline hangs forever waiting for input that never comes. This lesson covers the -p flag (mandatory in pipelines), structured output formats, multi-pass review patterns for large PRs, and the rule about independent review instances.

Non-Interactive Mode: The -p Flag

By default, Claude Code is interactive — it expects a TTY and may prompt for input. In CI, there's no TTY and no human to answer prompts. The -p (or --print) flag tells Claude Code to run non-interactively: process the input, produce the output, exit. This flag is mandatory in automated pipelines.

# Correct — exits after completing
claude -p "Analyze this PR for security issues"

# Wrong — hangs in CI waiting for input that never comes
claude "Analyze this PR for security issues"

Structured JSON Output

For CI to consume the output (post comments, gate merges, etc.), use structured output:

claude -p "Review PR" --output-format json --json-schema ./schema.json

The schema defines the shape of the output. CI scripts can then parse the JSON deterministically rather than scraping prose.

Independent Review Instances

If Claude generates the code and then Claude reviews the same code in the same session, the model retains its reasoning context — it's less likely to question its own decisions. Use a fresh, independent Claude instance for the review. The reviewer doesn't have the generator's reasoning, so it evaluates the code on its own merits.

Avoid Duplicate Comments on Re-Runs

If your pipeline re-runs Claude for review on the same PR (e.g., after new commits), include prior review findings in the context. Without that, Claude re-discovers the same issues and posts duplicate comments. The user-facing experience: "Claude flagged this 5 times across 5 commits." Annoying and noisy.

Multi-Pass Review for Large PRs

For PRs with 14+ files, a single review pass produces shallow, contradictory output. The model's attention spreads thin. Split into two passes:

1. Pass 1: per-file local analysis. Each file reviewed in isolation. Depth and consistency improve dramatically because the model can focus.
2. Pass 2: cross-file integration analysis. Data flow between modules, shared state, contradictions in approach across files.

Larger context windows do NOT solve this. Even when all 14 files fit in context, attention quality degrades. The fix is workflow, not capacity.

Document Standards in CLAUDE.md

If your project has specific testing patterns, security review criteria, or commit conventions, document them in CLAUDE.md. The CI Claude instance reads CLAUDE.md and uses those standards. Without explicit standards, the review is generic and misses your team's specific concerns.

What's Not a Real Flag

Be wary of fabricated flags. CLAUDE_HEADLESS, --batch, --ci-mode — these are not real Claude Code flags. The flag for non-interactive mode is -p or --print. If a question proposes one of these fake flags as the answer, it's a distractor.

Skills to Develop

1. Use the -p flag in every CI pipeline that invokes Claude Code.
2. Use --output-format json --json-schema for parseable CI output.
3. Use independent review instances for code review (not the same session that generated the code).
4. Include prior review findings in re-run context to avoid duplicate comments.
5. Split large PR reviews into per-file + integration passes.