Claude Code CI/CD 統合

Claude Code の CI/CD パイプライン統合は、ドメイン3（Claude Code の設定とワークフロー、CCA-F 試験の20%）におけるタスクステートメント 3.6「Claude Code を CI/CD パイプラインに統合する」の焦点であり、各受験で出題される4つのシナリオクラスターの中心でもある――すなわち、6つ中4つにランダムで選ばれる6番目のシナリオクラスター「継続的インテグレーションへの Claude Code 活用」の核心に位置する。2026年4月の試験で893/1000点を取ったコミュニティの合格レポートは、-p フラグを「ドメイン3全体の問題プールで最も頻繁に試験で問われる Claude Code の設定詳細」と表現している。Claude Code の CI/CD パイプライン統合を習得することは、合格スコアへの選択事項ではなく、必須要件だ。

本学習ノートは、タスク 3.6 のすべてのアウトラインを網羅するアーキテクチャレベルのウォークスルーである。CI/CD パイプラインにおける Claude Code の位置づけ、-p / --print フラグの正確なセマンティクス、--output-format json エンベロープ、--json-schema によるスキーマ強制、TTY なしのヘッドレスモード、プルリクエストレビューの自動化、コミット時のテスト生成、セキュリティスキャンの要約、CI エージェントコンテキストのための CLAUDE.md と .mcp.json の配置、パイプラインの失敗伝播のための終了コードのセマンティクス、コスト管理の規律を取り扱う。各セクションで、Claude Code の CI/CD パイプライン統合を試験シナリオおよびフラグを暗記した受験者とアーキテクチャを理解した受験者を分ける具体的な誤答選択肢に結びつける。

CI/CD 統合の概要 — 自動化パイプラインにおける Claude Code の位置づけ

CI/CD パイプラインとは、すべてのコード変更に対して実行されるステージのスクリプト化されたシーケンスである。チェックアウト、ビルド、静的解析、テスト、パッケージ、デプロイがその構成要素だ。Claude Code の CI/CD パイプライン統合とは、claude CLI をこれらのステージの内部から呼び出すことで、Claude がターミナルに座った開発者としてではなく、決定論的な入力と出力を持つ非インタラクティブなプロセスとして自動化ステップに参加することを意味する。

Claude Code の CI/CD パイプライン統合は、5つの典型的な自動化形状にまたがる。

• プルリクエストレビュー ― Claude が差分を読み、構造化されたコメントを投稿する。
• テスト生成 ― Claude が新しく追加されたコードパスのテストを書く。
• セキュリティスキャンの要約 ― Claude が SAST の生の出力を実行可能な文章に変換する。
• ドキュメントのメンテナンス ― Claude がシグネチャが変更されたとき README やドキュメントを更新する。
• リリースノートの下書き ― Claude がマージされた PR のリストをチェンジログに変換する。

これら5つの形状はすべて同じ機械的な要件を共有している。claude プロセスは TTY なしで実行しなければならず、人間に問い合わせてはならず、機械可読な出力を返さなければならず、パイプラインがエラー時に失敗するように終了コードを伝播しなければならない。これらの要件は1つのキーフラグ――-p――と CCA-F が確認の目で見ることを期待するコンパニオンフラグの小さなクラスターに集約される。

CCA-F が CI/CD を独自のシナリオとして扱う理由

Claude Code の CI/CD パイプライン統合は、ドメイン3の中で独自のシナリオクラスターを持つ唯一のトピックである。試験ガイドは6つのシナリオの1つ――「継続的インテグレーションへの Claude Code 活用」――をこの機能面に専用で割り当てており、このシナリオを抽出した各受験で3〜5問のクラスターが同じ呼び出しを繰り返し取り上げる。このトピックを「単なる CLI フラグ」として省略した受験者はシナリオ全体を失う。コミュニティの2026年4月の合格レポートは、-p の認識を CI シナリオの合否を左右する概念として明示的に挙げている。

-p / --print フラグ — スクリプト化された用途のための非インタラクティブ単発実行

-p（--print とも表記）フラグは、claude をインタラクティブな REPL からスクリプト化された非インタラクティブなコマンドに切り替えるスイッチである。-p なしで claude "write me a haiku" を実行すると、インタラクティブな TUI が起動し、バナーが表示され、入力を待つ。claude -p "write me a haiku" を実行すると、答えを stdout に出力して終了する。

-p が実際に行うこと

具体的には、-p によって claude CLI は以下を行う。

1. TUI を完全にスキップする。 バナーなし、ステータス行なし、キーストロークハンドラーなし。
2. コマンドライン（または stdin にパイプ）で渡したプロンプトから agentic loop を1回実行する。
3. 最終的なアシスタントメッセージを stdout に出力し、終了コードを返す。
4. 追加入力を待たずに終了する。

CI/CD のコンテキストでこれは交渉の余地がない。CI ランナーはターミナルを接続せず、キーボード入力を受け付けず、stdin でブロックするプロセスをランナーのウォールクロックタイムアウトで強制終了する。-p なしで CI 環境で claude を呼び出すと、ランナーのタイムアウトが来るまでハングするか、ビルドログに TUI エスケープコードを出力してしまう。

-p がプロンプトを読み取る場所

-p フラグはプロンプトを3つの方法のいずれかで受け取る。

• 位置引数 ― claude -p "review the diff in git".
• パイプされた stdin ― git diff | claude -p.
• 組み合わせ ― cat instructions.md | claude -p "follow the instructions on stdin".

CI パイプラインはほとんどの場合、パイプされた stdin の形式を使う。プロンプトが動的（現在のコミット、PR 番号、またはスキャン出力に依存する）であるためだ。

-p が行わないこと

これはドメイン3のプールで最も頻繁に試験で問われるトラップだ。-p は入出力の配管のためのモードスイッチである。以下のことは行わない。

