# バッチ設計書 13-Agent Deep Modeling

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Agent Deep Modeling」の設計を定義するものである。AIエージェントのディープモデリングプロセスを実行し、スキーマ解析やAI処理のテストを自動化するバッチ処理について記載する。

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

**業務上の目的・背景**：本プロジェクトはAIエージェント機能を搭載しており、その中核となるディープモデリング処理の品質を継続的に検証する必要がある。本バッチは、エージェント関連コード（agent、artifact、db、schema、pglite-server）に変更が加えられた際に、Supabaseローカル環境を起動し、OpenAI API及びLangSmithと連携したディープモデリングプロセスを実行する。これにより、AI機能の回帰を早期に検出し、プロダクト品質を維持する。

**バッチの実行タイミング**：Pull Request作成時・更新時に、特定のパス（agent、artifact、db、schema、pglite-server関連ファイル）に変更がある場合のみ自動実行される。

**主要な処理内容**：
1. Supabaseローカル環境の起動とAPIキー抽出
2. schemaパッケージのビルド
3. OpenAI・LangSmith連携によるディープモデリング処理の実行
4. 実行結果（処理時間、成功/失敗）のPRコメントへの投稿
5. 失敗時のCI失敗ステータス設定

**前後の処理との関連**：本バッチは他のCI/CDバッチ（Frontend CI等）と並列実行される。pnpm-setupアクションに依存し、schemaパッケージのビルドを前提とする。

**影響範囲**：@liam-hq/agentパッケージ、Supabaseローカルデータベース、OpenAI API、LangSmith

## バッチ種別

AI処理 / テスト自動化 / ディープモデリング

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Pull Request（特定パス変更時のみ） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| パス変更 | agent/artifact/db/schema/pglite-server関連ファイルの変更 |
| シークレット | OPENAI_API_KEY、LANGSMITH_API_KEY等が設定されていること |
| 権限 | contents: read、pull-requests: write が付与されていること |

### 実行可否判定

以下のパスに一致するファイルの変更がある場合に実行：
- `frontend/internal-packages/agent/**`
- `frontend/internal-packages/artifact/**`
- `frontend/internal-packages/db/**`
- `frontend/packages/schema/**`
- `frontend/internal-packages/pglite-server/**`
- `.github/workflows/agent-deep-modeling.yml`

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| OPENAI_API_KEY | シークレット | Yes | - | OpenAI APIキー |
| LANGSMITH_API_KEY | シークレット | Yes | - | LangSmith APIキー |
| LANGSMITH_PROJECT | シークレット | Yes | - | LangSmithプロジェクト名 |
| LANGSMITH_ORGANIZATION_ID | シークレット | Yes | - | LangSmith組織ID |
| LANGSMITH_PROJECT_ID | シークレット | Yes | - | LangSmithプロジェクトID |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Supabaseローカル環境 | PostgreSQL | テスト用データベース |
| .env.template | 環境変数 | 環境変数テンプレート |
| @liam-hq/schema | TypeScript | スキーマ解析パッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| execution_log.md | Markdown | 実行ログ（処理時間、結果等） |
| PRコメント | Markdown | スティッキーコメントとして投稿 |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | execution_log.md |
| 出力先 | ワークスペースルート |
| 文字コード | UTF-8 |
| 形式 | Markdown |

## 処理フロー

### 処理シーケンス

```
1. チェックアウト
   └─ persist-credentials: false

2. pnpm-setup
   └─ ローカルアクション./.github/actions/pnpm-setupを実行

3. Supabase起動
   └─ pnpm --filter @liam-hq/db supabase:start

4. 環境変数設定
   └─ .env.templateを.envにコピー

5. Supabaseキー抽出
   └─ extract-supabase-anon-key.sh / extract-supabase-service-key.sh実行

6. schemaパッケージビルド
   └─ pnpm build --filter @liam-hq/schema

7. ディープモデリング実行
   └─ pnpm --filter @liam-hq/agent execute-deep-modeling
   └─ 実行時間計測、結果をexecution_log.mdに記録

8. PRコメント投稿
   └─ marocchino/sticky-pull-request-commentでコメント

9. 結果判定
   └─ 失敗時はexit 1
```

### フローチャート

```mermaid
flowchart TD
    A[PR作成/更新] --> B{対象パス変更?}
    B -->|なし| C[スキップ]
    B -->|あり| D[チェックアウト]
    D --> E[pnpm-setup]
    E --> F[Supabase起動]
    F --> G[環境変数設定]
    G --> H[Supabaseキー抽出]
    H --> I[schemaビルド]
    I --> J[ディープモデリング実行]
    J --> K[execution_log.md生成]
    K --> L[PRコメント投稿]
    L --> M{実行成功?}
    M -->|はい| N[ステータス: 成功]
    M -->|いいえ| O[ステータス: 失敗]
    C --> P[バッチ終了]
    N --> P
    O --> P
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ディープモデリング | Supabaseローカル | SELECT/INSERT/UPDATE | AIモデリング処理でテストデータを操作 |

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

Supabaseローカル環境を使用するため、本番データベースへの影響はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SUPABASE_START_FAILED | 環境エラー | Supabase起動失敗 | Dockerの状態確認、再実行 |
| API_KEY_MISSING | 設定エラー | APIキー未設定 | シークレット設定を確認 |
| OPENAI_ERROR | APIエラー | OpenAI API呼び出し失敗 | APIキー・レート制限確認 |
| MODELING_FAILED | 処理エラー | ディープモデリング失敗 | ログを確認し原因調査 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（continue-on-error: trueで継続） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. execution_log.mdの内容を確認
2. Supabase起動失敗の場合：Dockerリソースを確認
3. API関連エラーの場合：シークレット設定とAPI利用状況を確認
4. ディープモデリング失敗の場合：@liam-hq/agentパッケージのログを詳細確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | Supabaseローカル環境内 |
| コミットタイミング | 処理完了時 |
| ロールバック条件 | テスト環境のため自動クリーンアップ |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回のディープモデリング実行 |
| 目標処理時間 | 30分以内（timeout-minutes: 30） |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

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

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | 開始時刻（UTC） |
| 進捗ログ | ディープモデリング中 | コマンド出力をリアルタイム記録 |
| 終了ログ | バッチ終了時 | 終了時刻、処理時間、成功/失敗ステータス |
| エラーログ | エラー発生時 | exit code、エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | GitHub Checks UI、PRコメント |
| タイムアウト | 30分 | GitHub Checks UI |

## 備考

- NO_COLOR: 1環境変数でカラー出力を無効化
- marocchino/sticky-pull-request-comment v2.9.4を使用してスティッキーコメントを投稿
- 処理時間は人間が読みやすい形式（例：5m 30s）で表示
- continue-on-error: trueにより、失敗してもPRコメント投稿は実行される
