AIが書いたコード、誰がレビューするの？Claude Code Actionで解決した話

はじめに

こんにちは。ピクトリンク開発部でWebアプリケーション開発を担当している西村です🧑‍💻

最近はAIの進歩が目まぐるしく、Claude CodeやCodexを使用してコードを書くことが当たり前の時代になりました。開発効率が上がった実感はありますが、その一方で「このAIが書いたコード、プロジェクトのルールに合っているのか？」というレビューの悩みも増えてきました。今回はClaude Code Actionを使って、PRを作成したら自動で開発方針をチェックしてくれる仕組みを構築したので、そのお話をしたいと思います。

なぜ自動レビューが必要になったのか

AIがコードを書く時代の新しい悩み

Claude CodeやCodexのおかげで開発が効率化された反面、使用していくうちに以下のような課題が見えてきました。

コードの一貫性が保ちにくい: AIは文脈を完全には理解できないため、プロジェクトのルールから少し逸脱したコードを書いてしまうことがある
レビューの負担が増えた: 見慣れない実装パターンが増えて、「これは正しいのか？」と確認する手間が増えた
暗黙のルールが伝わらない: チームで暗黙的に行っているルールがドキュメント化されておらず、新しいメンバーに伝わりにくい

取り組んだこと

この課題に対して、2つの取り組みを行いました。

開発方針をドキュメントにまとめる: 暗黙知を明文化
自動レビューの仕組みを作る: Claude Code Actionで方針チェックを自動化

まずは開発方針をドキュメント化

自動レビューを実現するには、まず「何をチェックするか」を明確にする必要があります。そこで、チームで以下のドキュメントを整備しました。

作成したドキュメント

カテゴリ	ファイル数	内容
テスト関連	5ファイル	テスト戦略、単体テスト、E2Eテスト、統合テストの方針
設計方針	9ファイル	ディレクトリ構成、コンポーネント設計、BFF、状態管理、スタイリングなど
その他	5ファイル	ブランチ運用、命名規則、PR作成ルール、CI/CDルール

ドキュメント作成時に意識したこと

コード例を添える: 「こうすべき」だけでなく、良い例・悪い例を併記する
理由を明記する: なぜこのルールが必要なのかを説明する
AIがチェックしやすい形式にする: 曖昧な表現を避けて、明確な基準を設定する

Claude Code Actionの設定

ワークフロー設定

以下のように設定しています。

name: Claude Assistant

on:
  pull_request:
    types: [opened]

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: claude-${{ github.event.pull_request.number || github.run_id }}
  cancel-in-progress: true

jobs:
  claude-response:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          claude_args: "--model claude-opus-4-5-20251101"
          prompt: |
            docs/配下にあるドキュメント群は開発方針です。
            PRの差分に対してこれらの開発方針に沿っているかをチェックし、以下を出力してください。

            ## 出力形式
            - コメントの冒頭に、必ずマージ可能か不可かを明示的に記述すること
            - 差分コードが開発方針に沿っていれば、その旨を明記し、マージ可能である趣旨を簡潔に記述する
            - 開発方針に沿っていない場合は、マージ不可である趣旨を明記し、どの開発方針に沿っていないかを具体的に指摘し、修正方法の具体例を提示する

            ## 指摘の構成
            - 指摘内容は「要約」「詳細指摘」「改善案」の3部構成で記述すること
            - 方針に沿っている良い点も簡潔に言及すること
            - 指摘の際は、なぜ問題になるのか（開発体験・保守性・ユーザー価値への影響）も補足すること

            ## 注意事項
            - レビュー対象は差分部分に限定すること（範囲外のコード全体レビューは不要）
            - レビュー結果は必ず日本語で出力すること

設定のポイント

プロンプトの工夫

結果を最初に表示: マージ可否を冒頭に記載させることで、一目で判断できる
3部構成にする: 要約→詳細→改善案の流れで、修正すべき内容がすぐに理解できる
スコープを限定する: 「差分だけ見て」と指定しないと、関係のない箇所まで指摘される可能性がある

実行順序のイメージ

レビュー結果のイメージ

実際にClaude Code Actionが出力するレビュー結果のイメージをご紹介します。

マージ可能パターン

## ✅ マージ可能

本PRは開発方針に沿っており、マージ可能です。

