Tech

Claude Code Auto-Fix 実践ガイド — CI失敗・PRコメント・autofix PR運用を自動化する

nidoneko · · 12 min read
Claude CodeCI/CDGitHub Actions開発効率化
🔧

Claude Code Auto-Fix で何ができるか

「CIが落ちた。ログを読んで、修正して、pushして、また待つ」や、「PRコメントが付いたので直して再レビューに戻す」——この反復を 1 日に何度もやるのは無駄です。

Claude Code の Auto-Fix は、この反復作業をクラウド上で自動化する機能です。Web/Mobile セッションから PR を監視し、CI失敗の検知 → ログ解析 → 修正コミット → 再実行までを自律的に回せます。さらに PR レビューコメントにも対応できるため、claude code autofix pr / claude autofix / claude code auto fix のように「PR単位でどこまで任せられるか」を知りたい人の関心にも直結します。

ただし、この機能を「何でも自動で直してくれる魔法」だと思って導入すると痛い目に遭います。実際には、autofix CI の適用範囲、PR コメント対応の任せ方、止めどころを決めて初めて運用に乗ります。本記事では、セットアップ手順だけでなく、実際に使って分かった失敗パターンと CLAUDE.md による品質制御まで踏み込んで解説します。

Claude Code の基本運用や CLAUDE.md、Hooks、権限管理の前提をまだ固めていない場合は、先に Claude Code 実践ガイド を読む方が順序として自然です。Auto-Fix は単体機能というより、既存の運用設計が整って初めて効く支援記事だからです。チーム配布ルールまで含めて設計したい場合は、AIコーディングツールの社内ガイドライン も合わせて参照してください。

Auto-Fix の仕組み — 何が起きているのか

Auto-Fix は単純な「エラーを検知して修正する」ツールではありません。内部では以下のループが回っています。

PR作成 → CI実行 → gh CLI でステータスポーリング
  → 失敗検知 → ログ取得・解析 → 修正コード生成
  → コミット＆プッシュ → CI再実行 → 全パス確認

ポイントは gh CLI によるポーリングです。Claude Code は GitHub CLI を使って CI のチェック結果を定期的に取得し、失敗を検知します。つまり、ローカルの CLI セッションだけでなく、Web/Mobile のクラウドセッションからもリモートで動作します。

Desktop での有効化

デスクトップアプリでは、PR を作成すると CI ステータスバーがセッション内に表示されます。ここに2つのトグルがあります。

  • Auto-fix: CI 失敗を自動修正するかどうか
  • Auto-merge: 全チェックがパスしたら自動マージするかどうか

Auto-merge を使う場合は、GitHub リポジトリ側でも Auto-merge の設定を有効にしておく必要があります。

クラウドセッションの強み

この機能の本質的な価値は「クラウドで動く」ことにあります。従来の CI 修正はローカルの Claude Code セッションに張り付く必要がありましたが、Auto-Fix ならセッションを Web/Mobile に切り替えてバックグラウンドで動かせます。つまり：

  1. ローカルで開発 → PR 作成
  2. Web/Mobile セッションで Auto-Fix を有効化
  3. ローカルでは次のタスクに着手
  4. 戻ってきたら PR は green（あるいは修正途中の差分が確認可能）

この「並行作業」ができることが、単なる CI 修正の自動化を超えた生産性向上をもたらします。

GitHub Actions で autofix CI を回す

Desktop/Mobile の Auto-Fix だけでなく、GitHub Actions と組み合わせることで、完全にサーバーサイドで CI 修正を回すことも可能です。

セットアップ手順

公式の claude-code-action リポジトリに設定例が用意されています。基本的な構成は以下の通りです。

# .github/workflows/claude-auto-fix.yml
name: Claude Auto-Fix CI

on:
  workflow_run:
    workflows: ["CI"] # 監視対象のワークフロー名
    types:
      - completed

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}

      - uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            CIが失敗しました。ログを確認し、原因を特定して修正してください。
            修正後はフォーマットとテストを実行して確認してください。
          claude_args: |
            --allowedTools "Edit,MultiEdit,Write,Read,Glob,Grep,Bash(git:*),Bash(npm:*),Bash(npx:*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

この構成のポイントは3つです。

  1. workflow_run トリガー: CI ワークフローの完了をフックに起動する
  2. conclusion == 'failure': 失敗時のみ実行する条件分岐
  3. --allowedTools: claude_args 経由で Claude が使えるツールを明示的に制限する

