Claude Code 接入 CI/CD Pipeline

Claude Code CI/CD pipeline 整合是任務說明 3.6——「將 Claude Code 整合進 CI/CD pipeline」——的核心，屬於 Domain 3（Claude Code 設定與工作流程，佔 CCA-F 考試 20%）。它也是第六情境叢集「Claude Code 持續整合」的核心主題，而這個情境叢集是每場考試從六個情境中隨機抽出的四個之一。社群那份在 2026 年 4 月以 893/1000 通過考試的報告，稱 -p flag 為「整個 Domain 3 題庫中，測試頻率最高的 Claude Code 設定細節」。把 Claude Code CI/CD pipeline 整合搞清楚，不是加分項目——而是拿到及格分的必要條件。

這份學習筆記全面涵蓋任務 3.6 大綱中的每個要點：Claude Code 在自動化 pipeline 中的定位、-p / --print flag 的精確語義、--output-format json 封包格式、--json-schema 強制驗證、無 TTY 的 headless 模式、PR review 自動化、提交時觸發測試生成、安全掃描摘要、CI agent 的 CLAUDE.md 與 .mcp.json 設定、exit code 語義以及 pipeline 失敗傳播，還有成本管控紀律。每個章節都將 Claude Code CI/CD pipeline 整合連回考試情境，以及 CCA-F 用來區分「只記住 flag」與「真正理解架構」的具體干擾選項。

CI/CD 整合概覽 — Claude Code 在自動化 Pipeline 中的角色

CI/CD pipeline 是一連串腳本化的階段，在每次程式碼變更時依序執行：checkout、build、靜態分析、test、打包、部署。Claude Code CI/CD pipeline 整合，就是在其中某個階段從內部呼叫 claude CLI，讓 Claude 以第一等自動化步驟的身份參與——不是坐在終端機前的開發者，而是一個接受確定性輸入、產出確定性輸出的非互動行程。

Claude Code CI/CD pipeline 整合的使用情境，涵蓋五種常見的自動化形態：

• PR review — Claude 讀取 diff，發布結構化的審查意見。
• 測試生成 — Claude 為新增的程式碼路徑撰寫測試。
• 安全掃描摘要 — Claude 將原始 SAST 輸出轉換為可行動的說明文字。
• 文件維護 — Claude 在函式簽名變更時更新 README 或說明文件。
• Release note 草稿 — Claude 將已合併的 PR 清單轉換為 changelog。

這五種形態共享同一組機械需求：claude 行程必須在無 TTY 環境下執行、不能提示人類輸入、必須輸出機器可讀的結果，並且必須正確傳播 exit code，讓 pipeline 在發生錯誤時能夠失敗。這些需求最終都歸結為一個關鍵 flag——-p——以及一小組 CCA-F 要求你熟練掌握的配套 flag。

為什麼 CCA-F 將 CI/CD 獨立出一個情境叢集

Claude Code CI/CD pipeline 整合是 Domain 3 中唯一擁有自己情境叢集的主題。考試指南專門將六個情境之一——「Claude Code 持續整合」——分配給這個面向，代表每場抽到 CI 情境的考試，都有三到五道題圍繞同一個呼叫流程展開。把這個主題跳過去，理由是「不就是一個 CLI flag」，等於把整個情境叢集的分數拱手相讓。社群 2026 年 4 月的通過報告，明確將 -p 的掌握程度列為 CI 情境成敗的關鍵因素。

-p / --print Flag — 腳本化用途的非互動單次執行

-p（完整寫法為 --print）flag 是將 claude 從互動式 REPL 切換為腳本化非互動指令的開關。執行 claude "幫我寫一首五行詩" 而不加 -p，會進入互動式 TUI，顯示歡迎橫幅，並等待你輸入。執行 claude -p "幫我寫一首五行詩" 則直接將答案輸出到 stdout 並結束。

-p 實際做了什麼

具體而言，-p 讓 claude CLI：

1. 完全略過 TUI。 沒有歡迎橫幅、沒有狀態列、沒有按鍵處理器。
2. 從命令列（或 piped stdin）傳入的 prompt 執行一次 agentic loop。
3. 將最終 assistant 訊息輸出到 stdout，並回傳 exit code。
4. 退出，不等待後續輸入。

在 CI/CD 環境中，這是不可妥協的要求。CI runner 不附帶終端機、不接受鍵盤輸入，任何阻塞在 stdin 的行程都會被 runner 的掛鐘超時強制終止。在 CI 中不加 -p 呼叫 claude，不是在 runner 超時前一直掛著，就是把 TUI 的 ANSI escape 碼印進 build log 裡。

-p 從哪裡讀取 Prompt

-p flag 支援三種傳入 prompt 的方式：

• 位置參數 — claude -p "review the diff in git"。
• 管道 stdin — git diff | claude -p。
• 組合使用 — cat instructions.md | claude -p "依照 stdin 上的指示操作"。

CI pipeline 幾乎都採用管道 stdin 的形式，因為 prompt 是動態的（取決於當前的 commit、PR 編號或掃描結果）。

-p 不會做什麼

這是 Domain 3 題庫中測試頻率最高的陷阱。-p 是輸入/輸出管線的模式切換。它不會：