• 破壊的ツールに対する権限プロンプトを無効化しない。 確認が必要なツール（許可リスト外のファイル書き込み、シェルコマンド）は引き続き .mcp.json、CLAUDE.md、または --allowedTools / --permission-mode フラグで事前承認された権限が必要となる。
• 安全チェックをバイパスしない。 Claude Code のビルトイン安全レール（明らかに破壊的なコマンドの実行拒否など）は影響を受けない。
• モデル、context window、または agentic loop を変更しない。 claude との対話方法を変えるのであって、claude 自体が何であるかを変えるわけではない。
• リポジトリ全体をコンテキストとして自動的に含まない。 Claude が promptの文字列以外の何かを見るためには、CLAUDE.md、明示的なファイル引数、またはツール呼び出しが引き続き必要だ。

-p を使うが tool 権限の設定を忘れた CI パイプラインは、Claude がファイルを書き込もうとするか、シェルコマンドを実行しようとした最初の時点で失敗する。コミュニティの合格レポートはこれをシナリオの中で最も高い価値を持つトラップとして繰り返し挙げている。

--output-format json — パイプラインが消費できる機械可読な構造化出力

デフォルトでは、claude -p はアシスタントの最終テキストメッセージを平文として stdout に出力する。人間が読むには良いが、パイプラインにとってはほぼ無意味だ。--output-format json フラグは、実行の出力を機械可読なエンベロープでラップし、ダウンストリームのシェルスクリプト、GitHub Actions ステップ、またはビルドツールが構造化フィールドを解析できるようにする。

JSON エンベロープの形状

--output-format json を指定すると、Claude Code は1回の実行ごとに通常以下を含む単一の JSON オブジェクトを出力する。

• type ― レコードを実行結果として識別するタグ。
• session_id ― Claude Code セッション識別子（ログとの相関に有用）。
• result ― 最終アシスタントメッセージのコンテンツ（他の方法では平文として出力されるもの）。
• num_turns ― 実行が消費した agentic loop のイテレーション数。
• total_cost_usd ― 実行の概算請求コスト。
• duration_ms ― ウォールクロック時間。
• is_error ― 実行がエラー状態で終了したかどうか。

パイプラインコードは jq '.result' で答えを抽出し、jq '.is_error' で後続のステップをゲートし、jq '.total_cost_usd' でバジェットを強制できる。

エンベロープが変えないもの

これはドメイン3のプールで2番目に頻繁に試験で問われるトラップだ。--output-format json はエンベロープを変えるが、アシスタントメッセージ自体のコンテンツの形式は変えない。result フィールドには Claude が生成したものがそのまま入る。平文を求めた場合は result に平文が含まれ、JSON 配列を求めた場合は result に文字列として JSON 配列が含まれる。エンベロープはスキーマ強制器ではなく、コンテナだ。

--output-format json だけで平文の答えが構造化 JSON フィールドに変換されると思い込んでパイプラインを設計することは、誤解に基づいた設計だ。アシスタントの答え自体をスキーマに準拠させる必要がある場合は、--json-schema（次のセクションで解説）、strict モードの tool use、または明示的なインプロンプトの指示とバリデーションが必要だ。--output-format json だけでは足りない。

代替フォーマット

Claude Code は、ストリーミングエンベロープ（改行区切りの1イベントあたり1JSON オブジェクト）のための --output-format stream-json もサポートしている。これは単一の結果をまとめて収集する代わりに、実行のターンごとに観察したいパイプラインに適している。stream-json は SDK の stream() エントリーポイントに相当する自動化版であり、下流で何かがリアルタイムで進捗を監視している場合（例：インクリメンタルな PR コメントを投稿するボット）に適している。

--json-schema — CI コンテキストでの出力スキーマ準拠の強制

--json-schema は --output-format json よりもう一層深い。コマンドラインまたはファイル参照で提供した JSON Schema に対して最終答えをバリデーションするよう Claude Code に指示する。答えが準拠しない場合、設定した厳格さに応じて Claude Code は内部でリトライするか、エラーを返すか、あるいはその両方を行う。

スキーマ強制が必要な場面

CI でのスキーマ強制は、パイプラインステップが答えを即座に消費する場合に重要となる。典型的な例は以下のとおりだ。

• PR レビューステップが file、line、severity、message を持つコメントの配列を期待する。
• テスト生成ステップが path と content を持つテストファイル書き込みのリストを期待する。
• セキュリティスキャンサマライザーが finding_id、risk、action を持つトリアージされたリストを期待する。

これらの形状のいずれにおいても、ダウンストリームのステップは平文のドリフトに耐えられない。Claude が配列を返したり、その中に JSON ブロックが埋め込まれた散文の要約を返したりする場合、パイプラインが断続的に壊れる ― CI 障害の中で最悪のクラスだ。

--json-schema と tool use の組み合わせ

最高の信頼性のために、CLI 境界での --json-schema と、プロンプト自体での厳格な tool use を組み合わせること。tool use アプローチ（入力スキーマに strict: true を持つ Claude ツール）は、トークン生成時に Claude の生成をスキーマに制約することを保証する。--json-schema CLI フラグは、モデルレイヤーがどういうわけか通過させたドリフトをキャッチする第二段階のバリデーターとして機能する。CI では二重防護の設計が適切だ。失敗した実行はオンコールを起こし、誤通過は本番を汚染するからだ。

CCA-F が --json-schema について問うこと

「CI パイプラインでこのスキーマに JSON 出力が準拠することを保証する正しいメカニズムを選べ」という問題が出ることが予想される。誤答選択肢として以下が提示される可能性がある。

• より強いシステムプロンプト（「CLAUDE.md に常に有効な JSON を返すよう Claude に告げる」）。
• --output-format json 単独（エンベロープであり、コンテンツではない）。
• リトライループなしの事後 jq バリデーション。