---

### 要約

このPRは〇〇機能の改善を行っています。主な変更は以下の通りです：

1. **セキュリティ強化**: △△の対策を追加
2. **コード品質向上**: □□の改善
3. **保守性向上**: ××の整理

---

### 良い点 ✅

| 項目 | 説明 |
|------|------|
| **セキュリティ** | 適切なセキュリティ対策が実装されている |
| **権限の明示化** | 必要最小限の権限が明示的に宣言されている |
| **保守性** | DRY原則に沿った実装になっている |
| **命名規則** | プロジェクトの命名規則に準拠している |

### 開発方針との整合性 ✅

| 方針 | 準拠状況 |
|------|----------|
| CI/CDパイプラインルール | ✅ 既存の構成に沿っている |
| コード品質ルール | ✅ KISS原則・DRY原則に沿った実装 |
| 命名規則 | ✅ 規則に準拠 |
| PRサイズ | ✅ 1つの関心ごとに絞られている |

---

### 総評

本PRは開発方針に完全に沿った変更です。
**マージを推奨します。**

---

### レビュー情報
- **使用モデル**: Claude Opus 4.5
- **入力トークン数**: 約15,000トークン
- **出力トークン数**: 約1,200トークン

マージ不可パターン

## ⚠️ マージ不可（要修正）

---

### 📋 要約

**差分内容:**
- 〇〇の制御を追加

**問題点:**
1. **コードの重複**: DRY原則に違反している箇所がある
2. **テストコードの欠如**: ユニットテストが含まれていない
3. **コメント不足**: ビジネス背景の説明がない

**良い点:**
- 既存の仕組みを適切に利用している
- コミットメッセージにチケット番号が含まれている

---

### 🔍 詳細指摘

#### 1. DRY原則違反（コードの重複）

**問題点:**
- 同じコンポーネントが複数箇所に重複して記述されている
- コード品質ルールの「DRY原則」に違反

**なぜ問題か:**
- 将来的な変更時に複数箇所を修正する必要があり保守性が低下
- コードの読み手の理解に時間がかかる

#### 2. テストコードの欠如

**問題点:**
- PRルール「ユニットテストの作成を含める」に違反
- テスト方針「バグ修正時はテストを必ず書く」にも該当

**なぜ問題か:**
- 条件分岐が正しく動作することが保証されない
- リグレッション発生時に検知できない

---

### 💡 改善案

#### 改善案1: コードの重複を解消する

共通部分を変数に抽出し、条件分岐を早期リターンで簡潔に記述することを推奨します。

#### 改善案2: テストコードを追加する

条件の真偽に応じて表示が切り替わることを検証するテストを追加してください。

#### 改善案3: コメントの追加

なぜこの制御が必要なのか、ビジネス背景を説明するコメントを追加してください。

---

### 📊 修正チェックリスト

- [ ] コードの重複を解消し、DRY原則に準拠している
- [ ] ユニットテストを追加している
- [ ] ビジネス背景を説明するコメントを追加している
- [ ] テストが成功することを確認
- [ ] Lintエラーがないことを確認
- [ ] ビルドが成功することを確認

---

### レビュー情報
- **使用モデル**: Claude Opus 4.5
- **入力トークン数**: 約20,000トークン
- **出力トークン数**: 約2,500トークン

導入してみた結果

良かった点

レビュー負担の軽減

「方針に沿っているか？」のチェックをAIが担当するため、レビュアーはロジックや設計の議論に集中できる
PR作成直後にフィードバックが得られるため、レビュー待ち時間が削減された

コード品質の安定化

レビュアーによる判断のばらつきが減少した
AIが生成したコードでも、プロジェクトのルールに沿った形で修正が促される

まとめ

AIがコードの大部分を実装する時代になり、質の低いコード生成や見慣れないパターンが増えることで、開発者の認知負荷が高まるという新たな課題が生まれています。だからこそ、適切なコーディングルールを維持し、保守性や可読性を保つことが重要です。これは単に人間のためだけでなく、AI自身が質の高いコードを生成しやすい環境を整えることにもつながると思います。 AIにコードを書いてもらう時代だからこそ、AIにレビューも手伝ってもらう。この仕組みが皆さんのチームでも参考になれば幸いです。