• 停用破壞性工具的權限提示。 需要確認的工具（檔案寫入、白名單以外的 shell 指令），仍然需要透過 .mcp.json、CLAUDE.md 或 --allowedTools / --permission-mode flag 預先核准權限。
• 繞過安全檢查。 Claude Code 的內建安全機制（例如拒絕執行明顯具破壞性的指令）完全不受影響。
• 改變模型、上下文視窗或 agentic loop。 它改變的是你與 Claude Code 溝通的方式，而不是 Claude Code 本身。
• 自動將完整 repository 作為上下文。 你仍然需要 CLAUDE.md、明確的檔案參數或工具呼叫，Claude 才能看到 prompt 字串以外的內容。

使用了 -p 卻忘記設定工具權限的 CI pipeline，在 Claude 第一次嘗試寫入檔案或執行 shell 指令時就會失敗。社群通過報告一再將此列為情境叢集中最值得掌握的陷阱。

--output-format json — Pipeline 消費的機器可讀結構化輸出

預設情況下，claude -p 以純文字輸出 assistant 的最終訊息到 stdout。這對人類可讀，對 pipeline 幾乎沒有用。--output-format json flag 將本次執行的輸出包裝在機器可讀的封包中，讓下游的 shell 腳本、GitHub Actions 步驟或建置工具能夠解析結構化欄位。

JSON 封包的結構

加上 --output-format json，Claude Code 每次執行會輸出一個 JSON 物件，通常包含：

• type — 識別此記錄為執行結果的標籤。
• session_id — Claude Code 的 session 識別碼（用於與日誌關聯）。
• result — 最終 assistant 訊息內容（原本會以純文字輸出的部分）。
• num_turns — 本次執行消耗了多少輪 agentic loop 迭代。
• total_cost_usd — 本次執行的大致計費成本。
• duration_ms — 掛鐘時間。
• is_error — 本次執行是否以錯誤狀態終止。

接下來，你的 pipeline 程式碼可以用 jq '.result' 取出答案、jq '.is_error' 控制後續步驟是否執行，或用 jq '.total_cost_usd' 執行預算管控。

封包不會改變什麼

這是 Domain 3 題庫中第二高頻的陷阱。--output-format json 改變的是封包外殼，而非 assistant 訊息本身的內容格式。result 欄位仍然包含 Claude 選擇輸出的內容——若你要求 Claude 給出散文，result 就是散文；若你要求 Claude 給出 JSON 陣列，result 就是 JSON 陣列字串。封包不是 schema 強制器，它只是一個運輸容器。

以為 --output-format json 能把散文答案自動轉換成結構化 JSON 欄位的 pipeline，是建立在誤解上的設計。若需要 assistant 的答案本身符合某個 schema，你需要 --json-schema（下一節說明）、帶 strict 模式的工具定義，或明確在 prompt 中約定 JSON 格式加驗證——而不是單靠 --output-format json。

替代格式

Claude Code 也支援 --output-format stream-json，以串流封包形式輸出（每個事件一個 JSON 物件，以換行分隔）。當 pipeline 需要逐輪觀察執行進度，而不是等到最後才收集單一結果時，這個格式就派上用場——例如一個會即時發布 PR 評論的機器人。stream-json 相當於 SDK 的 stream() 進入點的自動化版本。

--json-schema — 在 CI 環境中強制輸出 Schema 合規性

--json-schema 比 --output-format json 更深入一層。它指示 Claude Code 根據你在命令列或透過檔案參照提供的 JSON Schema 驗證最終答案。若答案不符合，Claude Code 會在內部重試、回傳錯誤，或兩者皆有——取決於你設定的嚴格程度。

何時需要 Schema 強制驗證

當 pipeline 步驟需要立即消費 Claude 的答案時，CI 中的 schema 強制驗證就非常重要。典型範例：

• PR review 步驟期望一個包含 file、line、severity 和 message 欄位的評論陣列。
• 測試生成步驟期望一份包含 path 和 content 的測試檔案寫入清單。
• 安全掃描摘要步驟期望一份包含 finding_id、risk 和 action 的分級清單。

在每一種形態中，下游步驟都無法容忍格式漂移。若 Claude 時而回傳陣列、時而回傳嵌有 JSON 區塊的散文摘要，pipeline 就會間歇性失敗——這是 CI 失敗中最難排查的類型。

將 --json-schema 與工具定義配合使用

為了最高的可靠性，可將命令列的 --json-schema 與 prompt 內部的 strict 工具定義組合使用。工具定義方式（帶有 strict: true 的 input_schema）能在 token 生成階段就將 Claude 的輸出限制在 schema 內；--json-schema CLI flag 則作為第二層驗證器，捕捉模型層偶然放過的漂移。雙重保護的設計在 CI 中是適當的，因為一次失敗的執行會驚動待命人員，而一次靜默通過的錯誤會污染生產環境。

CCA-F 對 --json-schema 的考點

預期會有考題要求你選出「在 CI pipeline 中保證 JSON 輸出符合某個 schema」的正確機制。錯誤答案會提出：

• 更強的系統提示（「在 CLAUDE.md 中告訴 Claude 永遠只回傳合法的 JSON」）。
• 單獨使用 --output-format json（封包，而非內容約束）。
• 事後以 jq 驗證，但沒有重試機制。

