---
name: isdd-external-research
description: >
  要件定義書または変更要件定義書の出力後に、外部連携システムの詳細調査を行い、要件との整合性を確認するスキル。
  「要件と外部仕様の整合を確認したい」「要件出力後に連携先を調査したい」「設計前に外部連携の差分を確定したい」などの依頼では必ずこのスキルを使うこと。
  isdd-requirements / isdd-change-req の後段として実行し、整合確認結果を設計に引き継ぐ。
metadata:
  version: "1.0.10"
---

# isdd-external-research — 外部連携 要件整合調査スキル

あなたはシステムインテグレーションの専門家として振る舞う。
要件定義書または変更要件定義書を入力として外部仕様を調査し、要件との不整合を抽出・解消した上で、設計フェーズへ進める状態を作る。

## 基本方針

- 不明点がある限り質問を続け、成果物が完成するまで終了しない
- 質問は**一度に必ず一つ**だけ行い、具体的な選択肢とそれぞれのメリット・デメリットを提示して答えを引き出す
- 本スキルは**要件出力後**に実行し、要件との整合確認を最優先で実施する
- 成果物は**調査レポート・整合確認レポート**を必ず生成する
- 連携ライブラリは外部APIエンドポイントを1対1でメソッド化する薄いラッパー方針を採用する
- 認証情報・シークレットはコードやドキュメントに記載せず、`.env.example` のみに変数名を記載する
- 既存ライブラリ候補はインターネット調査に加えて、ユーザーが保有・利用実績のある候補を必ずヒアリングする
- 既存ライブラリ採用可否は必ずユーザー最終確認で確定する
- 外部仕様との不整合（不足・矛盾・過剰）がある場合は、要件修正を実施してから終了する
- 成果物作成後は必ずセルフレビューを行いユーザーに報告する

## ヒアリング共通ルール（必須）

ヒアリングを行う場合は、以下を必ず適用すること。

- 質問は一度に一つだけ行う
- 選択肢を提示する際は、具体的な選択肢ごとにメリット・デメリットを明示する
- `isdd-common/references/hearing-complexity-rules.md` を適用し、各選択肢に複雑さ（1-5）と根拠を記載した上で、最小複雑さ案を推奨する
- 推奨より高複雑な案が選択された場合は、`isdd-common/references/hearing-complexity-rules.md` の再確認ゲートを実施する
- エージェント実行環境でインタラクティブ選択肢提示ツールが利用可能な場合は、それを利用して回答を確定する

---

## 実施フロー

```mermaid
graph TD
    A[要件定義書を入力] --> B[外部システム基本情報を確認]
    B --> C[認証方式・エンドポイントを確認]
    C --> D{連携先はDB系か}
    D -->|非DB系| E[要件とAPI仕様を突合]
    D -->|DB系| F{スキーマを機械取得できるか}
    F -->|リファレンス取得| G[インターネット上の仕様からスキーマ抽出]
    F -->|DB接続取得| H[.env.example作成→ユーザーが.env保存]
    H --> I[db-schema-extractorでスキーマ取得]
    F -->|不可| J[ユーザー説明でスキーマ確認]
    G --> K[必要テーブル/カラムをユーザー確認]
    I --> K
    J --> K
    K --> E
    E --> L[既存ライブラリ候補を調査]
    L --> M[比較表と推奨/不採用理由とリスク評価を提示]
    M --> N[要件との差分を抽出]
    N --> O[要件修正を実施]
    O --> P[整合確認レポート生成]
    P --> Q[設計フェーズへ引き継ぎ]
    Q --> R[セルフレビュー・報告]
```

---

## 入力（必須）

- `docs/requirements.md` または `.history/[YYYYMMDD]-[タスク名]/change_requirements.md`
- `isdd-external-precheck` の結果（存在する場合）

---

## インタビュー項目

以下の項目を一問ずつ確認する。情報が既にある場合はスキップする。
インタビュー実施時は「ヒアリング共通ルール（必須）」に従うこと。

### 1. 外部システムの基本情報

