# バッチ設計書 16-Claude PR Creator

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Claude PR Creator」の設計を定義するものである。特定のラベル付与をトリガーとして、Claude Code（AI）を使用してIssueの内容に基づくコード実装とPull Request作成を自動化するバッチ処理について記載する。

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

**業務上の目的・背景**：開発タスクの効率化において、Issue記載の要件からコード実装までの時間を短縮することは重要である。本バッチは、「claude-create-pr」ラベルがIssueに付与された際に、Anthropic社のClaude Code Actionを使用して自動的にコード実装を行い、ドラフトPull Requestを作成する。これにより、定型的な実装タスクの自動化や、開発者の初期実装の補助を実現する。GitHub App Tokenを使用することで、適切な権限管理とセキュリティを確保している。

**バッチの実行タイミング**：Issueに「claude-create-pr」ラベルが付与された時に自動実行される。

**主要な処理内容**：
1. GitHub App Tokenの生成（LIAM_CODE_ASSISTANT）
2. リポジトリのチェックアウト
3. pnpm環境のセットアップ
4. Claudeの設定（lint hookを含む）
5. Claude Code Actionによるコード実装
6. 実装完了後のlint/test検証
7. 新規ブランチの作成とコミット
8. ドラフトPull Requestの作成
9. Issueへの結果コメント投稿

**前後の処理との関連**：PR Scheduler（No.1）により「claude-create-pr」ラベルが自動付与されることがある。作成されたPRはClaude PR Assistant（No.17）、Claude Code Security Review（No.14）、その他CI/CDバッチの対象となる。

**影響範囲**：対象Issue、新規ブランチ（claude/issue-{number}）、新規Pull Request、リポジトリコード

## バッチ種別

AI駆動開発 / 自動PR作成 / イベント駆動

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Issueへのclaude-create-prラベル付与 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ラベル | 「claude-create-pr」ラベルが付与されていること |
| シークレット | LIAM_CODE_ASSISTANT_APP_ID/PRIVATE_KEY、ANTHROPIC_API_KEYが設定されていること |
| 権限 | contents: write、pull-requests: write、issues: write が付与されていること |

### 実行可否判定

`github.event.label.name == 'claude-create-pr'`の条件が満たされた場合のみ実行。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| LIAM_CODE_ASSISTANT_APP_ID | シークレット | Yes | - | GitHub App ID |
| LIAM_CODE_ASSISTANT_PRIVATE_KEY | シークレット | Yes | - | GitHub App 秘密鍵 |
| ANTHROPIC_API_KEY | シークレット | Yes | - | Anthropic APIキー |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.issue.number | 数値 | Issue番号 |
| github.event.issue.title | 文字列 | Issueタイトル |
| github.event.issue.body | 文字列 | Issue本文 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 新規ブランチ | Git | claude/issue-{number}形式のブランチ |
| Pull Request | GitHub PR | ドラフトPR |
| Issueコメント | Markdown | PR作成結果の通知 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ブランチ命名 | claude/issue-{issue_number}-* |
| PRタイトル | Fix: {Issueタイトル} |
| PRボディ | Issue参照、Summary、Implementation Details、Auto-generated表記 |

## 処理フロー

### 処理シーケンス

```
1. ラベル検証
   └─ claude-create-prラベルか確認

2. GitHub App Token生成
   └─ actions/create-github-app-tokenでトークン取得

3. チェックアウト
   └─ App Tokenを使用

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

5. Claude設定
   └─ .github/scripts/setup-claude.sh実行（lint hook含む）

6. Claude Code Action実行
   └─ Issue内容に基づきコード実装
   └─ pnpm lint / pnpm test で検証
   └─ ブランチ作成とコミット

7. PR作成
   └─ 最新のclaude/issue-{number}ブランチを検索
   └─ ドラフトPRを作成

8. 結果通知
   └─ Issueにコメント投稿（成功/失敗）
```

### フローチャート

```mermaid
flowchart TD
    A[Issueにラベル付与] --> B{claude-create-pr?}
    B -->|いいえ| C[スキップ]
    B -->|はい| D[GitHub App Token生成]
    D --> E[チェックアウト]
    E --> F[pnpm-setup]
    F --> G[Claude設定]
    G --> H[Claude Code Action実行]
    H --> I[コード実装・ブランチ作成]
    I --> J{lint/test成功?}
    J -->|いいえ| K[修正・再試行]
    K --> J
    J -->|はい| L[ブランチ検索]
    L --> M{ブランチ存在?}
    M -->|いいえ| N[Issueにエラーコメント]
    M -->|はい| O{PR既存?}
    O -->|はい| P[スキップ]
    O -->|いいえ| Q[ドラフトPR作成]
    Q --> R[IssueにPRリンクコメント]
    C --> S[バッチ終了]
    N --> S
    P --> S
    R --> S
```

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| APP_TOKEN_FAILED | 認証エラー | GitHub App Token生成失敗 | App ID/Private Key設定を確認 |
| API_KEY_INVALID | 認証エラー | Anthropic APIキー無効 | ANTHROPIC_API_KEY設定を確認 |
| LINT_FAILED | 検証エラー | lint/format失敗 | 自動修正後に再コミット |
| NO_BRANCH | 実行エラー | ブランチが作成されなかった | Claudeの実行ログを確認 |
| PR_CREATE_FAILED | API エラー | PR作成失敗 | GitHub API制限、権限を確認 |

### リトライ仕様

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

### 障害時対応

1. 実行ログでエラー原因を特定
2. ブランチ未作成の場合：Claude Code Actionの出力を確認
3. PR作成失敗の場合：GitHub APIの制限状況を確認
4. 一時的障害の場合：ラベルを再付与して再実行

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

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

## パフォーマンス要件

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

## 排他制御

同一Issueに対する同時実行は許可されない。concurrency設定により、同一Issue番号の実行が重複した場合、先行する実行がキャンセルされる（cancel-in-progress: true）。

```yaml
concurrency:
  group: ${{ github.workflow }}-${{ github.event.issue.number }}
  cancel-in-progress: true
```

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | Issue番号、タイトル |
| 進捗ログ | Claude実行中 | 実装進捗 |
| 終了ログ | ワークフロー終了時 | 作成されたブランチ名、PR URL |
| エラーログ | エラー発生時 | エラー詳細、失敗したステップ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | Issueコメント |
| タイムアウト | 60分 | GitHub Checks UI |
| ブランチ未作成 | - | Issueコメント |

## 備考

- anthropics/claude-code-action v1.0.12（コミット: 777ffcbfc9d2e2b07f3cfec41b7c7eadedd1f0dc）を使用
- actions/create-github-app-token v2.1.4を使用
- actions/github-script v7.1.0を使用
- 許可ツール：Bash(pnpm fmt:*), Bash(pnpm install), Bash(pnpm lint:*), Bash(pnpm test:*)
- PRはドラフトモードで作成（draft: true）
- pre-commit hook失敗時は自動修正が必須（MANDATORY PRE-COMMIT HOOK POLICY）
- allowed_bots: liam-claude-code-action-bot[bot]
