Flags that matter for non-interactive use:
| Flag | Purpose |
|---|---|
-p / --print |
Non-interactive mode — without it, the pipeline hangs waiting for input that never arrives |
--output-format json |
Machine-parseable output |
--json-schema |
Enforce a specific output structure |
--output-format json --json-schema together produce structured findings a pipeline can post directly as inline PR comments. CLAUDE_HEADLESS=true and --batch are not real flags — a scenario offering either as a fix is offering something that doesn't exist.
The discriminator: a hanging pipeline is almost always the missing -p. Redirecting stdin from /dev/null is a Unix-level workaround that papers over the symptom rather than using the flag that actually puts the CLI into the mode CI needs.
Beyond the flags, context strategy is where the real judgment sits:
- CLAUDE.md is how project context reaches CI — testing standards, what makes a test genuinely valuable, available fixtures. This is the direct fix for "our CI test generation keeps producing low-value tests": the generation step doesn't know your standards unless they're in the context it loads.
- Include prior review findings on re-runs, instructing Claude to report only new or still-unaddressed issues — otherwise every push re-posts the same comments the team already saw and dismissed or fixed.
- Provide existing test files so generation doesn't duplicate scenarios that are already covered.
- Session context isolation matters for review specifically: the session that generated a piece of code is measurably less effective at reviewing that same code than an independent instance would be — its own generation reasoning is still in context, biasing what it notices.
The classic failure modes in this task statement, together:
| Symptom | Cause | Fix |
|---|---|---|
| Pipeline hangs | Missing -p |
Add -p (--print) |
| Low-value generated tests | Generation step missing project testing standards | Add/ensure CLAUDE.md is loaded as context |
| Duplicate generated tests | Generation step missing existing test files | Provide existing test files as context |
| Same PR comments re-posted every push | Missing prior review context | Include previous findings; report only new/unaddressed issues |
| Weak self-review of generated code | Same session reviewing its own generation | Use an independent session for the review step |
Cross-module link: structured, machine-parseable output for pipelines (
--output-format json+--json-schema) is the same underlying idea as Module 2's structured MCP error responses — a downstream consumer (a pipeline script, an agent deciding whether to retry) needs a defined shape to act on, not free text it has to interpret.