Chapter 08 — Claude Code Workflows

Domain 3: Claude Code Configuration & Workflows (20%) — task statements 3.5, 3.6

Three topics: choosing plan mode vs direct execution, iterative refinement technique, and running Claude Code headless in CI. Scenarios 2 and 5 live here.

1. Plan mode vs direct execution

Task statement 3.5. 🎯 A published sample question turns on this.

	Plan mode	Direct execution
What happens	Claude investigates and proposes an approach; you review before anything changes	Claude makes the changes
Right for	Large-scale changes · multiple viable approaches · architectural decisions · multi-file edits	Well-scoped single changes with an obvious implementation
Cost of skipping	Wrong architectural direction discovered after 40 files are edited	Overhead on a two-line fix

🎯 The four triggers for plan mode

Any one of these in a stem points at plan mode:

Large scale — many files, broad blast radius
Multiple viable approaches — the choice matters and should be reviewed before execution
Architectural decisions — structural consequences that are expensive to reverse
Multi-file coordination — changes that must be consistent across files

The guide's example: decomposing a monolith into microservices. All four triggers fire. The answer is plan mode.

Direct execution is right more often than candidates expect

⚠️ Don't over-apply plan mode. "Add a null check to this function," "fix this failing test," "rename this variable across the module" — well-scoped, one obvious approach, small blast radius. Plan mode here is pure overhead, and an item describing a small targeted change wants direct execution.

The discriminator: is there a decision to review, or just work to do?

📎 The Explore subagent

🎯 A distinct, highly-testable mechanism: use the Explore subagent to isolate verbose discovery from the main session.

The problem: understanding an unfamiliar codebase means many Grep and Read calls, and every one of those results lands in the main conversation. By the time you know enough to make the change, the context is full of file dumps you no longer need — and the model's attention is spread across them.

The fix: delegate discovery to a subagent. It does the searching in its own isolated context and returns a summary. The main session receives the conclusion, not the raw exploration.

Main session                     Explore subagent
────────────                     ────────────────
"Where is auth handled?"  ──────▶  Grep for "authenticate"
                                   Read 6 candidate files
                                   Grep the imports
                                   Read 4 more files
                          ◀──────  "Auth is in src/auth/: middleware.ts
                                    validates the JWT, session.ts manages
                                    refresh, and both are wired in
                                    server.ts:42. Token secret comes from
                                    AUTH_SECRET."

The main context gained four sentences instead of ten file contents. 🧠 Note this is the same principle as subagent context isolation (Chapter 03 §1) and skills with context: fork (Chapter 07 §4) — push verbose intermediate work into a context you're going to throw away. Three mechanisms, one idea. The exam tests all three.

2. Iterative refinement

Task statement 3.5, second half. How to get an agent from "roughly right" to "right."

🎯 2–3 concrete input/output examples

The most effective refinement technique, per the guide: give 2–3 concrete examples of the input and the desired output. Not a description of what you want — the actual pairs.

This is the same principle as few-shot prompting (Chapter 09 §2) applied to interactive work. Descriptions of desired behaviour are interpretable in many ways; examples pin down the interpretation.

Test-driven iteration

Have the agent write or run tests, then iterate against the failures. The test output is unambiguous, machine-generated feedback — much stronger than your prose assessment of whether the code looks right. When a stem mentions that correctness is verifiable, test-driven iteration is favoured.

📎 The interview pattern

Rather than writing one elaborate specification up front, have the agent ask you clarifying questions before it starts. This surfaces the ambiguities you didn't know were ambiguous — and it's cheaper than discovering them in the output.

🎯 The item shape: "requirements are underspecified and the developer keeps getting output that doesn't match their intent." The answer is the interview pattern — have Claude ask questions first — not "write a longer prompt."

🎯 Batch feedback vs sequential feedback

A precise distinction that makes a good item:

Situation	Approach
The issues interact — fixing one affects another	All issues in one message. The agent can weigh them together and find a coherent solution.
The issues are independent	Sequentially is fine, and keeps each change reviewable.

⚠️ The reason batching matters for interacting issues: sequential fixes to interdependent problems cause the second fix to undo the first. If a stem says the agent "fixes one thing and breaks another," the answer is to present the constraints together.

3. CI/CD — headless Claude Code

Task statement 3.6. Scenario 5 (Continuous Integration) is built entirely on this. 📎 Exact flags; pure recall.

The flags

Flag	Purpose
`-p` / `--print`	Non-interactive mode: run the prompt, print the result, exit. This is how Claude Code runs in CI.
`--output-format json`	Emit structured JSON instead of prose, so a pipeline can parse it
`--json-schema`	Constrain the JSON output to a schema you supply
`--resume <session>`	Continue a named prior session