正解は --json-schema（または strict: true を持つ tool use）と CI フレンドリーなリトライポリシーの組み合わせだ。

ヘッドレスモード — 自動化のための TTY なし Claude Code の実行

「ヘッドレス」とは、ターミナルが接続されていない環境で claude を実行することの運用上の用語である。CI ランナーが提供するのはまさにそのような環境だ。ヘッドレスモードは -p（非インタラクティブ）に加え、TUI 機能が呼び出されないことを確保することで有効になる。Claude Code は非 TTY の stdin/stdout ペアを検出して出力レンダリングを自動的に調整するよう設計されているが、「人間を期待するな」という明示的な契約としての -p はやはり必要だ。

TTY 検出だけに頼らない理由

一部の CI ランナーは（カラーログ出力、プログレスレンダリングのために）実際には人間が接続されていないにもかかわらず TTY をシミュレートする。-p なしでは、Claude Code が疑似 TTY の存在をインタラクティブ UI を起動するシグナルとして解釈し、壊れた出力やハングを引き起こすことがある。-p は、ランナーの TTY エミュレーションがどう判断しようとも「非インタラクティブ」を明示するための確実な方法だ。

ヘッドレスコンテキストで重要な環境変数

• ANTHROPIC_API_KEY ― 認証に必要。CI のシークレットストレージ経由で注入する。
• CLAUDE_CODE_WORKSPACE ― ワークスペースルート。通常はチェックアウトディレクトリに設定する。
• 静的な .claude/settings.json ファイルに渡すのが扱いにくい設定については、各種フラグが環境変数としてミラーされる。

正確な環境変数リストは設定リファレンスで管理される。CCA-F は完全なリストを試験で問わないが、環境変数が動的すぎるまたは機密すぎて静的な .claude/settings.json ファイルでは扱いにくい設定を CI パイプラインが注入する方法であるという概念は問われる。

PR レビューの自動化 — Claude 分析によるプルリクエストへの自動コメント

プルリクエストレビューは、本番環境で最も一般的な Claude Code CI/CD パイプライン統合の形状だ。パターンは以下のとおりだ。

1. PR イベントが発生すると、CI ランナーがブランチをチェックアウトする。
2. ランナーが差分を計算する（git diff origin/main...HEAD）。
3. ランナーが差分をレビュープロンプトと任意の CLAUDE.md スコープとともに claude -p --output-format json にパイプする。
4. ランナーが JSON の結果から構造化されたレビューコメントを抽出する。
5. GitHub Actions（または GitLab CI）のステップが、プラットフォーム API 経由でコメントを PR に投稿する。

この形状が標準的な理由

CI での PR レビューは3つの責任をきれいに分離する。

• Claude Code はレビューコンテンツの生成に責任を持つ。
• CI ランナーは差分の収集とコメントの投稿に責任を持つ。
• プルリクエストプラットフォーム（GitHub、GitLab）はコメントのインライン表示に責任を持つ。

このパターンでは Claude Code は PR プラットフォームを直接呼び出さない。構造化された出力を生成するだけだ。これが正しい分離であり、差分がパイプで送られ、構造化されたコメントが呼び出し元によって処理される限り、同じ claude -p 呼び出しが GitHub Actions、GitLab CI、またはローカルの開発者スクリプトで動作することを意味する。

PR レビューでの CLAUDE.md の役割

PR レビューのプロンプトは通常、Claude に以下に集中するよう指示する。

• 正確性の問題（バグ、ロジックエラー）。
• 差分によって表面化されたセキュリティの懸念。
• プロジェクトの慣習からのスタイルの逸脱（CLAUDE.md を通じて読み込まれる）。
• 新しいコードパスに対するテストの欠如。

CLAUDE.md はここで重要な役割を果たす。Claude Code が -p を使って CI 環境で実行される場合でも、チェックアウトされたワークスペースの CLAUDE.md 階層を尊重する。CLAUDE.md にコード化されたプロジェクトの慣習、レビューチェックリスト、言語固有のルールは、コマンドラインのプロンプトを膨らませることなく、すべての CI レビューの暗黙の基準となる。

PR レビューにおける allowedTools の規律

純粋なレビュー（ファイル編集なし）のために、PR レビューの CI ジョブは通常、Claude を読み取り専用のツール――Read、Grep、Glob、限定された許可リストを持つ Bash――に限定する。提案された変更をコメントするのであって修正するわけではないため、書き込みアクセスは明示的に保留される。権限モデルは .mcp.json と設定ファイルによって強制され、Claude の振る舞いに期待するのではない。

テスト生成ワークフロー — コミット時に Claude がテストを書くトリガー

テスト生成は、2番目に標準的な Claude Code CI/CD パイプライン統合パターンだ。典型的な形状は以下のとおりだ。

1. プッシュまたは PR イベントがパイプラインをトリガーする。
2. 既存のステップがテストカバレッジが不十分な関数またはファイルを特定する（カバレッジレポート、または差分を考慮したヒューリスティックを経由して）。
3. claude -p が、テストされていないファイルの名前、プロジェクトのテスト慣習（CLAUDE.md から）、テストを書く指示を含むプロンプトとともに呼び出される。
4. サンドボックス化されたパスで Read と Write ツールが有効になった Claude Code がテストファイルを生成する。
5. パイプラインが新しいテストを実行し、合格した場合は変更を含む PR を開く。

テスト生成が CI に自然に適合する理由

インタラクティブなコーディング（開発者が密結合した機能コードをデバッグする）とは異なり、テスト作成はボリュームが多く、パターン駆動で、自然にスクリプト化できる。人間は新しいテストのみを含む PR を喜んでレビューする。誤りのコストは低い（テストは合格するか、失敗するか、修正されるかのいずれかだ）。

テストスタイルのための CLAUDE.md のアンカリング