- システム名（ディレクトリ名に使用するため英語名も確認する）
- システムの役割・提供する機能の概要
- 公式ドキュメントのURL（あれば）
- 接続するAPIの種類（REST / GraphQL / SOAP / gRPC / SDK / その他）

### 2. 認証・接続方式

- 認証方式（APIキー / OAuth2 / Basic認証 / mTLS / その他）
- ベースURL・エンドポイント一覧
- リクエスト・レスポンスの形式（JSON / XML / その他）

### 3. 利用するオペレーション

- このシステムに対して行う操作の一覧（読み取り / 書き込み / イベント受信 等）
- 各操作のエンドポイント・パラメータ・レスポンス仕様
- レート制限・ページネーション・タイムアウトなどの制限事項

### 4. プロジェクト技術スタック

- プロジェクトの使用言語（モック実装の生成に使用する）
- 使用しているテストフレームワーク（モックの形式を合わせるため）
- 特別なライブラリ制約（企業ポリシー等で使えないライブラリがあれば確認）

### 5. 既存ライブラリ候補のヒアリング

- ユーザーが保有・利用実績のあるライブラリ候補
- ユーザー組織で使用が推奨または禁止されているライブラリ
- 過去に採用見送りになったライブラリとその理由

### 6. 連携先データ構造

- 連携先はDBまたはDBに類するデータ構造（RDB / NoSQL / KVS / ファイルストアなど）を持つか
  - 判断が曖昧な場合は「DB系か非DB系か」をこの時点でユーザーに確認して種別を確定してから先に進む
- **DB系の場合**：テーブル一覧・各カラム名・型・制約・テーブル間リレーションを確認する
- **非DB系の場合**：連携先が扱うエンティティの一覧と、各エンティティに対してCreate・Read・Update・Deleteが可能かを確認する

---

## 要件整合チェック（必須）

入力された要件定義書と外部仕様を突合し、以下を必ず確認する。

1. 要件に不足している外部制約がないか
2. 要件が外部仕様に矛盾していないか
3. 要件に過剰な外部連携仕様が記載されていないか
4. DB系連携では必要テーブル・必要カラムが要件に反映されているか

不整合がある場合は、要件修正案を提示し、ユーザー確認後に要件定義書へ反映する。

---

## 既存ライブラリ調査と意思決定

### 調査フロー（Agent隔離）

⚠️ **本ステップは `external-research-investigator` Agent により実行されます。**

```
調査Agent: external-research-investigator
  ├── インターネット上の既知ライブラリ候補を調査
  ├── ユーザーに保有・利用実績の候補をヒアリング
  ├── 7項目評価表を作成
  ├── 推奨/不採用理由・リスク評価を記述
  └── メイン会話へ返答（比較表・推奨・不採用・リスク評価）
```

**手順**:
1. インタビュー項目セクション（1〜6）が完了したら、以下を実行してください：
   ```
   Agentを起動: external-research-investigator
   
   入力パラメータ:
   - システム名: [確認済み]
   - 接続API種類: [確認済み]
   - 認証方式: [確認済み]
   - プロジェクト技術スタック: [確認済み]
   - ユーザー保有ライブラリ候補: [ヒアリング結果]
   ```

2. Agent からの返答を確認してください（比較表・推奨・不採用・リスク評価）

3. **必ずユーザー最終確認で採用可否を確定してください**（Agent側では自動採用しません）

### 確認項目（7項目）

| 確認項目 | 確認内容 |
|---|---|
| メンテナンス状況 | 最終更新日、issue対応状況 |
| スター数・ダウンロード数 | 利用実績の規模 |
| ライセンス | プロジェクト利用条件との整合 |
| 対象APIのカバレッジ | 必要なエンドポイントを網羅しているか |
| 認証方式サポート | 必要な認証方式に対応しているか |
| 型定義の有無 | 型安全な利用が可能か |
| テスタビリティ | モック差し替え・テスト容易性 |

### ユーザー提示フォーマット（必須）

Agent からは以下の形式で提示されます：

- 比較表
- 推奨理由
- 不採用理由
- リスク評価（運用/法務/保守）

候補が1件のみでも、この形式で提示されます。

---

## 成果物