正確答案是將 --json-schema（或帶 strict: true 的工具定義）與 CI 友好的重試策略配合使用。研究資料中的痛點 pp-01——程式化約束優於 prompt 引導——在這裡直接適用。

Headless 模式 — 在無 TTY 環境中執行 Claude Code 以進行自動化

「Headless」是在沒有附加終端機的環境中執行 claude 的操作術語——這正好是 CI runner 提供的環境。Headless 模式由 -p（非互動）加上確保不觸發任何 TUI 功能的組合來啟用。Claude Code 設計上能偵測非 TTY 的 stdin/stdout 配對並自動調整輸出渲染，但 -p 仍是明確聲明「不要期待有人類」的正式約定。

為什麼不能單靠 TTY 偵測

有些 CI runner 會模擬 TTY（為了彩色日誌輸出、進度渲染），即使沒有人類附加其上。若沒有 -p，Claude Code 可能將偽 TTY 的存在解讀為啟動互動式 UI 的訊號，產生損壞的輸出或掛起。-p 是最保險的做法——無論 runner 的 TTY 模擬如何，它都明確聲明「非互動」。

Headless 環境中重要的環境變數

• ANTHROPIC_API_KEY — 身份驗證必需；透過 CI 的 secret 儲存注入。
• CLAUDE_CODE_WORKSPACE — 工作區根目錄；通常設為 checkout 目錄。
• 各種設定 flag 也有對應的環境變數形式，適用於不便在命令列傳入的動態或敏感設定。

完整的環境變數清單由 settings reference 管理；CCA-F 不考完整清單，但會考「環境變數是 CI pipeline 注入動態或敏感設定的方式，而非寫死在 .claude/settings.json 中」這個概念。

PR Review 自動化 — 讓 Claude 自動在 Pull Request 上發布分析評論

PR review 是生產環境中最常見的 Claude Code CI/CD pipeline 整合形態。典型流程如下：

1. PR 事件觸發後，CI runner checkout 該分支。
2. Runner 計算 diff（git diff origin/main...HEAD）。
3. Runner 將 diff 透過管道傳入 claude -p --output-format json，並附上 review prompt 和任何 CLAUDE.md 範圍設定。
4. Runner 從 JSON result 中取出結構化的 review 評論。
5. GitHub Actions（或 GitLab CI）步驟透過平台 API 將評論回傳到 PR 上。

為什麼這種形態是標準

CI 中的 PR review 將三個責任清楚分離：

• Claude Code 負責生成 review 內容。
• CI runner 負責收集 diff 並發布評論。
• PR 平台（GitHub、GitLab）負責渲染行內評論。

在這個形態中，Claude Code 不會直接呼叫 PR 平台——它只產出結構化輸出。這是正確的職責分離：同樣的 claude -p 呼叫在 GitHub Actions、GitLab CI 或本地開發者腳本中都能運作，只要 diff 被管道傳入、結構化評論由呼叫端處理即可。

限定 Claude 在 PR Review 中的關注範圍

PR review 的 prompt 通常指示 Claude 專注於：

• 正確性問題（bugs、邏輯錯誤）。
• diff 中浮現的安全疑慮。
• 違反專案規範的風格問題（規範透過 CLAUDE.md 載入）。
• 新增程式碼路徑缺少的測試。

CLAUDE.md 在這裡扮演關鍵角色。Claude Code 以 -p 在 CI 中執行時，仍然遵循 checkout 後工作區中的 CLAUDE.md 層級結構。寫入 CLAUDE.md 的專案規範、review 檢核清單和語言特定規則，會自動成為每次 CI review 的隱性標準，而不需要讓命令列 prompt 越來越臃腫。

PR Review 的 allowedTools 紀律

對於純 review 工作（不編輯檔案），PR review CI 任務通常將 Claude 限制在唯讀工具：Read、Grep、Glob、白名單範圍內的 Bash。寫入權限被明確排除，因為這個 pipeline 是在評論提案，而非修改它。權限模型透過 .mcp.json 和 settings 檔案強制執行，而不是靠期待 Claude 自律。

測試生成工作流程 — 在提交時觸發 Claude 撰寫測試

測試生成是 Claude Code CI/CD pipeline 整合的第二個標準形態。典型流程如下：

1. push 或 PR 事件觸發 pipeline。
2. 前一個步驟識別缺乏測試覆蓋的函式或檔案（透過覆蓋率報告，或差異感知的啟發式判斷）。
3. 以 claude -p 呼叫，prompt 中指定未測試的檔案、專案的測試規範（來自 CLAUDE.md），以及撰寫測試的指示。
4. Claude Code 在沙盒路徑內啟用 Read 和 Write 工具，產出測試檔案。
5. Pipeline 執行新增的測試；若通過，則開一個包含這些變更的 PR。

為什麼測試生成天生適合 CI

與互動式編碼（開發者在緊密耦合的功能程式碼上除錯）不同，撰寫測試是高量、規律性強、天然適合腳本化的工作。人類樂於審查只包含新測試的 PR；出錯的代價低（測試要嘛通過、要嘛失敗、要嘛被修改）。

CLAUDE.md 錨定測試風格