「pytest を使う、フィクスチャは tests/conftest.py に置く、外部 HTTP は responses でモックする」という内容をドキュメント化したプロジェクトレベルの CLAUDE.md は、テスト生成の CI 出力を一貫させるものだ。CLAUDE.md アンカーなしでは、同じプロンプトが実行ごとに異なるテストスタイルを生成し、スタイルのチャーンでレビュアーの時間を消費させる。これは CI の pp-08（モノリシックまたは欠落した CLAUDE.md の指示は信頼性の低い出力を生む）に相当するものだ。

許可されたパスへの書き込みスコープ

テスト生成の場合、Claude Code は書き込みを許可されるが、例えば tests/ ディレクトリのみに限定される。書き込みスコープの強制は通常、Claude が自分のレーンに留まることを信頼するのではなく、権限モデルを通じて表現される。CCA-F はこの原則を評価する：CI ジョブに必要なものだけにツール許可リストの影響範囲を限定し、それ以上は許可しないこと。

セキュリティスキャン統合 — 静的解析の結果を Claude が要約する

静的解析ツール（Semgrep、CodeQL、Bandit、Brakeman など）は、人間がトリアージしにくい大量の生の検出結果を生成する。Claude Code の CI/CD パイプライン統合は、その生のストリームをトリアージされ、平文で説明された要約に変換する。

典型的な形状

1. セキュリティスキャンステップが実行され、検出結果を JSON、SARIF、または CSV として出力する。
2. 検出結果のアーティファクトが claude -p --output-format json --json-schema <triage-schema> への入力としてパイプまたは参照される。
3. プロンプトが Claude に、根本原因別に検出結果をグループ化し、既知の誤検知をフィルタリングし（オプションでリポジトリ内の .false-positive-allowlist.json と照合）、重大度、推奨アクション、簡潔な説明を含むトリアージされたリストを出力するよう指示する。
4. パイプラインがトリアージサマリーを PR またはセキュリティダッシュボードに投稿する。

Claude 自身がスキャナーを実行しない理由

スキャナーは数十年のチューニングを経た専門ツールであり、Claude はその代替品ではない。Claude が付加する価値は解釈――密なSAST の出力を平文に変換し、関連する検出結果をグループ化し、最もリスクの高い項目に人間の注意を最初に向けること――である。この分離は PR レビューの形状を反映している。Claude は解析を行うのではなく、解析を説明する。

スキャンサマリーのバジェット規律

大きなスキャンでは何千もの検出結果が生成される可能性がある。それらすべてを直接 Claude Code に渡すことは、コストが高く無駄だ ― Claude は一度に1万件の検出結果を有効に処理できず、そのほとんどはほぼ重複している。正しいパターンは以下のとおりだ。

• Claude を呼び出す前にスキャン出力を事前フィルタリングして重複を排除し、検出結果をバケット化する。
• 実行ごとに要約される検出結果の数を上限設定する。
• ボリュームが大きい場合はパスで要約し、一度に1バケットずつ送る。

これは後述のコスト管理セクションを先取りするが、インラインで言及する価値がある：Claude Code を生の検出結果トランスフォームとして使わないこと。既に前処理された入力のトリアージレイヤーとして使うこと。

環境設定 — CI エージェントコンテキストのための CLAUDE.md と .mcp.json

Claude Code の CI/CD パイプライン統合は、インタラクティブな Claude Code が使う同じ設定機構を継承する。CLAUDE.md はプロンプト指示のため、.mcp.json は MCP サーバーの接続のため、.claude/settings.json はモデル・ツールの設定のために使われる。ただし、CI 固有の2つの規律が適用される。

CI 環境での CLAUDE.md

チェックアウト後の CI ランナーの作業ディレクトリには、リポジトリにコミットされた CLAUDE.md ファイルが含まれる。ヘッドレスで実行する Claude Code でも CLAUDE.md 階層をウォークする。グローバル CLAUDE.md（~/.claude/CLAUDE.md、CI ランナーにはほとんど存在しない）、プロジェクトルートの CLAUDE.md、ツリー内の深い場所のディレクトリスコープの CLAUDE.md ファイルがその対象だ。

CI 固有の CLAUDE.md パターン：

• CI に関連する慣習（テストフレームワーク、レビューチェックリスト、セキュリティガードレール）をコミット済みのプロジェクト CLAUDE.md に保持し、CI 呼び出しが自動的にそれらを見られるようにする。
• @import を使って CI 関連のフラグメント（@.claude/ci-review.md）をインタラクティブ専用のコンテンツから分離する。
• 開発者ローカルの慣習はプロジェクトの CLAUDE.md にコミットしないこと ― CI ランナーが持たないユーザースコープの CLAUDE.md に置くべきだ。

CI 環境での .mcp.json

プロジェクトルートの .mcp.json は、Claude Code が使用できる MCP サーバーを宣言する。CI では、ポリシーを最小限にすること。

• CI ジョブが実際に必要とする MCP サーバーのみを有効にする（通常は git、場合によっては PR コメント投稿のための GitHub MCP サーバー、稀にナレッジルックアップ用の内部サービス MCP）。
• 実験的な MCP サーバーを CI 実行で有効にしないこと。CI は統合のデバッグを行う場所ではない。
• MCP サーバーの認証情報には、コミット済みファイルではなく CI ランナーのシークレットを使用する。

--strict-mcp-config フラグ

一部の Claude Code ビルドでは、.mcp.json が実行時に解決できないサーバーを宣言している場合に起動を拒否する --strict-mcp-config フラグをサポートしている。CI 環境では、これは煩わしさではなく機能だ ― 設定が誤った MCP サーバーは、機能の半分が欠けた実行をサイレントに開始するのではなく、ジョブを大きな音で失敗させるべきだ。CCA-F はフラグの正確なスペルを問わないが、CI 実行がサイレントな劣化よりも厳格な設定を優先すべきという原則は問われる。

