Claude Codeには、Pull RequestのCIが失敗したことを検知し、自動で原因を調査してコードを修正する機能があります。しかしCircleCIユーザーがこの機能を使おうとした場合、デフォルト設定のままでは動作しないケースがあります。本記事では、Claude CodeのAuto Fix機能がCircleCIと連携するための前提条件と設定手順を説明します。
Claude CodeのAuto Fix機能とは
Claude Codeには、GitHubのPull Requestにサブスクライブし、CI失敗イベントを受信したときに自動で以下を実行する機能があります。
- 失敗したジョブを特定する
- ローカルでテストを再現し、エラーの原因を調査する
- コードを修正してコミットし、再CIを実行する
Claude CodeがCI失敗イベントを受信し、失敗ジョブを特定している様子
この機能が動作するためには、Claude CodeがGitHub上のCI失敗イベントを受信できる状態になっている必要があります。CircleCIのデフォルト設定ではこの条件が満たされないため、以下の設定が必要です。
Auto Fixが動作するための前提条件
Claude CodeはGitHubのCheck Runs APIを通じてCI失敗イベントを受信します。このAPIにステータスを書き込めるのは、GitHub Appとして認証されたサービスに限られます。
CircleCIのGitHub連携方式は2種類あります。
| 連携方式 | Auto Fixの検知 |
|---|---|
| GitHub OAuth App連携（旧来型・デフォルト） | ❌ 検知できない |
| GitHub App連携 | ✅ 検知できる |
多くのCircleCIプロジェクトは、2023年以前に作成されたものを中心に、デフォルトのGitHub OAuth App連携を使用しています。この場合、Claude CodeはCI失敗を検知できません。GitHub App連携に切り替えることで、Claude CodeがCI失敗を受信できるようになります。
設定手順
ステップ1：現在の連携方式を確認する
GitHub PRのChecksから、連携状況について手軽に判別できます。「CircleCI Checks」セクションが表示されていれば、すでにGitHub App連携が有効です。
GitHub PRのChecksタブに「CircleCI Checks」セクションが表示されている状態
「CircleCI Checks」セクションではなく、ci/circleci: testなどが表示される場合は、以下の手順で設定します。
ステップ2：CircleCIにGitHub Checksを追加する
CircleCIのサイドバーから Org を選択し、VCS Connections > Manage GitHub Checks の順に進みます。GitHub CircleCI Checks Appの設定ページが開くので、GitHub Checksを有効化するリポジトリを選択して保存します。
GitHub ChecksをCircleCIで有効化するには、該当GitHubリポジトリの管理者権限が必要です。
詳細はEnabling GitHub Checks - CircleCI Docsを参照してください。
ステップ3：Claude CodeのGitHub Appパーミッションを更新する
Claude CodeのAuto Fix機能を利用するには、Claude CodeのGitHub AppにWebhookおよびChecksのRead/Write権限が必要です。この権限が付与されていない場合、CI失敗イベントを受信できません。
GitHubからパーミッション更新のメールが届いているはずなので、メールを確認して更新を承認します。
GitHubから届くパーミッション更新の通知メール
メールの承認リンクを開くと、追加されるパーミッションの内容が表示されます。WebhookとChecksのRead/Write権限が含まれていることを確認して更新を承認します。
Webhook・ChecksのRead/Write権限が追加される
ステップ4：PRを作成し、自動修正を有効化する
Auto Fix機能はPRが作成されるまで有効化できません。PRを作成する前の段階では、Claude CodeのUIにCIボタンは表示されません。
PR作成前の状態。CIボタンは表示されない
PRを作成すると、Claude CodeのUIに [CI] ボタンが表示されます。
PR作成後、CIボタンが表示される
[CI]ボタンを開いて「自動修正」をオンにします。これでCI失敗時にAuto Fixが起動するようになります。
「自動修正」をオンにする
Auto Fixが動作したときに何が起きるか
設定が完了した状態でCIが失敗すると、Claude Codeは以下の順序で処理を進めます。
まずGitHubから失敗したジョブの情報を取得し、どのジョブが失敗したかを特定します。
失敗ジョブをCheck Runs APIから取得している様子
次にローカル環境でテストコマンドを実行し、同じエラーを再現します。エラーの原因を特定したらコードを修正し、コミットをプッシュして再CIを実行します。
ローカルでテストを再現して原因を調査している様子
Checksタブでは、ワークフローとジョブ単位で失敗内容を確認できます。
Checksタブに表示されるCircleCI Checksの詳細
現時点の制限事項
Auto Fix機能には現時点で以下の制限があります。
CircleCIのビルドログの内容は直接読み取れません。Claude CodeはCI失敗の「ジョブ名」と「ステータス」を取得しますが、ログに記録されたエラーメッセージの内容は参照できないため、ローカルでテストを再現することで原因を調査するアプローチを取ります。そのため、ローカル環境で再現できない種類の失敗（環境変数の不足、外部サービスとの依存など）は自動修正が困難になる場合があります。
ビルドログを参照した上での修正精度向上を検討する場合は、CircleCI APIまたはCircleCI MCPサーバーの設定が別途必要になります。
まとめ
Claude CodeのAuto Fix機能をCircleCIで動作させるには、以下の4つの設定が必要です。
- CircleCIでGitHub App連携を有効化する（GitHub Checks）
- Claude CodeのGitHub Appパーミッションを更新する（Webhook・Checks Read/Write）
- PRを作成する
- Claude CodeのUIで「自動修正」をオンにする
設定後は、PRのCIが失敗した際にClaude Codeが自動で失敗ジョブを特定し、ローカルで原因を調査して修正コミットをプッシュするところまでを自律的に実行します。
CircleCI GitHub App連携の詳細については以下を参照してください。