專案層級的 CLAUDE.md 若記錄了「我們使用 pytest、fixture 放在 tests/conftest.py、外部 HTTP 以 responses mock」，就能讓測試生成 CI 的輸出保持一致。沒有 CLAUDE.md 錨定，同樣的 prompt 在不同次執行時產出不同的測試風格——讓 reviewer 浪費時間在風格問題上。這是 CI 中 pp-08 痛點的對應：缺失或龐雜的 CLAUDE.md 指令會產出不可靠的輸出。

以允許路徑限制寫入範圍

對於測試生成，Claude Code 允許寫入——但只限於 tests/ 目錄。寫入範圍的強制執行通常透過權限模型實現，而不是信任 Claude 自行待在它應該待的地方。CCA-F 考試獎勵這個原則：將工具允許清單的爆炸半徑限制在 CI 任務的實際所需，永遠不要更多。

安全掃描整合 — 用 Claude 摘要靜態分析結果

靜態分析工具（Semgrep、CodeQL、Bandit、Brakeman 等）會產出大量原始結果，人類難以逐一分類。Claude Code CI/CD pipeline 整合將這些原始串流轉化為分級整理的散文說明摘要。

典型流程

1. 安全掃描步驟執行後，以 JSON、SARIF 或 CSV 格式輸出結果。
2. 結果 artifact 被管道傳入或作為輸入參照給 claude -p --output-format json --json-schema <triage-schema>。
3. Prompt 指示 Claude 依根因分組結果、過濾已知的假陽性（可選，對照 repo 中的 .false-positive-allowlist.json），並輸出包含嚴重程度、建議行動和簡短說明的分級清單。
4. Pipeline 將分類摘要發布到 PR 或安全儀表板。

為什麼不讓 Claude 直接執行掃描器

掃描器是有數十年調校積累的專門工具；Claude 不是替代品。Claude 帶來的價值是詮釋——將密集的 SAST 輸出翻譯成散文、將相關結果分組，並優先引導人類注意力到風險最高的項目。這個分工方式與 PR review 形態相同：Claude 不是在執行分析，而是在解釋分析。

掃描摘要的預算紀律

大型掃描可能產出數千個結果。將全部結果直接餵給 Claude Code，既昂貴又浪費——Claude 無法有效推理一萬個結果，而且大部分結果接近重複。正確的模式是：

• 在呼叫 Claude 之前，預先過濾掃描輸出，去重並分桶。
• 設定上限，限制每次執行摘要的結果數量。
• 當量大時分批摘要，每次只餵一個桶。

這預先觸及了後面成本管控的章節，但值得在此明確指出：不要把 Claude Code 當作原始結果的轉換器。要把它當作在已預先處理的輸入上運作的分類層。

環境設定 — CI Agent 的 CLAUDE.md 與 .mcp.json

Claude Code CI/CD pipeline 整合繼承了互動式 Claude Code 使用的相同設定機制——CLAUDE.md 用於散文指令、.mcp.json 用於 MCP server 接線、.claude/settings.json 用於模型/工具設定——但需要套用兩個 CI 特有的紀律。

CI 中的 CLAUDE.md

CI runner 在 checkout 後的工作目錄，包含已提交到 repository 的所有 CLAUDE.md 檔案。Claude Code 以 headless 模式執行時，仍然會遍歷 CLAUDE.md 層級結構：全域 CLAUDE.md 位於 ~/.claude/CLAUDE.md（CI runner 上幾乎不存在）、專案根目錄的 CLAUDE.md，以及目錄範圍的 CLAUDE.md。

CI 特有的 CLAUDE.md 模式：

• 將 CI 相關規範（測試框架、review 檢核清單、安全防護規則）保留在已提交的專案 CLAUDE.md 中，讓 CI 呼叫自動能看到這些設定。
• 使用 @import 將 CI 相關片段（@.claude/ci-review.md）與純互動式內容分開。
• 避免將開發者本地規範提交到專案 CLAUDE.md——那些應該放在使用者範圍的 CLAUDE.md 中，CI runner 不會有這個檔案。

CI 中的 .mcp.json

專案根目錄的 .mcp.json 聲明 Claude Code 可以使用的 MCP server。在 CI 中，原則應該是最小化：

• 只啟用 CI 任務實際需要的 MCP server（通常是 git，有時是用於發布 PR 評論的 GitHub MCP server，極少需要內部服務 MCP）。
• 不要在 CI 執行中啟用實驗性 MCP server；CI 不是除錯整合的場所。
• MCP server 憑證使用 CI runner secret（而非提交的檔案）。

--strict-mcp-config Flag

某些 Claude Code 版本支援 --strict-mcp-config flag，若 .mcp.json 聲明的 server 在執行時無法解析，則拒絕啟動。在 CI 中，這是一個特性，而不是麻煩——MCP server 設定錯誤應該讓任務明顯失敗，而不是靜默地以缺少一半功能的狀態開始執行。CCA-F 考試不考具體的 flag 拼寫，但會考「CI 執行應偏好嚴格設定，而非靜默降級」這個原則。

Exit Code 與錯誤處理 — Pipeline 失敗從 Claude Code 傳播出去

CI/CD pipeline 的一個階段是只有一個輸出用於流程控制的黑盒子：exit code。零代表成功，非零代表失敗，runner 只根據這個整數決定後續動作。Claude Code CI/CD pipeline 整合對 pipeline 的價值，完全取決於它的 exit code 能否正確反映步驟是否成功。