終了コードとエラー処理 — Claude Code からのパイプライン障害伝播

CI/CD パイプラインのステージは、フロー制御のための出力をちょうど1つだけ持つブラックボックスだ。その出力は終了コードで、ゼロは成功、非ゼロは失敗を意味し、ランナーはその整数のみに基づいて次のステップを決定する。Claude Code の CI/CD パイプライン統合は、その終了コードがステップが成功したか失敗したかを正しく反映する限りにおいてのみ、パイプラインに有用だ。

終了コードの規約

Claude Code は標準的な Unix 終了コード規約に従う。

• 0 ― 成功した実行。agentic loop が正常に終了し（end_turn）、エラーが発生しなかった。
• 非ゼロ ― 何らかの理由で実行が失敗した。認証エラー、ツール権限拒否、スキーマバリデーション失敗（--json-schema が強制されている場合）、イテレーション上限超過、Anthropic API エラー、または Claude 内部からの明示的なエラーシグナル。

終了コードの規律が重要な理由

インタラクティブな使用では、失敗した Claude Code の実行は明らかだ ― 人間が画面でエラーメッセージを見る。CI では、終了コード0を返す失敗した実行はパイプラインをサイレントに汚染する。ダウンストリームのステップ（コメントを投稿する、PR を開く、ビルドをデプロイする）は、すべてが正常に機能したかのように進行する。壊れた出力を送り出した合格パイプラインは、CI 障害の最悪のクラスだ。

逆に、成功した実行が非ゼロの終了コードを返すと、パイプラインを不必要に止め、開発者の時間を誤警報に費やさせる。

JSON エンベロープの is_error フィールドの解析

--output-format json で実行する場合、終了コードは1つのシグナルであり、JSON エンベロープ内の is_error フィールドは別のシグナルだ。堅牢な CI ラッパーは両方をチェックする。

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

多層防御 ― 終了コードとエンベロープフィールドの両方 ― は、ハードな失敗（プロセスエラー）とソフトな失敗（Claude が内部エラー状態に達したが、プロセスはクリーンに終了した）の両方をキャッチする。

Claude の構造化エラーをランナーにバブルアップさせる

Claude が --json-schema で実行して最終出力がバリデーションに失敗した場合、パイプラインには確定的な失敗が必要だ。正しいパターンは、claude レイヤーでスキーマを検証し、エンベロープに is_error: true を設定し、非ゼロの終了コードを返すことだ。CI ラッパーはその後、ランナー固有のイディオム（GitHub Actions の ::error:: アノテーション、GitLab CI の失敗ステージ、Jenkins の不安定ビルド）で失敗を伝播させる。

CI でのコスト管理 — スコープの制限・キャッシング・トークン使用のバジェット管理

CI は Claude Code を多く実行する。週に100件の PR があり、それぞれが Claude を使ったレビューをトリガーするリポジトリは、最低でも週100回の agentic loop 実行となる。規律なしでは、Claude Code の CI/CD パイプライン統合が Anthropic の請求書の最大の項目になる。コスト管理はあると良いものではなく、設計要件だ。

スコープの制限

最安のトークンは送らないトークンだ。CI で Claude Code を呼び出す前に入力を絞ること。

• 変更されたファイルのみをレビューする。 コードベース全体ではなく、差分をパイプする。
• 重大度のしきい値を超えた検出結果のみを要約する。 ノイズをスキップする。
• 新しいまたは変更された関数のみのテストを生成する。 残りはそのままにする。
• Claude を呼び出す前に安価なツールで事前フィルタリングする。 Grep、jq、少量の awk が関連のない入力の80%を排除する。

キャッシング

基盤となるプラットフォームがプロンプトキャッシングをサポートしている場合、長く安定した前文（CLAUDE.md コンテンツ、レビューチェックリスト、セキュリティガイダンス）が実行をまたいで安価にキャッシュされる。正確なキャッシングのメカニズムは Claude のプラットフォーム内にあり、CCA-F の対象外（試験ガイドの付録では「機能の存在を知っている範囲を超えるプロンプトキャッシングの実装詳細」を明示的に除外している）だが、安定した前文が揮発性の前文よりコストが低いというアーキテクチャ上の事実は問われる可能性がある。

実行ごとのトークンバジェット

--output-format json はエンベロープで total_cost_usd とトークン数を出力する。実行ごとのバジェット上限を強制する CI ラッパーは簡単だ。

COST=$(echo "$OUTPUT" | jq -r '.total_cost_usd')
if (( $(echo "$COST > 0.50" | bc -l) )); then
  echo "claude run exceeded $0.50 budget: $COST"
  # アラート、タグ付け、または失敗させる
fi

プッシュごとの実行 vs マージごとの実行

一般的なコストレバーは、Claude Code をいつ実行するかだ。PR ブランチへのすべてのプッシュ（すべての git push）で実行すると、高速なフィードバックが得られるが請求額が倍増する。PR オープン、PR レビュー準備完了、または PR マージ時のみで実行すると、コストを大幅に削減できる。CCA-F は特定のトリガーポリシーを規定しないが、CI トリガーポリシーはコストレバーであるという原則は問われ、正解はすべてのイベントよりも少ないイベントでトリガーすることを伴うことが多い。

CI での Plan mode — なぜデフォルトの答えは「ノー」なのか

Plan mode（タスク 3.4）は、Claude Code が実行前に承認のための計画を生成するよう求める機能だ。インタラクティブな使用では、リスクの高いまたは曖昧なタスクに対して plan mode が正しい選択であることが多い。CI では、デフォルトの答えは逆だ：CI では plan mode を使わないこと。

Plan mode が CI を壊す理由

