# バッチ設計書 12-triage.yml

## 概要

本ドキュメントは、新規Issue作成時に自動トリアージを実行するGitHub Actionsワークフローの設計書です。AIエージェントを使用してIssueを分類・ラベル付けします。

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

このバッチは、リポジトリに新しいIssueが作成された際に自動的に実行され、専用のトリアージエージェントを使用してIssueを分析・分類します。

**業務上の目的・背景**：大規模なオープンソースプロジェクトでは、毎日多くのIssueが作成されます。メンテナーがすべてのIssueを手動で確認・分類するのは時間がかかり、対応の遅延につながります。このバッチにより、Issueの初期トリアージを自動化し、メンテナーが重要なIssueに集中できる環境を提供します。

**バッチの実行タイミング**：Issueが新規作成された時（opened）にイベントドリブンで即座に実行されます。

**主要な処理内容**：
1. リポジトリのチェックアウト（fetch-depth: 1）
2. Bun環境のセットアップ
3. opencodeのインストール
4. triageエージェントにIssueタイトルと本文を渡して分析実行
5. エージェントによる自動ラベル付け・分類

**前後の処理との関連**：duplicate-issues.ymlワークフローと同じIssue openedイベントで並行実行されます。トリアージ結果は後続のIssue対応フローで活用されます。stale-issues.ymlによる自動クローズ処理の判断材料にもなります。

**影響範囲**：GitHub Issues（ラベル付与、分類）、Issue対応ワークフロー全体

## バッチ種別

イベントドリブン / AI分析処理 / 自動分類

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント発生時（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | GitHub Issues イベント（opened） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| OPENCODE_API_KEY | OpenCode APIキーがSecretsに設定されていること |
| GITHUB_TOKEN | GitHub Actionsの自動生成トークンが利用可能であること |
| triageエージェント | opencodeにtriageエージェントが定義されていること |

### 実行可否判定

- Issue openedイベントで自動実行（条件分岐なし）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| ISSUE_NUMBER | number | Yes | - | Issue番号（環境変数経由） |
| ISSUE_TITLE | string | Yes | - | Issueタイトル（環境変数経由） |
| ISSUE_BODY | string | Yes | - | Issue本文（環境変数経由） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Issue | GitHub Event | 新規作成されたIssueの情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Issue Labels | API | トリアージ結果のラベル |
| GitHub Issue Metadata | API | 分類情報 |

### 出力ファイル仕様

ファイル出力はありません。すべてGitHub API経由で出力されます。

## 処理フロー

### 処理シーケンス

```
1. Issue openedイベント受信
   └─ GitHub Actionsワークフロー起動
2. 環境セットアップ
   └─ チェックアウト、Bunセットアップ、opencode インストール
3. トリアージ実行
   └─ triageエージェントにIssue情報を渡す
4. 結果適用
   └─ エージェントがラベル付け・分類を実行
```

### フローチャート

```mermaid
flowchart TD
    A[Issue opened] --> B[チェックアウト]
    B --> C[Bunセットアップ]
    C --> D[opencode インストール]
    D --> E[triageエージェント実行]
    E --> F[Issue分析・分類]
    F --> G[ラベル付与]
    G --> H[終了]
```

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

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

本バッチはデータベースを直接操作しません。GitHub APIを経由してIssueメタデータを更新します。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| ラベル付与 | GitHub Issue | UPDATE | トリアージ結果のラベル付与 |

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

該当なし（GitHub API経由のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API認証エラー | OPENCODE_API_KEYが無効 | Secrets設定を確認 |
| - | エージェント未定義 | triageエージェントが存在しない | エージェント設定を確認 |
| - | GitHub APIエラー | レート制限超過 | 自動リトライ待機 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actionsデフォルト設定に従う |
| リトライ間隔 | - |
| リトライ対象エラー | ネットワークエラー、一時的なAPI障害 |

### 障害時対応

1. ワークフロー実行ログを確認
2. 必要に応じて手動でIssueをトリアージ
3. triageエージェントの設定を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各API呼び出し単位 |
| コミットタイミング | 各操作完了時（即座） |
| ロールバック条件 | 自動ロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件/実行 |
| 目標処理時間 | 60秒以内 |
| メモリ使用量上限 | GitHub Actionsランナー標準 |

## 排他制御

同一Issueに対するduplicate-issues.ymlとの並行実行が許可されています。各ワークフローは独立して動作し、GitHub APIの整合性により競合は発生しません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | Issue番号、タイトル |
| 進捗ログ | 各ステップ完了時 | ステップ名、実行結果 |
| 終了ログ | ワークフロー終了時 | 成功/失敗ステータス |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub Actions通知 |

## 備考

- triageエージェントは専用のエージェント設定ファイルで定義される（`--agent triage`オプション使用）
- Issue本文は環境変数経由でエージェントに渡される
- 他のIssue関連ワークフロー（duplicate-issues.yml）と同時に実行される可能性がある