CLAUDE.md でガードレールを設定する

ここがほとんどの解説記事が見落としている重要なポイントです。GitHub Actions で Auto-Fix を使う場合、CLAUDE.md がガードレールの役割を果たします。

# CLAUDE.md（CI Auto-Fix 用ガードレール）

## 修正後の必須チェック

- `pnpm run lint` を実行してフォーマットエラーがないことを確認
- `pnpm run test` を実行して全テストがパスすることを確認
- `pnpm run build` を実行してビルドが成功することを確認

## 禁止事項

- テストコードを削除・スキップして CI をパスさせない
- 型エラーを `any` でごまかさない
- 既存の public API の型を変更しない

CLAUDE.md がない、あるいは曖昧な記述しかない状態で Auto-Fix を走らせると、Claude は「CI をパスさせること」を最優先にして、テストを削除したり any で型エラーを潰したりすることがあります。これは実際に私が経験した失敗です。

PRレビューコメントへの自動対応

Auto-Fix は CI 失敗だけでなく、PR に付いたレビューコメントにも対応します。特に、リンターやセキュリティスキャナーなどのボットが残したコメントの自動修正に威力を発揮します。検索意図として多い autofix pr は、実際には「PR 全体を無人化したい」のではなく、機械的に直せるコメントだけを先回りで消したいケースが中心です。

GitHub Marketplace にある PR Autofix Action では、以下のフローが実現できます。

ボットがPRにコメント → Action がコメント読み取り
  → Claude が修正コード生成 → 同じブランチにプッシュ
  → 再度ボットがチェック → クリーンになるまで繰り返し
  → 最終的に人間がレビュー

ここで重要なのは、最終レビューは人間が行うという設計思想です。Auto-Fix はあくまでボットコメントの機械的な修正を自動化するもので、設計判断を伴うレビューコメントへの対応は人間に委ねるべきです。

実際に使って分かった5つの落とし穴

1. コンテキスト枯渇で修正品質が劣化する

Auto-Fix が複数回のイテレーションを重ねると、コンテキストウィンドウが圧迫されます。コンテキスト圧縮（compaction）が走った後は、修正の精度が明らかに下がります。具体的には、先に修正したファイルの変更内容を忘れて矛盾した修正を入れることがあります。

対処法: CLAUDE.md に「3回の修正試行で解決しない場合は、修正を中断して原因をコメントとして残す」と明記しておく。

2. テストを”修正”して CI を通す

これが最も危険なパターンです。本来はプロダクションコードにバグがあるのに、テストの期待値を書き換えて CI をパスさせることがあります。

対処法: CLAUDE.md に「テストの期待値を変更する場合は、必ずコミットメッセージに理由を記載する」と書く。さらに、Auto-merge は有効にせず、人間が差分を確認してからマージする。

3. 型エラーを any で潰す

TypeScript プロジェクトでよく発生します。複雑な型エラーに対して、as any や @ts-ignore で応急処置をすることがあります。

対処法: CLAUDE.md に型安全のルールを明記する。ESLint の @typescript-eslint/no-explicit-any ルールを CI に含めておくと、Auto-Fix が any を使った場合に再度 CI が落ちるので、二重のガードになります。

4. 無関係なファイルを巻き込む

CI の失敗原因を探索する過程で、問題と無関係なファイルを「改善」してしまうことがあります。リファクタリングが混入した PR は、レビューの負荷が上がります。

対処法: allowed_tools で Bash コマンドの範囲を制限する。Bash(git:add) Bash(git:commit) 程度に絞り、Bash(git:checkout) は許可しないなど、操作可能な範囲を最小限にする。

5. 修正ループから抜け出せない

Auto-Fix が修正 → CI 失敗 → 別の修正 → 別の CI 失敗…と無限ループに入ることがあります。特にE2Eテストやインテグレーションテストの失敗で発生しやすいです。

対処法: GitHub Actions のワークフローに timeout-minutes を設定して、暴走を防ぐ。max_retries のようなジョブレベルのリトライ設定は GitHub Actions の標準構文には存在しないため、タイムアウトによる強制終了が最もシンプルかつ確実な対策です。

jobs:
  auto-fix:
    timeout-minutes: 15 # 15分でタイムアウト

Auto-Fix を最大限に活かす CLAUDE.md 設計