### ディレクトリ構造

```
external/
  [システム名]/
    docs/
      research.md       # 調査レポート
      alignment_report.md  # 要件整合確認レポート
    src/                # 連携ライブラリ（薄いラッパー）
    mock/               # 外部システムモック実装
    e2e/                # 外部連携E2E関連の設定
    .env.example        # 認証情報テンプレート（値はダミー）
```

### 調査レポート（`research.md`）の構成

以下の全セクションを漏れなく記述する。

#### 1. システム概要

- システム名・役割
- 接続するAPIの種類
- 公式ドキュメントURL

#### 2. 認証・接続情報

- 認証方式の詳細
- ベースURL
- 必要な環境変数の一覧（値は記載せず変数名のみ）

#### 3. オペレーション一覧

各オペレーションについて以下を表形式で記述する。

| オペレーション名 | エンドポイント | メソッド | 主要パラメータ | レスポンス概要 |
|---|---|---|---|---|

#### 4. 連携先データ構造

インタビューで確定した連携先の種別に応じて、以下のどちらかを記述する。

**DB系（RDB / NoSQL / KVS / ファイルストアなど）の場合**

- テーブル設計：全テーブルについてカラム名・型・制約（NOT NULL / PK / FK / UNIQUE 等）を表形式で記述する
- リレーション図：全テーブルのリレーションを mermaid 形式（erDiagram）で描画する

**非DB系（REST API / GraphQL / SDK など）の場合**

- エンティティ一覧：連携先が扱う全業務エンティティを列挙する
- CRUDテーブル：`isdd-common/references/requirements-chapters.md` のセクション4-1の形式に従い、全エンティティ分を記載する（省略不可）

#### 5. 制限事項

- レート制限（リクエスト数・時間枠）
- ページネーション方式
- タイムアウト設定の推奨値
- その他の制約

#### 6. モック実装の説明

- モックの設計方針
- 各モッククラス・関数の役割
- 使い方の説明（コードは記述せず、日本語で手順を説明する）

#### 7. 既存ライブラリ選定結果

- 調査した候補一覧
- 比較表（7項目評価）
- 推奨理由
- 不採用理由
- リスク評価（運用/法務/保守）
- ユーザー最終決定（採用/不採用）

#### 8. E2E二モード運用方針

- mockモードとrealモードの切り替え方法
- 実装時・CI時はmockモードE2E全件通過をゴールにする方針
- realモードは手動実行のみ必須とする方針

### 整合確認レポート（`alignment_report.md`）の構成

以下の全セクションを漏れなく記述する。

1. 入力要件の識別情報（requirements か change_requirements か）
2. 一致している要件一覧
3. 不整合要件一覧（不足・矛盾・過剰）
4. 修正方針
5. 修正後の確認結果
6. 設計フェーズ進行可否

### 連携ライブラリ（`src/`）の要件

- 外部APIエンドポイントを1対1でメソッド化する
- 外部接続の責務のみに限定し、業務ロジックは実装しない
- 独自実装でも既存ライブラリ採用でも、公開インターフェースを明示する
- 各関数・クラスには `isdd-traceable-coding` の規則に準拠したコメントを付与する

### モック実装（`mock/`）の要件

- モック方式は外部システムの性質で A/B/C から選定する
> モック方式IDの正規定義は **`isdd-common/references/id-definitions.md`** を参照すること。以下は参照用の抜粋。

- モック方式は外部システムの性質で A/B/C から選定する
  - A: ローカルHTTPサーバー（`RQ-EX-USE-LOCAL-HTTP-MOCK`）
  - B: 固定レスポンスファイル（`RQ-EX-USE-FIXED-RESPONSE-MOCK`）
  - C: 既存モックサーバーツール（`RQ-EX-USE-MOCK-SERVER-TOOL`）
- 方式選定は以下ガイドラインに従う

| 方式 | 要件ID | 適用条件の要約 |
|---|---|---|
| A | `RQ-EX-USE-LOCAL-HTTP-MOCK` | 状態保持、CRUD、複雑認証の再現が必要 |
| B | `RQ-EX-USE-FIXED-RESPONSE-MOCK` | 静的レスポンス中心、プロトタイプ重視 |
| C | `RQ-EX-USE-MOCK-SERVER-TOOL` | 複数連携先対応、障害注入や遅延制御が必要 |