Plan mode は提案された計画を生成し、実行前に承認を待つ。非インタラクティブな CI コンテキストでは承認する人間がおらず、実行はハングするか、パイプラインがタイムアウトする。これは、コミュニティの pp-06（「plan mode は常により安全な選択ではない」）が具体化する場面だ。plan mode は非インタラクティブなパイプラインでは、より安全な選択ではなく、誤った選択だ。

まれな例外

CI のような自動化が計画を生成するが実行しない場面がある ― 例えば、別のツールで人間が非同期にレビューするために計画を準備するパイプラインステージだ。このまれなケースでは、plan mode フラグを使って Claude Code を呼び出せるが、パイプラインはエンベロープから計画を解析し、承認を待たずに明示的に続行しないことが必要だ。これはニッチな形状だ。CCA-F の試験当日には、「CI での plan mode」に対するデフォルトの答えは「有効にしないこと」だ。

CI ステップ内のイテレーティブな改善とマルチエージェントパターン

CI ジョブが単純な一度限りの変換以上である場合、2つの隣接するタスクステートメントがタスク 3.6 に流れ込む。タスク 3.5（イテレーティブな改善）とタスク 1.2/1.3（マルチエージェントオーケストレーション）だ。CI 内では両方が有用だが、コスト的に安全に保つための CI 固有の規律が必要だ。

単一実行内のイテレーティブな改善

テストを生成したりコードを書いたりする CI ステップは、単一の claude -p 呼び出し内でイテレーションが必要な場合がある。書いて、実行して、失敗を観察して、修正して、再実行する ― Claude Code 内の agentic loop がこれをネイティブに処理する。Claude が Write を呼び出し、Bash でテストを実行し、失敗を観察し、Edit を呼び出して修正し、テストが合格するかイテレーション上限が発動するまで再実行する。

CI 固有のイテレーション上限

CI ステップのイテレーション上限はタイトであるべきだ ― 通常10ターン以下 ― なぜなら際限のない CI ステップはすべての後続ジョブからランナーの時間を奪うからだ。ランナーレベルのウォールクロックタイムアウト（例：GitHub Actions のステップの timeout-minutes）と組み合わせること。

停止シグナル：繰り返し状態の検出

Claude が同じ Edit → Bash サイクルを進展なく繰り返し提案し続ける場合、ループはスタックしている。Bash からの構造化エラーレスポンス（実行可能な stderr を含む非ゼロの終了コード）と Claude 自身のパターン認識が通常サイクルを破るが、堅牢な CI ジョブは同一のツール呼び出しの繰り返しで終了する。

CI ステップで subagent が必要な場面

Claude Code の CI/CD パイプライン統合は、並列化可能な作業 ― それぞれの変更されたファイルを独自の subagent でレビューし、各スキャン検出結果のバケットを独立して要約し、モジュールごとにテストを生成する ― で subagent に委任できる。CI 固有の規律は以下のとおりだ。

• 各 subagent が独自の agentic loop を生成してコストを乗算するため、subagent の数を少なく保つ。
• 並列処理が実際にウォールクロック時間を削減する（ランナーに並列容量がある）場合、またはコンテキストの分離が必要な場合にのみ subagent を使用する。
• subagent ごとではなく、すべての subagent の累積コストを監視する。

CI のシナリオクラスターはマルチエージェントの形状を間接的に参照することがある ― タスク 3.6 のコンテキストに展開されたタスク1のパターンとして認識すること。

よくある試験トラップ

Claude Code の CI/CD パイプライン統合は、ドメイン3で最もトラップが多いトピックの一つだ。5つのパターンが問題プール全体で繰り返される。

トラップ1：-p が安全チェックや権限を無効化すると信じる

-p / --print は入出力の配管のためのモードスイッチ ― それだけだ。ツールの権限プロンプトを無効化せず、破壊的なコマンドの実行を拒否する安全レールを無効化せず、その他の保護もバイパスしない。「Claude に必要なことを何でもやらせる」ために -p だけに頼る CI ジョブは、Claude が許可リスト外で書き込みや呼び出しを試みた最初の時点で失敗する。正しいパターンは、非インタラクティブのための -p と、.mcp.json、settings.json、または --allowedTools フラグを経由した明示的な権限設定の組み合わせだ。

トラップ2：--output-format json が答えの形式を制約すると期待する

--output-format json はエンベロープを変えるだけだ。エンベロープ内の .result フィールドには Claude が生成したものがそのまま入る ― 平文を求めれば平文、JSON 配列を求めれば JSON 配列。コンテンツのスキーマ強制には --json-schema、strict: true を持つ tool use、またはその両方の組み合わせが必要だ。スキーマセーフな出力のために --output-format json だけに頼ることは、発生を待っているパイプラインのバグだ。

トラップ3：非インタラクティブコンテキストで Plan mode を有効にする

Plan mode は承認を待つ。CI には承認する人間がいない。パイプラインはタイムアウトが来るまでハングする。Plan mode はインタラクティブ専用の機能だ。CI でのデフォルトの答えは「有効にしないこと」だ。plan mode を CI での安全強化として位置づける誤答選択肢は誤りだ。

トラップ4：終了コードまたは is_error エンベロープフィールドを無視する

堅牢な CI ラッパーは、プロセスの終了コードと JSON エンベロープの is_error フィールドの両方をチェックする。ソフトな失敗（Claude が内部エラー状態に達したがクリーンに終了した）とハードな失敗（プロセスレベルのクラッシュ）は両方発生し得る。片方だけをチェックすると、失敗モードの半分を見逃す。コミュニティの合格レポートでは、単一シグナルのエラー処理が「惜しいが誤り」の頻繁なパターンとして挙げられている。

トラップ5：シークレットまたは全コンテキストをコミット済み設定に含める

