# バッチ設計書 14-Claude Code Security Review

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Claude Code Security Review」の設計を定義するものである。Anthropic社のClaude AIを活用してPull Requestのセキュリティレビューを自動化し、潜在的なセキュリティ脆弱性を早期に検出するバッチ処理について記載する。

### 本バッチの処理概要

**業務上の目的・背景**：ソフトウェア開発において、セキュリティ脆弱性の早期発見は重要である。従来の静的解析ツールでは検出困難な論理的脆弱性やコンテキスト依存の問題も、AIによるレビューで検出可能となる。本バッチは、Anthropic社が提供するclaude-code-security-reviewアクションを使用し、PRのコード変更に対してAI駆動のセキュリティレビューを実行する。これにより、人間のレビュアーがセキュリティ観点でのレビューに集中でき、開発効率とセキュリティ品質の両立を実現する。

**バッチの実行タイミング**：Pull Requestのopened、synchronize、reopenedイベント時に自動実行される。

**主要な処理内容**：
1. リポジトリのチェックアウト（完全な履歴を取得）
2. Claude Code Security Reviewアクションの実行
3. セキュリティ上の問題点の検出と分析
4. PRコメントへのレビュー結果投稿
5. レビュー結果のアーティファクトアップロード

**前後の処理との関連**：本バッチは他のCI/CDバッチと並列実行される。Dependency Review（No.11）やCodeQL（No.9）と補完関係にあり、多層的なセキュリティチェック体制を構成する。

**影響範囲**：Pull Request全体のコード変更、node_modules/dist/build/.next ディレクトリは除外

## バッチ種別

セキュリティレビュー / AI駆動分析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Pull Request（opened/synchronize/reopened） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| シークレット | ANTHROPIC_API_KEYが設定されていること |
| 権限 | contents: read、pull-requests: write、issues: write が付与されていること |

### 実行可否判定

Pull Requestのopened、synchronize、reopenedイベントが発生した場合に無条件で実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| claude-api-key | シークレット | Yes | - | Anthropic APIキー |
| comment-pr | boolean | No | true | PRにコメントを投稿するか |
| upload-results | boolean | No | true | 結果をアーティファクトにアップロードするか |
| exclude-directories | 文字列 | No | node_modules,dist,build,.next | 除外ディレクトリ |
| claudecode-timeout | 数値 | No | 20 | タイムアウト（分） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| PRの差分 | Git diff | レビュー対象のコード変更 |
| リポジトリ履歴 | Git | コンテキスト分析用 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestコメント | Markdown | セキュリティレビュー結果 |
| GitHub Artifacts | JSON/テキスト | 詳細なレビュー結果 |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | claude-code-security-reviewアクションにより自動生成 |
| 出力先 | GitHub Artifacts |
| 形式 | アクション依存 |

## 処理フロー

### 処理シーケンス

```
1. チェックアウト
   └─ fetch-depth: 0で完全履歴を取得
   └─ persist-credentials: false

2. Claude Code Security Review実行
   └─ Anthropic APIを呼び出し
   └─ PRの差分に対してセキュリティ分析を実行
   └─ 除外ディレクトリ（node_modules等）はスキップ

3. 結果投稿
   └─ comment-pr: trueによりPRにコメント投稿

4. アーティファクトアップロード
   └─ upload-results: trueにより結果を保存

5. ステータス設定
   └─ レビュー完了後にチェックステータスを設定
```

### フローチャート

```mermaid
flowchart TD
    A[PR opened/synchronize/reopened] --> B[チェックアウト]
    B --> C[完全履歴取得 fetch-depth: 0]
    C --> D[Claude Code Security Review実行]
    D --> E[セキュリティ分析]
    E --> F{セキュリティ問題検出?}
    F -->|あり| G[PRにコメント投稿]
    F -->|なし| H[クリーンレポート投稿]
    G --> I[アーティファクトアップロード]
    H --> I
    I --> J[ステータス: 成功]
    J --> K[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

データベース操作は行わない。

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| API_KEY_INVALID | 認証エラー | Anthropic APIキー無効 | シークレット設定を確認 |
| RATE_LIMIT | レート制限 | API呼び出し上限超過 | 一定時間待機後に再実行 |
| TIMEOUT | タイムアウト | 処理時間超過（20分） | PR差分のサイズを確認 |
| API_ERROR | APIエラー | Anthropic API障害 | 障害復旧後に再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | claude-code-security-reviewアクション内部で管理 |
| リトライ間隔 | アクション依存 |
| リトライ対象エラー | 一時的なAPIエラー |

### 障害時対応

1. GitHub Actions実行ログを確認し、エラー原因を特定
2. API関連エラーの場合：ANTHROPIC_API_KEYの有効性を確認
3. タイムアウトの場合：PR差分サイズの確認、claudecode-timeout値の調整を検討
4. 一時的な障害の場合：PRの再プッシュまたはワークフロー再実行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1 PR |
| 目標処理時間 | 20分以内（claudecode-timeout: 20） |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

同一PRに対する同時実行は許可される。ワークフローレベルでの排他制御は設定されていない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | PR番号、イベント種別 |
| 進捗ログ | 分析中 | 分析対象ファイル数 |
| 終了ログ | ワークフロー終了時 | 検出結果サマリー |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | GitHub Checks UI |
| タイムアウト | 20分（claudecode-timeout） | GitHub Checks UI |
| セキュリティ問題検出 | 1件以上 | PR コメント |

## 備考

- anthropics/claude-code-security-review@68982a6bf10d545e94dd0390af08306d94ef684cを使用
- timeout-minutes: 30（ジョブ全体）、claudecode-timeout: 20（AI処理部分）
- 除外対象：node_modules, dist, build, .next
- fetch-depth: 0でコンテキスト分析のための完全履歴を取得
