notfolder 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.mdisdd-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が可能かを確認する
要件整合チェック（必須）
入力された要件定義書と外部仕様を突合し、以下を必ず確認する。
- 要件に不足している外部制約がないか
- 要件が外部仕様に矛盾していないか
- 要件に過剰な外部連携仕様が記載されていないか
- DB系連携では必要テーブル・必要カラムが要件に反映されているか
不整合がある場合は、要件修正案を提示し、ユーザー確認後に要件定義書へ反映する。
既存ライブラリ調査と意思決定
調査フロー（Agent隔離）
⚠️ 本ステップは external-research-investigator Agent により実行されます。
調査Agent: external-research-investigator
├── インターネット上の既知ライブラリ候補を調査
├── ユーザーに保有・利用実績の候補をヒアリング
├── 7項目評価表を作成
├── 推奨/不採用理由・リスク評価を記述
└── メイン会話へ返答（比較表・推奨・不採用・リスク評価）
手順:
インタビュー項目セクション（1〜6）が完了したら、以下を実行してください：
Agentを起動: external-research-investigator 入力パラメータ: - システム名: [確認済み] - 接続API種類: [確認済み] - 認証方式: [確認済み] - プロジェクト技術スタック: [確認済み] - ユーザー保有ライブラリ候補: [ヒアリング結果]Agent からの返答を確認してください（比較表・推奨・不採用・リスク評価）
必ずユーザー最終確認で採用可否を確定してください（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）の構成
以下の全セクションを漏れなく記述する。
- 入力要件の識別情報（requirements か change_requirements か）
- 一致している要件一覧
- 不整合要件一覧（不足・矛盾・過剰）
- 修正方針
- 修正後の確認結果
- 設計フェーズ進行可否
連携ライブラリ（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）
- A: ローカルHTTPサーバー（
方式選定は以下ガイドラインに従う
| 方式 | 要件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-extractorAgent で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対1）になっているか
- モック方式の選定理由がガイドラインと整合しているか
- E2E二モード（mock/real）の運用方針と切替方法が記載されているか
- シンボリックリンクのGit管理方針が明記されているか
- テスト環境作成スクリプト方針（bash優先、複雑処理はメイン言語またはPython）が明記されているか
- 認証情報・シークレットが
.env.example以外のファイルに記載されていないか isdd-traceable-codingの仮IDコメントが全ての関数・クラスに付与されているか- 連携先データ構造セクションが記載されているか（DB系はテーブル設計・mermaid リレーション図、非DB系はエンティティ一覧・CRUDテーブル）
- 整合確認レポートに不整合要件一覧と解消結果が記載されているか
- 未解消の不整合が残ったまま設計フェーズへ進めていないか
次のステップ
完了を報告する際に、ユーザーに次のスキルを提案する。
- 新規開発の場合:
isdd-designを実行して詳細設計書を作成する - 変更開発の場合:
isdd-change-designを実行して変更詳細設計書を作成する