Scenarioshigh-yieldci-cdcli-flags

Scenario: Claude Code for CI/CD

One full lesson on headless reviews in a pipeline. Flags, cost caps, review quality, and traps.

On this page
PreviousNext
Practice questions

Scenario: Claude Code for CI/CD

The full picture

The exam tells one story here. Claude Code runs headless with claude -p inside a CI pipeline. It reviews code. It writes tests. It leaves PR feedback. No human is watching the run.

The cast of this lesson:

  • Flags that shape the run, like --append-system-prompt and --bare.
  • Cost caps, --max-turns and --max-budget-usd.
  • CLAUDE.md, which carries your team standards into every review.
  • Review quality rules, like criteria, confidence tags, and few-shot examples.

This is the flag-heavy scenario. Most people find it the hardest. One flag question shows up again and again. It is section 1.

flowchart TD
    A["CI pipeline starts"] --> B["claude -p runs headless"]
    B --> C["Prompt setup"]
    C --> C1["--append-system-prompt<br/>keeps the built-in tool guidance"]
    C --> C2["--bare<br/>no auto-discovery"]
    C --> C3["CLAUDE.md<br/>team standards"]
    C1 --> D["Agent uses tools<br/>Read and Grep across the repo"]
    B --> E["Cost caps<br/>--max-turns, --max-budget-usd"]
    D --> F["Findings with confidence and severity"]
    E --> F
    F --> G["PR comment"]
    B -.->|"200 non-urgent jobs"| H["Message Batches API<br/>50% discount"]
Remember
  • --system-prompt replaces the whole default prompt.
  • Claude then loses its built-in tool guidance. It stops using Read and Grep on other files.
  • Fix it with --append-system-prompt.
  • Cap runaway cost with --max-turns and --max-budget-usd (print mode).
  • Reproducible CI runs: --bare plus --append-system-prompt-file ./CLAUDE.md to load standards on purpose.

1. The classic flag question

Start with the question that several test-takers reported seeing.

Symptom. The headless review talks about the piped diff. It never opens other files in the repo.

Cause. --system-prompt overrode the default system prompt. That default prompt is what teaches Claude Code to use its built-in tools, like Read and Grep. That guidance is gone.

Fix. Use --append-system-prompt or --append-system-prompt-file. Your review instructions are then added to the default prompt. They do not replace it.

The distractor. --dangerously-skip-permissions is the wrong answer here. Permissions were never the problem. The lost thing was tool guidance.

2. Headless flags you must know

The fix above is one flag. Here is the full set, checked against the docs.

FlagWhat it does
-p / --printRuns without a person. Prints the response and exits. It loads CLAUDE.md, hooks, and .mcp.json unless you add --bare
--output-formattext is the default. json returns the result plus session ID plus cost metadata. stream-json streams the output
--bareSkips auto-discovery. No CLAUDE.md, no skills, no hooks, no MCP servers, no subagents. Recommended for scripts
--system-promptReplaces the entire default system prompt
--append-system-promptAdds your text to the default system prompt
--append-system-prompt-fileAdds prompt text loaded from a file
--max-turnsCaps the number of agentic turns
--max-budget-usdCaps API spend. Print mode only. It includes subagent spend
--dangerously-skip-permissionsSame as --permission-mode bypassPermissions. Deny rules still block
Remember

--bare and -p are a pair. -p alone picks up local config. -p --bare does not.

3. What gets tested

The flags are the tools. Now match each exam problem to its answer.

Problem in the questionCorrect approach
The review only sees the diff and misses cross-file bugsMake it an agentic task with tools. Let it read files and search the repo. Add a turn limit
Cost or iterations blow up in CIAdd --max-turns 10 --max-budget-usd 2.00 to the claude -p call
CI runs pick up random local configUse --bare. Pass standards on purpose with --append-system-prompt-file
200 review jobs that are not urgentMessage Batches API with unique custom_ids. 50% discount
The review flags accepted team patterns as issuesWrite the accepted patterns in CLAUDE.md. It loads in every review
Generated tests are trivial or noisyPut testing standards in CLAUDE.md: criteria, fixtures, good and bad examples
Too many false positives in reviewsGive explicit criteria. Report bugs and security. Skip style nits
The model is unsure, so silence or noiseReport all findings with confidence and severity tags. Filter them downstream
Review quality differs across concern typesSplit into focused prompts, like security and business logic. Consolidate after
A huge PR goes past the context limitSplit into several calls over file subsets. Merge the findings arrays
Identical reruns give different verdictsThe same session keeps its earlier reasoning, so it will not re-question itself. Fresh runs differ
Worry about a slow feedback loopCheck first whether feedback 24h later is still actionable. Then batch
Tell real issues from acceptable patternsFew-shot examples with annotated snippets for each category

4. Traps

These answers look reasonable. On the exam they are wrong.

  • ❌ "Add allowedTools Read, Grep" when --dangerously-skip-permissions is already set. Permissions are not the issue.
  • ❌ Pasting the whole diff into -p "..." instead of giving the agent tools.
  • ❌ Controlling cost with prompt wording instead of --max-turns and --max-budget-usd.

See also

Recap

  • The story: claude -p runs headless in CI for reviews, tests, and PR feedback.
  • --system-prompt replaces the default prompt. Tool guidance is lost.
  • Symptom of that: the review reads the diff but never opens other files.
  • Fix: --append-system-prompt or --append-system-prompt-file.
  • --dangerously-skip-permissions is a distractor in that question.
  • -p / --print prints and exits. It loads CLAUDE.md, hooks, and .mcp.json unless --bare is set.
  • --output-format: text default, json (result, session ID, cost metadata), stream-json.
  • --bare skips auto-discovery. No CLAUDE.md, skills, hooks, MCP servers, or subagents. Best for scripts.
  • --max-turns caps agentic turns.
  • --max-budget-usd caps spend. Print mode only. It includes subagent spend.
  • --dangerously-skip-permissions equals --permission-mode bypassPermissions. Deny rules still block.
  • Missed cross-file bugs → give it tools and a turn limit.
  • Cost blowup → --max-turns 10 --max-budget-usd 2.00.
  • Random local config → --bare plus --append-system-prompt-file.
  • 200 non-urgent jobs → Message Batches API, unique custom_ids, 50% off.
  • Accepted patterns flagged → document them in CLAUDE.md.
  • Trivial tests → testing standards in CLAUDE.md with criteria, fixtures, and good-vs-bad examples.
  • False positives → explicit criteria. Bugs and security only. No style nits.
  • Unsure model → report everything with confidence and severity tags.
  • Uneven quality by concern → split into focused prompts, then consolidate.
  • Huge PR → several calls over file subsets, then merge findings arrays.
  • Different verdicts on reruns → the same session keeps prior reasoning. Fresh runs differ.
  • Slow feedback → ask if 24h-later feedback is still actionable.
  • Real issue vs accepted pattern → few-shot examples with annotated snippets.
  • Traps: allowedTools when permissions are already bypassed, inlining the diff, and prompt-only cost control.

Next: Scenario: Developer Productivity