Headless モードで CI に Claude を組み込む

コース構成

このコースで学ぶこと

1. 01

   Headless モードとは

   claude コマンドに -p（プロンプト）と --output-format を渡すと、対話画面を出さずにスクリプト用の出力を返す。これが CI に組み込む土台になる。

   • --output-format text / json / stream-json
   • --max-turns で暴走を防ぐ（CI では 1〜3 推奨）
   • --allowed-tools で使えるツールを限定（Read のみ等）

   bash

   claude -p "このディレクトリの README を 5 行で要約して" \
     --output-format json \
     --max-turns 1

   理解度チェック

   1. Q1.Headless モードで Claude を CI に組み込むときの最小オプションセットは？

      A`-p` のみ。それ以外は不要B`-p` + `--output-format` + `--max-turns`（最低限ガード）C`-p` + `--ultrathink` で常に強考D`--debug` + `--verbose`
   PR レビュー Bot を 1 ファイルで
2. 02

   PR レビュー Bot を 1 ファイルで

   GitHub Actions に Claude を 1 ジョブとして組み込む。diff をプロンプト本体に埋め込んで観点別にコメントを返させる構成が最も小さく始められる。

   yaml

   name: claude-review
   on: pull_request
   jobs:
     review:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with: { fetch-depth: 0 }
         - name: claude review
           env:
             ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           run: |
             DIFF=$(git diff origin/main...HEAD)
             claude -p "以下のパッチを review_checklist.md の観点でレビュー。
   
   ---PATCH---
   $DIFF
   ---END---" \
               --allowed-tools Read \
               --max-turns 2 > review.md
         - uses: actions/github-script@v7
           with:
             script: |
               const fs = require('fs');
               const body = fs.readFileSync('review.md', 'utf8');
               await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });

   理解度チェック

   1. Q1.PR レビュー Bot で `--allowed-tools Read` を指定する意図は？

      ARead が一番速いツールだからBBot にコードを書き換えさせず、読み取りだけに権限を限定するためCRead 以外のツールが課金対象だからDHeadless モードでは Read しか使えないから
   Headless モードとはCost ガードレールと失敗時の挙動
3. 03

   Cost ガードレールと失敗時の挙動

   CI で動かす以上、暴走するとお金と時間が燃える。max-turns・allowed-tools・タイムアウトの 3 段ガードを必ず入れる。

   • max-turns: 1〜3（要件確認なら 1、レビューなら 2）
   • allowed-tools: 書き込みが要らないなら Read だけ
   • timeout-minutes: 5〜10（job レベル）
   • Anthropic Console の Workspace で月間 spend cap を設定

   理解度チェック

   1. Q1.外部 fork からの PR で `pull_request_target` を無防備に使うと起きる事故は？

      Aジョブが GitHub の制限で落ちるBfork 側のコードに ANTHROPIC_API_KEY などの secrets が露出して盗まれうるCClaude のレスポンスが日本語にならないDBot が外部 PR を勝手にマージしてしまう
   PR レビュー Bot を 1 ファイルで“要件チェック”ジョブで PR 説明を強制する
4. 04

   “要件チェック”ジョブで PR 説明を強制する

   Claude に PR 本文を読ませて、テンプレに足りない項目があれば検出するジョブを足す。レビュアーの負荷が劇的に下がる。

   bash

   PR_BODY=$(gh pr view --json body -q .body)
   claude -p "以下の PR description が我が社の PR テンプレ（@.github/PULL_REQUEST_TEMPLATE.md）を満たしているか判定し、missing: [..] の JSON で返して。
   
   ---PR_BODY---
   $PR_BODY
   ---END---" \
     --output-format json --max-turns 1

   手を動かす

   0 / 3

   • テンプレ未記入なら fail させる
   • missing 配列を PR コメントに貼る
   • 本人が編集したら自動再実行（pull_request: types: [edited]）

   理解度チェック

   1. Q1.PR description のテンプレ充足判定を Claude にやらせるとき、出力形式の選択として最適なのは？

      A自由形式テキストBmissing 配列を含む JSON（`--output-format json`）CSlack メッセージDPDF レポート
   Cost ガードレールと失敗時の挙動リリースノートと運用
5. 05

   リリースノートと運用

   リリースタグ作成時に Claude が直近の commit から日本語リリースノートを書く。これも Headless モードで自動化できる。

   bash

   COMMITS=$(git log v1.0.0..HEAD --oneline)
   claude -p "以下のコミットから 5 行のリリースノートを日本語で。ユーザー視点で。
   
   ---COMMITS---
   $COMMITS
   ---END---" \
     --max-turns 1

   手を動かす

   0 / 3

   • release.yml の Job 化
   • ノートはまず Draft Release に貼る（人間が最終確認）
   • 暴走時のロールバック手順を README に書く

   Lv.7 — エージェント自動化

   理解度チェック

   1. Q1.Headless Claude で自動生成したリリースノートを“まず Draft Release に貼る”運用にするのはなぜ？

      ADraft の方が GitHub の API 利用料が安いからBHeadless モードでは公開リリースが作れないからCAI 生成の文言を人間が必ず一度確認してから公開する余白を残すためDAnthropic の利用規約で公開リリース禁止になっているから
   “要件チェック”ジョブで PR 説明を強制する