# Automated PR review in CI
claude -p "Review the changes in this PR against .claude/rules/. \
Report findings as JSON." \
  --output-format json \
  --json-schema ./ci/review-schema.json \
  > review.json

# Then a script decides whether to post comments or fail the build.

🚫 Non-existent flags

The published sample question offers CLAUDE_HEADLESS (an environment variable) and --batch as distractors. Neither exists. The answer is -p / --print.

⚠️ This is worth internalizing beyond the specific strings: on configuration items, the exam's favourite distractor is a plausible-sounding flag that doesn't exist. -p is short and unglamorous; the fake options sound more purpose-built. Trust the real one.

🎯 CLAUDE.md as the CI context carrier

In CI there is no developer to explain the project. CLAUDE.md is how the CI run inherits project context — conventions, architecture, what counts as a real problem in this codebase.

This is a genuinely important design point: a headless review that doesn't load project conventions will flag things that are deliberate choices in your codebase, which is a direct cause of false positives. Committing CLAUDE.md and .claude/rules/ gives the CI agent the same context a human reviewer would have.

🎯🎯 Session context isolation — the generating session can't review its own code

One of the highest-value facts in Domain 3, and it appears in more than one form.

The generating session is worse at reviewing its own output. It carries the reasoning that produced the code, so it's predisposed to see that reasoning as correct — the assumptions that caused a bug are still in its context, still looking reasonable.

The fix: review in a separate session with fresh context. A reviewer instance that sees only the code, not the reasoning that produced it, evaluates it on its merits.

⚠️ Distractors in this family:

"Ask the same session to double-check its work" — this is precisely the thing that doesn't work.
"Enable extended thinking for the review" — more reasoning inside the contaminated context doesn't decontaminate it.

🧠 The general principle, which recurs in Chapter 10 §5 as multi-instance review: independent context is what makes review valuable. Self-review — by a session, by a model, by a person — inherits the blind spot that caused the error.

4. Worked examples

Example 1 — plan mode

A team needs to decompose a monolithic application into microservices. Several decomposition boundaries are plausible and the choice affects dozens of files. How should they use Claude Code?

A. Use plan mode to have Claude investigate and propose an approach for review before making changes. B. Use direct execution and review the resulting diff. C. Run separate sessions for each candidate service and merge the results. D. Use --output-format json to get a structured migration plan.

Answer and reasoning

All four plan-mode triggers are present: large scale, multiple viable approaches, an architectural decision, and multi-file coordination. The decomposition boundary is the expensive decision, and it should be reviewed before dozens of files change.

B — Reviewing a diff that spans dozens of files across a wrong boundary means discovering the problem at the most expensive moment.
C — Presupposes the boundary decision that hasn't been made yet, and provides no coordination between the pieces.
D — A output-format flag for non-interactive runs; it doesn't provide the review-before-execute gate, and this is an interactive architectural task.

Reflex applied: is there a decision to review, or just work to do? Here, a decision.

Example 2 — headless CI

A team wants Claude Code to run automated reviews in their CI pipeline, producing output a script can parse. Which approach is correct?

A. Invoke claude -p with --output-format json. B. Set the CLAUDE_HEADLESS environment variable before invoking claude. C. Invoke claude --batch with a prompt file. D. Run claude interactively and scrape the terminal output.

Answer and reasoning

-p / --print is the non-interactive mode, and --output-format json gives a script something to parse. Add --json-schema if you need the shape constrained.

B — CLAUDE_HEADLESS does not exist.
C — --batch does not exist. (Don't confuse it with the Message Batches API, which is a different product surface entirely — Chapter 10 §4.)
D — Fragile and unnecessary when a structured output mode exists.

Reflex applied: if you can't picture the flag, distrust it. Two of these four options are fabricated.

5. Decision reflexes (reproduce from memory)

Plan mode for large scale · multiple viable approaches · architectural decisions · multi-file coordination. Direct execution for well-scoped single changes.
Discriminator: is there a decision to review, or just work to do?
Explore subagent isolates verbose discovery so file dumps never enter the main context. Same idea as subagent isolation and context: fork.
Refinement: 2–3 concrete input/output examples · test-driven iteration · the interview pattern for underspecified requirements.
Interacting issues → all in one message. Independent issues → sequential is fine.
CI = -p / --print, plus --output-format json and --json-schema. CLAUDE_HEADLESS and --batch do not exist.
CLAUDE.md carries project context into CI — the defence against context-blind false positives.
The generating session is worse at reviewing its own code. Review in a separate session with fresh context; self-review and extended thinking don't substitute.