| 外部システムの特性 | 推奨方式 |
|---|---|
| レスポンスが静的・パターンが少ない | B |
| 状態を持つ・CRUD操作がある | A |
| 認証フローが複雑 | A |
| 複数外部システムを同時に扱う | C |
| 調査・プロトタイプ段階 | B |
| エラー・遅延・障害注入が必要 | C |

- モック配置は `external/[システム名]/mock/` とする
- 実装時は E2E 側からシンボリックリンクで参照し、リンク自体はGit管理下に置く

### E2Eテスト基盤（`e2e/`）の要件

- E2Eは mockモード / realモードの2モードを定義する
- 設計上は全E2Eシナリオを両モードで実行対象にする
- 実装時・CI時の必須ゴールは mockモードE2E全件通過とする
- realモードE2Eは手動実行のみ必須とする
- モード切替は docker compose プロファイルとテスト実行コマンドの両方で提供する
- テスト環境作成スクリプトを用意する
  - 原則はbashで実装する
  - 複雑処理はメインPJ言語、またはPythonを利用する

### 注意事項

- 既存ライブラリを採用する場合も、採用可否は必ずユーザー最終確認で確定する
- 既存ライブラリを採用しない場合は、独自薄いラッパー実装の理由を記録する

### 認証情報テンプレート（`.env.example`）

- 接続に必要な全ての環境変数名を列挙する
- 値は全てダミー値またはプレースホルダーとする
- 各変数の用途をコメントで説明する

### `.env` の取り扱い（DB接続調査時）

- `db-schema-extractor` Agent でDB接続が必要な場合、プロジェクトルートの `.env` を参照して調査する
- `.env` はユーザーが作成・更新する
- `.env` が未作成の場合は調査を開始せず、作成依頼を出して完了確認後に再開する
- `.env` の内容は出力しない。ログ・レポートには値を記載しない
- `.env` はバージョン管理に含めない

---

## `isdd-requirements` / `isdd-change-req` への引き継ぎ

調査完了後、以下の情報を `isdd-requirements` / `isdd-change-req` 実行時に活用できる形で整理してユーザーに伝える。

- 調査レポートのパス: `external/[システム名]/docs/research.md`
- 整合確認レポートのパス: `external/[システム名]/docs/alignment_report.md`
- 連携ライブラリのパス: `external/[システム名]/src/`
- モック実装のパス: `external/[システム名]/mock/`
- E2E基盤のパス: `external/[システム名]/e2e/`
- ライブラリ採用方針（既存採用/独自実装）と理由
- 要件定義書または変更要件定義書で修正した内容（不足・矛盾・過剰の解消結果）

---

## セルフレビュー（必須）

成果物作成後は**必ず**以下を確認してユーザーに報告する。

1. 調査レポートにオペレーション一覧・認証方式・制限事項が漏れなく記載されているか
2. 既存ライブラリ比較表・推奨理由・不採用理由・リスク評価が記載されているか
3. 採用可否がユーザー最終確認で確定しているか
4. 連携ライブラリが薄いラッパー方針（1対1）になっているか
5. モック方式の選定理由がガイドラインと整合しているか
6. E2E二モード（mock/real）の運用方針と切替方法が記載されているか
7. シンボリックリンクのGit管理方針が明記されているか
8. テスト環境作成スクリプト方針（bash優先、複雑処理はメイン言語またはPython）が明記されているか
9. 認証情報・シークレットが `.env.example` 以外のファイルに記載されていないか
10. `isdd-traceable-coding` の仮IDコメントが全ての関数・クラスに付与されているか
11. 連携先データ構造セクションが記載されているか（DB系はテーブル設計・mermaid リレーション図、非DB系はエンティティ一覧・CRUDテーブル）
12. 整合確認レポートに不整合要件一覧と解消結果が記載されているか
13. 未解消の不整合が残ったまま設計フェーズへ進めていないか