ここまで見てきた通り、Auto-Fix の品質は CLAUDE.md の設計に大きく依存します。Auto-Fix 専用のセクションを追加することを推奨します。

## CI Auto-Fix ガイドライン

### 修正の優先順位

1. ビルドエラー（import パス、型エラー）
2. リントエラー（フォーマット、未使用変数）
3. テスト失敗（ロジックエラー）

### 修正方針

- テストを修正する場合は、テストが間違っている根拠をコミットメッセージに記載する
- `any`, `@ts-ignore`, `eslint-disable` の使用は禁止
- 修正対象は CI ログに直接関連するファイルに限定する
- 3回の試行で解決しない場合は中断し、PR にコメントで状況を報告する

### 修正後の検証手順

1. `pnpm run lint`
2. `pnpm run typecheck`
3. `pnpm run test`
4. `pnpm run build`

重要なのは、修正後の検証手順を明示することです。Auto-Fix はこの手順に従ってセルフチェックを行うため、漏れがあるとすり抜けます。

Desktop Auto-Fix vs GitHub Actions — どちらを選ぶべきか

Desktop Auto-FixGitHub Actions
動作環境Web/Mobile/Desktop クライアントGitHub サーバーサイド
トリガーPR 作成時に手動有効化ワークフロー完了イベント
コストClaude Code サブスクリプション内API キー課金（トークン従量制）
カスタマイズ性低（トグルのON/OFFのみ）高（YAML で詳細設定可能）
推奨ユースケース個人開発、小規模プロジェクトチーム開発、CI パイプラインが複雑なプロジェクト

私の結論としては、個人開発なら Desktop Auto-Fix で十分、チーム開発なら GitHub Actions 一択です。チーム開発では、CLAUDE.md によるガードレールと allowed_tools によるツール制限が不可欠だからです。

まとめ — Auto-Fix は「ハーネス設計」で真価を発揮する

Auto-Fix は、正しく設定すれば CI 修正の反復作業から解放してくれる強力な機能です。しかし「有効にすれば勝手にうまくいく」というものではありません。

CLAUDE.md によるガードレール設計、allowed_tools による権限制御、タイムアウトの設定——これらの「ハーネス（制御装置）」を整えることで初めて、Auto-Fix は信頼できる自動化ツールになります。

導入のステップとしては：

  1. まず Desktop Auto-Fix で小さな PR から試す（Auto-merge は OFF）
  2. 修正内容を人間が確認し、CLAUDE.md のルールを追加・修正する
  3. 安定したら GitHub Actions に移行し、チーム全体で運用する
  4. Auto-merge は十分な CI カバレッジが確保できてから有効化する

「イテレーションこそが王道」——Auto-Fix の運用も例外ではありません。小さく始めて、ルールを磨き続けることが、この機能を使いこなす鍵です。

導入全体の地図が必要なら Claude Code 実践ガイド、ローカルでの強制ルール設計を詰めたいなら Claude Code Hooks の使い方 実践ガイド、組織配布ルールまで含めて整えたいなら AIコーディングツールの社内ガイドライン も合わせて参照してください。

WRITTEN BY nidoneko

Full-stack engineer with 8+ years of experience in TypeScript, React, Node.js, and cloud-native development across healthcare, finance, HR, and IoT domains.

View Profile →
// Related articles View All
🧠
Claude Code

Claude Code サブエージェント運用ガイド — 並列委譲・コンテキスト分離・レビュー役分担の実践

·14 min read

Claude Code のサブエージェント運用を実務目線で解説します。main 会話との使い分け、並列委譲、レビュー役分担、権限とツール制限、worktree 分離まで、実際に事故りやすい論点に絞って整理しました。

Read More →
📋
AIコーディング

AIコーディングツールの社内ガイドライン — 安全運用テンプレと判断基準

·10 min read

AIコーディングツールを社内導入したいが、何を禁止し何を許可すべきか曖昧な方向けに、最小構成の社内ガイドラインをテンプレ付きで整理します。入力データ、実行権限、レビュー境界、監査、MCP の扱いまで実務向けにまとめました。

Read More →
🧩
AIエージェント

マルチエージェントオーケストレーション 4パターン解説 — 逐次・並列・階層・フィードバックループの使い分け

·9 min read

マルチエージェントオーケストレーションを実務に入れたい方向けに、逐次・並列・階層・フィードバックループの4パターンを整理します。どの業務に向くか、壊れやすい点、監視項目まで実装目線で解説します。

Read More →