Exit Code 慣例

Claude Code 遵循標準 Unix exit code 慣例：

• 0 — 執行成功；agentic loop 正常終止（end_turn），未發生錯誤。
• 非零 — 執行失敗，原因可能是：身份驗證錯誤、工具權限被拒、schema 驗證失敗（啟用 --json-schema 時）、迭代上限超出、Anthropic API 錯誤，或 Claude 內部發出明確的錯誤訊號。

為什麼 Exit Code 紀律很重要

在互動式使用中，Claude Code 執行失敗是顯而易見的——人類在螢幕上看到錯誤訊息。在 CI 中，失敗的執行若回傳 exit code 0，會靜默地污染 pipeline：下游步驟（發布評論、開 PR、部署建置）繼續執行，好像一切正常。一個通過但輸出損壞的 pipeline，是 CI 失敗中最糟糕的類型。

反過來說，成功的執行若回傳非零 exit code，會不必要地停止 pipeline，浪費開發者時間在假警報上。

解析 JSON 封包中的 is_error 欄位

以 --output-format json 執行時，exit code 是一個訊號，JSON 封包內的 is_error 欄位是第二個訊號。健全的 CI wrapper 需要同時檢查兩者：

OUTPUT=$(claude -p --output-format json "..." )
if [ $? -ne 0 ]; then
  echo "claude returned non-zero exit code"
  exit 1
fi
if [ "$(echo "$OUTPUT" | jq -r '.is_error')" = "true" ]; then
  echo "claude returned is_error=true in envelope"
  exit 1
fi

縱深防禦——exit code 加上封包欄位——能同時捕捉硬性失敗（行程錯誤）和軟性失敗（Claude 進入內部錯誤狀態，但行程仍以 0 退出）。

將 Claude 的結構化錯誤傳播給 Runner

若 Claude 以 --json-schema 執行，最終輸出驗證失敗，pipeline 需要確定性的失敗。正確的模式是：在 claude 層驗證 schema，在封包中設置 is_error: true，輸出非零 exit code。CI wrapper 再以 runner 原生的方式傳播失敗（GitHub Actions 的 ::error:: 標註、GitLab CI 的失敗階段、Jenkins 的不穩定建置）。

CI 中的成本管控 — 限制範圍、快取與 Token 使用預算

CI 執行 Claude Code 的頻率很高。一個每週有 100 個 PR、每個 PR 都觸發 Claude 驅動 review 的 repository，每週至少有 100 次 agentic loop 執行。缺乏紀律，Claude Code CI/CD pipeline 整合可能成為 Anthropic 帳單上最大的單一項目。成本管控不是加分項目；它是設計需求。

範圍限制

最便宜的 token 是你從來不需要發送的那個。在 CI 中呼叫 Claude Code 之前，縮小輸入範圍：

• 只 review 有變更的檔案。 管道傳入 diff，而不是整個程式碼庫。
• 只摘要超過嚴重程度門檻的結果。 跳過雜訊。
• 只為新增或有變更的函式生成測試。 其餘的不要動。
• 在呼叫 Claude 之前，先用輕量工具預先過濾。 Grep、jq 和幾行 awk 就能剔除 80% 的無關輸入。

快取

在底層平台支援 prompt 快取的情況下，長期穩定的前言（CLAUDE.md 內容、review 檢核清單、安全指引）在多次執行之間能夠低成本快取。確切的快取機制在 Claude 平台內部，超出 CCA-F 的考試範圍（考試指南附錄明確排除「prompt 快取實作細節，只需知道它存在」），但「穩定的前言比揮發性前言成本更低」這個架構事實是可考的。

每次執行的 Token 預算

--output-format json 在封包中輸出 total_cost_usd 和 token 計數。強制執行每次執行預算上限的 CI wrapper 很簡單：

COST=$(echo "$OUTPUT" | jq -r '.total_cost_usd')
if (( $(echo "$COST > 0.50" | bc -l) )); then
  echo "claude run exceeded $0.50 budget: $COST"
  # alert, tag, or fail accordingly
fi

在每次 Push 還是每次 Merge 時執行 Claude Code

常見的成本控制手段是決定何時執行 Claude Code。在每次 push（PR 分支的每次 git push）時執行，能提供快速反饋，但成倍增加帳單。只在 PR 建立、PR 準備 review 或 PR 合併時執行，能大幅削減支出。CCA-F 考試不要求特定的觸發策略，但會考「CI 觸發策略是成本控制手段，正確答案往往是在更少的事件上觸發，而不是在每個事件上觸發」這個原則。

Plan Mode 在 CI 中的應用 — 預設答案是否

Plan mode（任務 3.4）是讓 Claude 在執行之前先產出計畫供批准的功能。在互動式使用中，plan mode 常常是高風險或模糊任務的正確選擇。在 CI 中，預設答案恰恰相反：不要在 CI 中使用 plan mode。

為什麼 Plan Mode 會讓 CI 中斷

Plan mode 產出一份提案計畫，並在執行之前等待批准。在非互動的 CI 環境中，沒有人類可以批准；執行要嘛掛起等待，要嘛 pipeline 超時。這是社群痛點 pp-06（「plan mode 不總是更安全的選擇」）的具體體現——plan mode 在非互動 pipeline 中是錯誤的選擇，而不是更安全的選擇。