ANTHROPIC_API_KEY、MCP サーバーの認証情報、その他のシークレットは CI ランナーのシークレットストレージに属する ― コミット済みの CLAUDE.md、.mcp.json、.claude/settings.json には絶対に含めないこと。また、CI 実行がリポジトリ全体を Claude コンテキストとして自動的に見ると思わないこと。セキュリティ（最小限の必要な開示）とコスト（最小限の必要なトークン）の両方のために、差分をパイプするか、ファイルを明示的に指定すること。

練習アンカー

Claude Code の CI/CD パイプライン統合はシナリオクラスター6のアンカーだ。試験当日に特に一般的な2つのアンカーサブシナリオがある。

失敗した PR レビューパイプライン

シナリオの形状：チームが PR イベントで claude を GitHub Actions に組み込んでいる。実行が断続的にハングするか、ビルドログに ANSI エスケープノイズを生成するか、Claude がファイルを編集しようとすると権限エラーで失敗する。試験はアーキテクチャ上の修正を特定するよう求める。答えには -p の追加、ツール権限の絞り込み、そして多くの場合 CLAUDE.md コンテンツの CI スコープのフラグメントへの分離が含まれると予想される。誤答選択肢は「タイムアウトを増やす」（原因ではなく症状を治療する）、「plan mode を使う」（ハングを悪化させる）、または「-p で安全チェックを無効にする」（-p の動作を誤解している）を提示するだろう。

スキーマドリフトのテスト生成ジョブ

シナリオの形状：テスト生成ジョブが何ヶ月も安定していた。Claude が時々テストファイルのコンテンツと一緒に平文を返すようになり、ダウンストリームのファイル書き込みステップが壊れることで突然失敗し始めた。試験はこれを永続的に修正するよう求める。正解は --json-schema（または strict: true を持つ tool use）を --output-format json の上に重ねること。誤答選択肢はプロンプトを強化する提案をするだろう（「CLAUDE.md に JSON のみを許可するよう Claude にもっと強く告げる」）。プログラマティック vs プロンプトの pp-01 が直接試験で問われる ― 正解はプログラマティックな制約であり、プロンプトの制約ではない。

完全なシナリオクラスターの準備

CI シナリオクラスターはドメイン2のツール設計（Claude が呼び出せるツール）、ドメイン3の設定（CLAUDE.md、フラグ、権限）、ドメイン4の構造化出力（スキーマ強制）、ドメイン5の信頼性（終了コードの伝播、エラーの分類）を絡み合わせている。CI シナリオを純粋にドメイン3の演習として扱うと、それぞれ1〜2点を失うクロスドメインの問題を見逃す。

やさしい解説: Claude Code を CI/CD パイプラインで使うことは非常に具体的なエンジニアリング問題であり、3つの日常的なシステムがその動作部品を直感的に理解させる。

厨房の受け渡し口 — -p は注文票の受け渡し

注文の方法が2通りある厨房を想像してほしい。食堂（インタラクティブな Claude Code）では、ウェイターがパス（受け渡し口）に歩み寄り、テーブルのニーズを言葉で説明し、シェフが確認の質問をし、料理を作り、持ち帰る。デリバリー窓口（claude -p）では、プリンターから注文票が届き、シェフはそれを読み、仕様どおりに料理を作り、完成した皿を宅配業者が取り行くためのウォーマーボックスに置く。会話なし、確認質問なし、食事客が決めるのを待たない。-p フラグはデリバリー窓口のプリンターだ。「これはチケットであって会話ではない ― 料理して行け」とシェフに告げる。そしてデリバリー窓口と同様に、-p はシェフが食品安全規則を無視することを意味しない（権限と安全チェックはまだ適用される）。シェフが会話しないことを意味する。デリバリーチケットを誤って食堂のプリンターに出力してしまう厨房はすべての人を混乱させる。-p を忘れた CI パイプラインは、ランナーが決して来ない会話を待って混乱させる。

コンテナ船 — --output-format json と --json-schema の違い

運送会社は何でも標準コンテナ（エンベロープ）に入れられる ― 標準的な形状、標準的な住所ラベル、標準的な書類だ。これが --output-format json だ。コンテナの外側は予測可能；中の貨物は送り主が何を入れたかによって異なる。受け取り手がオレンジのケースを期待して、鉄くずのケースが届いた場合、エンベロープは役に立たなかった ― 外側は正しく見えたが、中身は間違っていた。--json-schema は、貨物がマニフェストに合致するかを確認するために税関検査がコンテナを開けるようなものだ。合致しない場合、荷物は港でトラックが出発する前に却下される。--output-format json だけに頼る CI パイプラインは、コンテナの外側しか確認しない受け取り手だ。Claude が JSON の代わりに平文を送る最初の日に、ダウンストリームのステップはオレンジを開こうとして鉄くずを受け取ることになる。--output-format json と --json-schema を組み合わせることが、発送と検査の両方を行う唯一の構成だ。

工場の緊急停止ボタン — 終了コードというランナーへの唯一の信号線

工場の生産ラインは、それぞれが1本の赤い「障害」信号線をメインコントロールパネルに繋げた機械のシーケンスだ。どれかの機械の信号線が活性化すると、ライン全体が止まる。各機械には何百もの内部シグナル ― 温度、振動、圧力 ― があるが、メインパネルはその1本の信号線しか見ない。CI パイプラインも同じように機能する。各ステップが機械、終了コードが信号線、ランナーがメインパネルだ。内部で何が起きてもランナーに常に「正常」と報告する Claude Code のステップは故障した機械だ ― ライン全体がドリルが詰まったまま動き続け、完成品はすべておかしくなる。--output-format json と is_error は2本目の信号線（障害センサーの横に温度センサー）を与え、プライマリの信号線が発火し忘れた場合でも CI ラッパーが比較して失敗させられるようにする。堅牢な CI 統合は、一部だけの情報ではなく、コントロールパネルに全真実を告げる工場機械だ。

