Isdd external research

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

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

基本方針

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

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

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

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

---

実施フロー

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テーブル：.agents/skills/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の正規定義は .agents/skills/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. 未解消の不整合が残ったまま設計フェーズへ進めていないか

---

次のステップ

完了を報告する際に、ユーザーに次のスキルを提案する。

• 新規開発の場合: isdd-design を実行して詳細設計書を作成する
• 変更開発の場合: isdd-change-design を実行して変更詳細設計書を作成する