罕見的例外情況

有邊緣案例，CI 式的自動化確實想要產出計畫但不執行——例如，某個 pipeline 階段只是準備一份計畫，供人類在另一個工具中非同步審查。在這種罕見情況下，Claude Code 可以以 plan mode flag 呼叫，但 pipeline 必須從封包中解析出計畫，並明確地不等待批准。這是一個小眾形態；在 CCA-F 考試當天，「CI 中的 plan mode」的預設答案就是「不要啟用它」。

CI 步驟內的迭代精煉與多 Agent 模式

兩個相鄰的任務說明，在 CI 任務超過一次性轉換時會滲入任務 3.6：任務 3.5（迭代精煉）和任務 1.2/1.3（多 agent 編排）。兩者在 CI 中都有用——但都需要 CI 特有的紀律才能保持成本安全。

單次執行內的迭代精煉

生成測試或撰寫程式碼的 CI 步驟，可能需要在單次 claude -p 呼叫內迭代——撰寫、執行、觀察失敗、修正、重新執行——直到測試通過或迭代上限觸發。Claude Code 內部的 agentic loop 原生處理這個流程：Claude 呼叫 Write，然後 Bash 執行測試，觀察失敗，呼叫 Edit 修正，再次執行，如此循環直到測試通過。

CI 特有的迭代上限

CI 步驟的迭代上限應該嚴格——通常十輪以下——因為無界限的 CI 步驟會搶占後續所有任務的 runner 時間。同時在 runner 層面設置掛鐘超時（例如 GitHub Actions 步驟的 timeout-minutes）。

停止訊號：重複狀態偵測

若 Claude 不斷提出相同的 Edit → Bash 循環而沒有進展，代表迴圈卡住了。Bash 的結構化錯誤回應（帶有可行動 stderr 的非零 exit code）加上 Claude 自身的模式辨識，通常能打破這個循環，但保險的 CI 任務會在重複相同的工具呼叫時直接退出。

Subagent 何時屬於 CI 步驟

Claude Code CI/CD pipeline 整合可以將工作委派給 subagent 以進行平行化——各自 review 每個有變更的檔案、獨立摘要每個掃描結果桶、按模組生成測試。CI 特有的紀律是：

• 保持 subagent 數量少，因為每個 subagent 會啟動自己的 agentic loop 並倍增成本。
• 只在平行化實際能減少掛鐘時間（runner 有平行容量）或需要上下文隔離時，才使用 subagent。
• 監控所有 subagent 的累計成本，而不是單一 subagent 的成本。

CI 的情境叢集可能間接提及多 agent 形態——將它們識別為部署在任務 3.6 情境下的任務 1 模式。

常見考試陷阱

Claude Code CI/CD pipeline 整合是 Domain 3 中陷阱密度最高的主題之一。五種模式在題庫中反覆出現。

陷阱一：以為 -p 停用了安全檢查或權限

-p / --print 是輸入/輸出管線的模式切換——僅此而已。它不會停用工具權限提示、拒絕執行破壞性指令的安全機制，或任何其他保護。倚賴單獨的 -p 來「讓 Claude 隨心所欲」的 CI 任務，在 Claude 第一次嘗試寫入白名單以外的位置時就會失敗。正確的模式是：-p 用於非互動，加上透過 .mcp.json、settings.json 或 --allowedTools flag 進行明確的權限設定。

陷阱二：期待 --output-format json 能約束答案的格式

--output-format json 改變的是封包外殼。封包內的 .result 欄位仍然包含 Claude 生成的任何內容——要求散文就包含散文，要求 JSON 陣列就包含 JSON 陣列字串。對內容的 schema 強制需要 --json-schema、帶 strict: true 的工具定義，或兩者同時使用。單靠 --output-format json 想得到 schema 安全的輸出，是等著爆發的 pipeline bug。

陷阱三：在非互動環境中啟用 Plan Mode

Plan mode 等待批准。CI 沒有人類可以批准。Pipeline 掛起直到超時終止它。Plan mode 是互動式專屬功能；在 CI 中的預設答案是「不要啟用它」。將 plan mode 框架為 CI 中安全增強手段的干擾選項是錯的。

陷阱四：忽略 Exit Code 或 is_error 封包欄位

健全的 CI wrapper 同時檢查行程 exit code 和 JSON 封包中的 is_error 欄位。軟性失敗（Claude 遭遇內部錯誤，但行程仍然乾淨地退出）和硬性失敗（行程層級的崩潰）都是可能的情況；只檢查一個訊號就會漏掉一半的失敗模式。社群通過報告將「只看單一訊號的錯誤處理」列為常見的「差一點卻選錯」模式。

陷阱五：將 Secret 或完整上下文提交進已版本控管的設定中

ANTHROPIC_API_KEY、MCP server 憑證和任何其他 secret，都應該放在 CI runner 的 secret 儲存中——永遠不要放在已提交的 CLAUDE.md、.mcp.json 或 .claude/settings.json 中。此外，不要假設 CI 執行會自動將整個 repository 作為 Claude 的上下文；明確管道傳入 diff 或指定檔案，既是為了安全（最小必要揭露），也是為了成本（最小必要 token）。