どの比喩がどの試験問題に適合するか

• -p と非インタラクティブモードについての問題 → 厨房の受け渡し口の比喩。
• --output-format json と --json-schema の違いについての問題 → コンテナ船の比喩。
• 終了コードとパイプラインの伝播についての問題 → 工場の緊急停止ボタンの比喩。

FAQ — Claude Code CI/CD 上位6つの質問

-p フラグは実際に何をするのか、CI で必要な理由は？

-p（長形式は --print）はインタラクティブ TUI を無効にして非インタラクティブな単発実行を行う Claude Code のモードスイッチだ。-p なしでは claude がインタラクティブ REPL を起動してキーボード入力を待つ ― CI ランナーでは決して入力が来ないため、プロセスはランナーのウォールクロックタイムアウトが来るまでハングするか、TUI エスケープコードをビルドログに出力する。-p を使うと、Claude はコマンドラインまたは stdin のプロンプトから1回の agentic loop 実行を行い、最終結果を stdout に出力し、標準の終了コードで終了する。-p は CCA-F タスク 3.6 で最も頻繁に試験で問われるフラグであり、両方のスペルと正確なセマンティクスを暗記すること。

-p は権限チェックや安全レールを無効化するか？

しない。-p は入出力の配管を変えるだけだ ― TUI がスキップされ、入力が引数または stdin から来て、出力が stdout に行く。ツールの権限モデルを無効化せず（許可リスト外のファイル書き込み、シェルコマンドには引き続き事前承認された権限が必要）、Claude が明らかに破壊的なコマンドの実行を拒否しないようにもせず、安全チェックをバイパスしない。権限は .mcp.json、.claude/settings.json、--allowedTools フラグ、または --permission-mode フラグで別途制御される。「何でもやれる」権限を -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 の内部で制約しない。Claude が生成したものが文字列としてそこに入る。--json-schema はユーザーが提供した JSON Schema に対して最終答えを検証する別のフラグで、答えが準拠しない場合は実行が失敗（またはリトライ）する。2つのフラグは補完的だ。--output-format json がエンベロープを与え、--json-schema が貨物を制約する。スキーマセーフな CI パイプラインは両方を使うか、ベルトアンドブレースの強制のために strict: true モードの tool use と --json-schema を組み合わせる。

CI パイプラインで plan mode を有効にすべきか？

ほとんどの場合、すべきでない。Plan mode は提案された計画を生成し、実行前に人間の承認を待つ。CI は定義上非インタラクティブで承認する人間がいないため、ランナーのウォールクロックタイムアウトまでパイプラインがハングする。Plan mode はリスクの高い、または曖昧なタスクのインタラクティブセッション向けに設計されている。まれな例外は、CI ステージが別のツールでの非同期な人間レビューのために計画を生成することを明示的に望む場合で、その場合はパイプラインが承認を待たずにエンベロープから計画を解析しなければならない。CCA-F では、CI での plan mode を「安全のために」推奨する答えはほぼ確実に誤りだ ― 非インタラクティブな実行と互換性がない。

CI ラッパーは Claude Code の実行が成功したかどうかをどう判断すべきか？

2つのシグナルを確認する。まず、プロセスの終了コード：ゼロは成功を意味し、非ゼロは CLI 自体がエラーとなったことを意味する（認証、API 障害、権限拒否、--json-schema が強制されている場合のスキーマバリデーション失敗、イテレーション上限超過）。次に、--output-format json エンベロープ内の is_error フィールド：true は Claude がプロセスがクリーンに終了したにもかかわらず内部エラー状態に達したことを意味する。堅牢な CI ラッパーはいずれかのシグナルが失敗を示した場合にステップを失敗させる。終了コードだけをチェックすると、Claude がエンベロープで問題を表面化したがクリーンに終了したソフトな失敗を見逃す。エンベロープだけをチェックすると、CLI レベルのハードなエラーを見逃す。両方合わせて Claude Code CI/CD パイプライン統合の標準的な信頼性パターンを形成する。

Claude Code の CI コストを管理するには？

4つのレバーを組み合わせて適用する。まず、入力を絞る ― リポジトリ全体ではなく差分をパイプし、スキャン検出結果を事前フィルタリングし、変更されたファイルのみをターゲットにする。次に、より少ないイベントでトリガーする ― すべてのプッシュではなく PR オープンと PR レビュー準備完了のみ。第三に、JSON エンベロープから total_cost_usd を解析して、実行がしきい値を超えた場合に失敗またはアラートを発することで、実行ごとのトークン・コストバジェットを強制する。第四に、1回の実行が単独で絡まないよう Claude Code 内の agentic loop に厳格なイテレーション上限を使う。安定した前文（CLAUDE.md コンテンツ、レビューチェックリスト）のプロンプトキャッシングがコストをさらに削減するが、フラグレベルではなくプラットフォームレベルだ。統一原則：最安のトークンは送らないトークンだ。

参考文献

• Claude Code を CI/CD パイプラインに統合する: https://docs.anthropic.com/en/docs/claude-code/ci-cd
• Claude Code 設定リファレンス: https://docs.anthropic.com/en/docs/claude-code/settings
• Claude Code 機能概要: https://docs.anthropic.com/en/docs/claude-code/overview
• CLAUDE.md 設定: https://docs.anthropic.com/en/docs/claude-code/claude-md
• Plan mode とイテレーティブな改善: https://docs.anthropic.com/en/docs/claude-code/plan-mode
• コミュニティ合格レポート（893/1000）: https://medium.com/@kishorkukreja/i-passed-anthropics-claude-certified-architect-foundations-exam-with-a-score-of-893-1000-2206c27efd6c

関連 ExamLab トピック：Plan Mode vs 直接実行、ビルトインツールの選択と適用、イテレーティブな改善による段階的向上、バッチ処理戦略。