# バッチ設計書 17-Claude PR Assistant

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Claude PR Assistant」の設計を定義するものである。@claudeメンション時にClaude Code（AI）を使用してコード支援やレビュー対応を自動化するバッチ処理について記載する。

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

**業務上の目的・背景**：開発者がIssueやPull Requestのコメントで@claudeとメンションすることで、AIによるコード支援を受けられる仕組みを提供する。これにより、コードレビューへの対応、バグ修正の提案、リファクタリングなど、様々な開発タスクをAIがサポートする。開発者はコメント形式で自然言語の指示を出すだけで、Claude Code Actionが適切なコード変更やIssue/PR作成を行う。

**バッチの実行タイミング**：Issue/PRコメント、PRレビューコメント、PRレビュー、Issue作成/アサイン時に、本文に@claudeが含まれる場合に自動実行される。

**主要な処理内容**：
1. @claudeメンションの検出
2. リポジトリのチェックアウト
3. pnpm環境のセットアップ
4. Claudeの設定（lint hookを含む）
5. Claude Code Actionによるコード変更・コメント対応
6. lint/test検証と必要に応じた修正
7. コミット・プッシュ
8. 必要に応じてIssue/PR作成

**前後の処理との関連**：Claude PR Creator（No.16）で作成されたPRに対してユーザーが追加指示を出す際に使用される。Claude Code Security Review（No.14）と並行して、PRの品質向上に貢献する。

**影響範囲**：対象Issue/PR、リポジトリコード、コメントスレッド

## バッチ種別

AI駆動開発 / コード支援 / イベント駆動

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | @claudeメンション（Issue/PRコメント、レビュー等） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| メンション | コメント/レビュー本文に@claudeが含まれること |
| シークレット | ANTHROPIC_API_KEYが設定されていること |
| 権限 | contents: write、pull-requests: write、issues: write、id-token: write、actions: read が付与されていること |

### 実行可否判定

以下の条件のいずれかが満たされた場合に実行：
- issue_comment.created で comment.bodyに@claude含む
- pull_request_review_comment.created で comment.bodyに@claude含む
- pull_request_review.submitted で review.bodyに@claude含む
- issues.opened/assigned で issue.bodyに@claude含む

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| ANTHROPIC_API_KEY | シークレット | Yes | - | Anthropic APIキー |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.comment.body | 文字列 | コメント本文 |
| github.event.review.body | 文字列 | レビュー本文 |
| github.event.issue.body | 文字列 | Issue本文 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| コード変更 | Git commit | 指示に基づくコード修正 |
| Issue/PR | GitHub | 必要に応じて作成 |
| コメント | Markdown | 処理結果の返信 |

### 出力ファイル仕様

特定のファイル形式は定義されない。指示内容に応じてコード変更が行われる。

## 処理フロー

### 処理シーケンス

```
1. イベント検出
   └─ コメント/レビュー/Issueイベントを受信

2. メンション検証
   └─ @claudeが本文に含まれるか確認

3. チェックアウト
   └─ fetch-depth: 1

4. pnpm-setup
   └─ ローカルアクション実行

5. Claude設定
   └─ .github/scripts/setup-claude.sh実行

6. Claude Code Action実行
   └─ 指示内容に基づき処理
   └─ lint/test検証

7. 結果反映
   └─ コード変更のコミット・プッシュ
   └─ 必要に応じてIssue/PR作成
```

### フローチャート

```mermaid
flowchart TD
    A[イベント発生] --> B{@claude含む?}
    B -->|いいえ| C[スキップ]
    B -->|はい| D[チェックアウト]
    D --> E[pnpm-setup]
    E --> F[Claude設定]
    F --> G[Claude Code Action実行]
    G --> H[指示解析・処理]
    H --> I{コード変更?}
    I -->|はい| J[lint/test実行]
    J --> K{成功?}
    K -->|いいえ| L[修正・再試行]
    L --> J
    K -->|はい| M[コミット・プッシュ]
    I -->|いいえ| N[コメント応答]
    M --> O[バッチ終了]
    N --> O
    C --> O
```

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| API_KEY_INVALID | 認証エラー | Anthropic APIキー無効 | ANTHROPIC_API_KEY設定を確認 |
| RATE_LIMIT | レート制限 | API呼び出し上限超過 | 一定時間待機後に再実行 |
| LINT_FAILED | 検証エラー | lint/format失敗 | 自動修正後に再コミット |
| TIMEOUT | タイムアウト | 処理時間超過（60分） | 指示内容を簡素化して再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | lint/format失敗時は自動修正・再試行 |
| リトライ間隔 | 即時 |
| リトライ対象エラー | pre-commit hook失敗 |

### 障害時対応

1. 実行ログでエラー原因を特定
2. API関連エラーの場合：ANTHROPIC_API_KEYの有効性を確認
3. lint失敗の場合：自動修正が完了するまで待機
4. タイムアウトの場合：指示を分割して再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（Gitベースの操作） |
| コミットタイミング | Claude Code Actionによる自動コミット |
| ロールバック条件 | 手動でコミットを取り消し |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1コメント/レビュー |
| 目標処理時間 | 60分以内（timeout-minutes: 60） |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

ワークフローレベルでの排他制御は設定されていない。同一PRに対する複数の@claudeメンションは並列実行される可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | イベント種別、対象PR/Issue |
| 進捗ログ | Claude実行中 | 処理進捗 |
| 終了ログ | ワークフロー終了時 | 処理結果 |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | GitHub Checks UI |
| タイムアウト | 60分 | GitHub Checks UI |

## 備考

- anthropics/claude-code-action v1.0.12（コミット: 777ffcbfc9d2e2b07f3cfec41b7c7eadedd1f0dc）を使用
- 許可ツール：
  - Bash(pnpm fmt:*), Bash(pnpm install), Bash(pnpm lint:*), Bash(pnpm test:*)
  - mcp__github__create_issue, mcp__github__add_issue_comment, mcp__github__create_pull_request
- MANDATORY PRE-COMMIT HOOK POLICYをシステムプロンプトに含む
- fetch-depth: 1で浅いクローン（処理速度優先）
- id-token: write権限を付与（OIDC認証用）