練習錨點

Claude Code CI/CD pipeline 整合是情境叢集六的錨點。考試當天最常出現的兩個錨點子情境如下。

失敗的 PR Review Pipeline

情境形態：一個團隊將 claude 接入 GitHub Actions 的 PR 事件。執行間歇性掛起、在 build log 中產出 ANSI escape 碼噪音，或在 Claude 嘗試編輯檔案時因權限錯誤失敗。考題要求你找出架構層面的修正。預期答案涉及加入 -p、縮小工具權限，通常還需要將 CLAUDE.md 內容分割成 CI 範圍的片段。干擾選項會提出「增加超時」（治標不治本）、「使用 plan mode」（讓掛起更嚴重），或「用 -p 停用安全檢查」（誤述 -p 的作用）。

Schema 漂移的測試生成任務

情境形態：一個測試生成任務穩定運行了幾個月。它突然開始失敗，原因是 Claude 偶爾在測試檔案內容旁邊回傳散文，讓下游的檔案寫入步驟出錯。考題要求你永久修復這個問題。正確答案是在 --output-format json 之上疊加 --json-schema（或帶 strict: true 的工具定義）；干擾選項會提出加強 prompt（「在 CLAUDE.md 中更強調只允許 JSON」）。程式化約束 vs. prompt 約束的痛點（pp-01）在這裡被直接考驗——正確答案是程式化約束，而非 prompt 約束。

準備完整情境叢集

CI 情境叢集將 Domain 2 的工具設計（Claude 可以呼叫哪些工具）、Domain 3 的設定（CLAUDE.md、flags、permissions）、Domain 4 的結構化輸出（schema 強制驗證）和 Domain 5 的可靠性（exit code 傳播、錯誤分類）交織在一起。把 CI 情境純粹當作 Domain 3 題目來準備，會漏掉每道各差一兩分的跨 Domain 題目。

白話說明

Claude Code 在 CI/CD pipeline 中是一個非常具體的工程問題。三個日常情境能讓它的運作機制立刻變得直觀。

滷肉飯攤的出單機 — -p 是內場出票的開關

想像一家夜市滷肉飯攤有兩種點餐方式。堂食（互動式 Claude Code）時，客人直接對老闆說想吃什麼，老闆問清楚飯要多、湯要不要、還有沒有其他加點，煮好再端出來。外送（claude -p）時，點餐 App 把訂單印在出單機上，老闆拿著票按票做，做完放在保溫箱讓外送員取走。沒有問答、沒有確認、不等客人改主意。-p flag 就是外送出單機——它告訴老闆「這是一張訂單，不是對話，做完就走」。就像外送不代表老闆可以不管食品安全規定（權限與安全機制照樣運作），-p 也只是改變溝通方式，而不是取消任何保護機制。一個忘記加 -p 的 CI pipeline，就像把外送訂單印到堂食端菜單上，讓 runner 在一張永遠不會開口說話的桌位旁乾等。

貨運箱與海關查驗 — --output-format json vs --json-schema

貨運公司可以把任何東西裝進標準貨櫃（封包外殼）——標準尺寸、標準標籤、標準文件。這是 --output-format json。貨櫃的外觀一致；裡面的貨物是托運人塞進去的任何東西。如果收貨方期待三十箱牛軋糖，結果收到三十箱廢鐵，封包沒有幫到任何忙——外表看起來沒問題，裡面全錯了。--json-schema 是海關開箱查驗——在貨車離港之前打開貨櫃，確認貨物符合申報清單。不符合就扣押退回。只靠 --output-format json 的 CI pipeline，是那個只看貨櫃外觀不開箱驗貨的收貨端；Claude 哪天把散文當牛軋糖裝進去，下游步驟拆箱就爆炸了。將 --output-format json 與 --json-schema 搭配，才是出貨又驗貨的完整配置。

工廠的緊急停止按鈕 — Exit Code 是 Runner 與 Claude Code 之間的唯一訊號線

工廠產線上每台機器都有一條故障訊號線接回主控台。任何一台機器的訊號線亮起，整條線就停機。每台機器內部有幾百個感測器——溫度、震動、壓力——但主控台只看那一條線。CI pipeline 的運作方式相同：每個步驟是一台機器，exit code 是故障訊號線，runner 是主控台。一個不管內部發生了什麼、永遠對訊號線回報「我沒事」的 Claude Code 步驟，就是一台壞掉的機器——產線繼續跑，成品全是瑕疵品。--output-format json 加上 is_error 欄位，相當於在故障訊號線旁多拉一條溫度感測線，讓 CI wrapper 能夠交叉比對——即使主要訊號線忘了亮起，也能正確停機。健全的 CI 整合是一台如實告知主控台全部情況的機器，而不是只報平安的機器。

考試當天選用哪個類比

• 關於 -p 與非互動模式的題目 → 滷肉飯攤出單機類比。
• 關於 **--output-format json vs --json-schema**的題目 → 貨運箱與海關查驗類比。
• 關於 exit code 與 pipeline 傳播的題目 → 工廠緊急停止按鈕類比。

FAQ — Claude Code CI/CD 前六大問題

-p flag 實際做了什麼，為什麼在 CI 中是必要的？

-p（長形式 --print）是 Claude Code 的模式切換，停用互動式 TUI 並執行單次非互動呼叫。沒有 -p，claude 會啟動互動式 REPL 並等待鍵盤輸入——CI runner 永遠不會提供這樣的輸入，因此行程不是掛到 runner 的掛鐘超時強制終止，就是把 TUI escape 碼印進 build log。加上 -p，Claude 從命令列或 stdin 的 prompt 執行一次 agentic loop，將最終結果輸出到 stdout，並以標準 exit code 退出。-p 是 CCA-F 任務 3.6 中測試頻率最高的 flag；兩種拼寫和精確語義都要記住。

-p 會停用權限檢查或安全機制嗎？

不會。-p 改變的是輸入/輸出管線——TUI 被跳過，輸入來自參數或 stdin，輸出送到 stdout。它不會停用工具的權限模型（白名單以外的檔案寫入和 shell 指令仍然需要預先核准的權限），不會停用 Claude 拒絕執行明顯破壞性指令的機制，也不會繞過任何安全檢查。權限透過 .mcp.json、.claude/settings.json、--allowedTools flag 或 --permission-mode flag 另行控制。期待 -p 授予「隨意執行」特權的 CI 任務，在工具第一次跨越權限邊界時就會失敗。

--output-format json 和 --json-schema 有什麼差異？

--output-format json 將每次 Claude Code 執行包裝在機器可讀的 JSON 封包中——包含 result、session_id、num_turns、total_cost_usd、is_error 等元資料欄位，讓 CI 腳本能用 jq 解析執行元資料。它不會約束 .result 內部 assistant 答案的格式；Claude 生成了什麼就放什麼進去，以字串形式存放。--json-schema 是獨立的 flag，針對使用者提供的 JSON Schema 驗證最終答案；若答案不符合，執行失敗（或重試，取決於設定）。兩個 flag 相輔相成：--output-format json 提供封包，--json-schema 約束貨物。schema 安全的 CI pipeline 同時使用兩者，或將 --json-schema 與帶 strict: true 的工具定義搭配，實現雙重保護。

我應該在 CI pipeline 中啟用 plan mode 嗎？

幾乎絕對不要。Plan mode 產出一份提案計畫，並在執行之前等待人類批准；CI 按定義是非互動的、沒有人類可以批准，因此 pipeline 會掛起直到 runner 的掛鐘超時終止它。Plan mode 是為互動式高風險或模糊任務設計的。罕見的例外是某個 CI 階段明確想要產出計畫供非同步人工審查，此時 pipeline 必須從封包中解析計畫而不等待批准。在 CCA-F 上，任何以「更安全」為由推薦在 CI 中啟用 plan mode 的答案，幾乎肯定是錯的——它與非互動執行根本不相容。

我的 CI wrapper 應該如何判斷 Claude Code 執行是否成功？

檢查兩個訊號。第一，行程 exit code：零代表成功，非零代表 CLI 本身出錯（身份驗證、API 失敗、權限被拒、啟用 --json-schema 時的 schema 驗證失敗、迭代上限超出）。第二，--output-format json 封包內的 is_error 欄位：true 表示 Claude 遭遇內部錯誤狀態，即使行程乾淨地退出。健全的 CI wrapper 在任一訊號顯示失敗時就讓步驟失敗。只檢查 exit code，會漏掉 Claude 在封包中浮現問題但仍以 0 退出的軟性失敗；只檢查封包，會漏掉 CLI 層級的硬性錯誤。兩者合起來，才是 Claude Code CI/CD pipeline 整合的標準可靠性模式。

如何讓 Claude Code 在 CI 中的成本維持在可控範圍？

四個槓桿，合併使用。第一，縮小輸入範圍——管道傳入 diff 而非完整 repo、預先過濾掃描結果、只針對有變更的函式。第二，在更少的事件上觸發——PR 建立和 PR 準備 review，而不是每次 push。第三，透過解析 JSON 封包中的 total_cost_usd 強制執行每次執行的 token/成本預算，超出門檻時失敗或發出警報。第四，對 Claude Code 內部的 agentic loop 設置嚴格的迭代上限，讓單次執行無法失控。穩定前言（CLAUDE.md 內容、review 檢核清單）的 prompt 快取進一步降低成本，但屬於平台層而非 flag 層。統一原則：最便宜的 token 是你從來不需要發送的那個。

延伸閱讀

• Integrate Claude Code into CI/CD pipelines: https://docs.anthropic.com/en/docs/claude-code/ci-cd
• Claude Code settings reference: https://docs.anthropic.com/en/docs/claude-code/settings
• Claude Code features overview: https://docs.anthropic.com/en/docs/claude-code/overview
• CLAUDE.md configuration: https://docs.anthropic.com/en/docs/claude-code/claude-md
• Plan mode and iterative refinement: https://docs.anthropic.com/en/docs/claude-code/plan-mode
• Community pass report (893/1000): https://medium.com/@kishorkukreja/i-passed-anthropics-claude-certified-architect-foundations-exam-with-a-score-of-893-1000-2206c27efd6c

Related ExamHub topics: Plan Mode vs Direct Execution, Built-in Tools Selection and Application, Iterative Refinement for Progressive Improvement, Batch Processing Strategies.