generate-connectivity-knowledge

Name: generate-connectivity-knowledge
Author: mulesoft

github.com/mulesoft開発14226 回インストール今日更新

generate-connectivity-knowledge について

専用の Mule コネクターがない SaaS API の連携情報を作成し、Mule HTTP-Connector のワークフローで利用するスキルです。API を調査して OpenAPI 3.0 仕様を生成し、実サービスで各操作を検証します。

主な機能

01API ドキュメントとエンドポイントの調査
02OpenAPI 3.0 仕様の生成
03実サービスに対する操作の検証
04認証・ページネーション・エンティティ情報の整理
05API リファレンスと設定用プレースホルダーの出力

活用シーン

01専用 Mule コネクターがない SaaS の HTTP 連携情報を準備
02生成した API 操作とリクエスト・レスポンスを検証
03OpenAPI 仕様を Exchange や他のツールに渡す

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mulesoft/mulesoft-dx --skill generate-connectivity-knowledge

インストール後、Claude Code で/generate-connectivity-knowledgeを入力して読み込まれたか確認します。

同梱ファイルreferences/examples.md

詳細

接続性ナレッジの生成

このスキルは、Exchange に専用の Mule コネクタがない SaaS と統合するために、Mule HTTP-Connector フローで必要となる接続性ナレッジを生成します。次の 3 段階を順に実行します — API を調査する、OpenAPI 3.0 仕様を生成する、稼働中のサービスに対してすべての操作を検証する — そして、api-reference.md、<apiName>.yaml、プレースホルダーの config.properties を含む、自己完結したフォルダーを connectivity-schema/<apiName>/ に作成します。

build-mule-integration は、あるシステムに適切なコネクタが見つからない場合、Step 3a（HTTP フォールバック分岐）からこのスキルを呼び出します。フロー生成ツールはその後、生成されたナレッジを読み込み、適切な認証、ページネーション、エンティティの形状を使って HTTP Request 操作を構成します。

出力を利用するユーザー

build-mule-integration の Phase 2 — api-reference.md の Authentication、Rate Limits、Use Cases、Entity Reference セクションを使用して、HTTP Request の設定と DataWeave 変換を生成します。
マージ後のユーザー — <apiName>.yaml は、Exchange に公開したり、ほかのツールに入力したりできる正式な OpenAPI 3.0 仕様です。

このスキルが生成するすべての成果物は、これらの利用者の少なくとも 1 つに役立つものである必要があります。リクエストの構築、レスポンスの検証、依存関係の接続、認証情報の収集のいずれにも役立たない情報は、ここに含めないでください。

自律性の原則

調査と仕様生成の段階は、ユーザーへのプロンプトなしで自律的に実行します。ライブ検証の段階も、次の 4 つの必須の一時停止ポイントを除き、自律的に実行します。

認証情報の収集 — config.properties が存在しない場合、または必須キーが不足している場合、スキルはプレースホルダーを含むファイルを作成し、ユーザーに入力を依頼して待機します。必須です — 検証を省略したり、プレースホルダーのレポートを書いたり、認証情報なしで先に進んだりしてはいけません。
エンティティ ID — 操作で既存のエンティティへの参照が必要な場合、スキルはユーザーにその情報を提供するよう依頼します。
破壊的操作の確認 — DELETE または破壊的な PUT を実行する前に、スキルは影響についてユーザーに警告し、確認を求めます。
解決できない失敗 — 検証ループの完了後に失敗した操作がある場合、スキルは今後の対応（再試行／維持／削除／キャンセル）をユーザーに確認します。

認証エラー（401／403）が発生した場合は、ループを直ちに停止して停止レポートを表示します。これは対話形式の一時停止ではなく、ループが単に停止するだけです。

それ以外のすべて — 操作の選択、リクエストの構築、実行、スキーマの比較、エラー処理、再試行 — はユーザーに見えない形で行われます。ユーザーには、簡潔な進捗行と最終結果が表示されます。

認証情報のセキュリティ — 必須

これらのルールはワークフロー全体を通して適用されます。違反は重大な失敗です。

config.properties の認証情報の値を読み取る、表示する、エコーする、ログに記録する、または推論することは絶対にしないでください。
認証情報のキーが存在することを確認するには、grep -c '^KEY_NAME=' config.properties を使用してください。これは値ではなく、件数（0 または 1）を返します。
認証情報を curl コマンドに渡すには、インラインのシェル置換 $(grep '^KEY_NAME=' config.properties | cut -d'=' -f2-) を使用してください。値はシェル内を通りますが、会話コンテキストには入りません。
curl コマンドの出力に認証情報が誤って含まれていた場合（エラーメッセージ内など）、その出力を繰り返してはいけません。機密情報を含めずに結果を要約してください。

ワークフロー

INPUTS → DOC_DISCOVERY → PRIMARY_ENDPOINTS → PRIMARY_ENTITIES → CRUD_COMPLETION
       → DEPENDENCY_ANALYSIS → SECONDARY_CRUD → ACTION_PLAN → DEEP_RESEARCH
       → API_REFERENCE_CONSOLIDATION → OPENAPI_SPEC_GENERATION
       → VALIDATION_PREREQUISITES → VALIDATION_LOOP → FINAL_REPORT

以下の手順を順番に実行してください。先の手順に進んではいけません — 各手順は、直前の手順の出力に依存します。

ステップ 1：入力

$ARGUMENTS から以下の情報を解析します。不足している場合はユーザーに確認します。

apiName — kebab-case 形式の SaaS プラットフォーム／API 名（例：canva-lms、jira、coda）。これは connectivity-schema/ の下のサブフォルダー名、および OpenAPI ファイル名になります。
useCases — 統合に必要な、具体的な操作を 1 つ以上指定します。例：
- 「最新のコースを取得し、新しいコースがあれば通知する」
- 「Jira チケットを取得し、ステータスを更新する」
Project Folder (任意) — 出力ファイルを書き込むディレクトリです。デフォルトは <workspaceRoot>/connectivity-schema/<apiName>/ です。<workspaceRoot> は、アクティブな VS Code ワークスペースに解決します。ワークスペースが開いていない場合は、現在の作業ディレクトリに解決します。
documentation (任意) — API ドキュメントを指す URL を 1 つ以上指定します。指定されている場合（呼び出し元のスキルから渡される場合など）、ステップ 2 では検索の代わりにこれらを直接使用します。

項目 1～2 が指定されていることを確認します。どちらかが不足している場合はユーザーに確認してください。両方が揃うまでは進めないでください。

このスキルの以降の手順では、{PROJECT_FOLDER} は解決済みの Project Folder を指します。まだ存在しない場合は作成してください。

ステップ 2：ドキュメントの調査

調査中にエージェントが参照する API ドキュメントを見つけます。

ステップ 1 でドキュメントの URL が指定されている場合： 各 URL を WebFetch で取得し、アクセス可能で、エンドポイントのドキュメントが含まれていることを確認します。指定された URL がすべて有効な場合は、それらをドキュメントソースとして使用し、下記の選定ステップ（4）に進みます。指定された URL にアクセスできない、またはエンドポイントのドキュメントが含まれていない場合に限り、WebSearch に進みます。

WebSearch で API の公式ドキュメントを検索します。次の内容を検索してください：
- 公式 REST API リファレンス（例："{apiName} REST API reference"）
- OpenAPI／Swagger 仕様（例："{apiName} OpenAPI spec"）
- 開発者ポータルまたは API エクスプローラー
機械可読なソースを優先します — 下流のエージェントが必要とする正確なフィールド型、必須／任意の区別、スキーマ定義が含まれているため、OpenAPI 仕様や構造化された REST リファレンスは、ブログ記事やチュートリアルよりも有用です。
最も信頼性の高いソースを選び、選定理由を記録します。 通常は、文脈や例を確認するための人間向け API リファレンスと、正確なスキーマを確認するための機械可読な仕様の 2 つが必要です。
選定したドキュメントページを WebFetch で取得し、アクセス可能で、エンドポイントのドキュメントが含まれていることを確認します。ソースに問題がある、または役に立たない場合は、代替を探してください。

確認済みでアクセス可能なドキュメントソースが少なくとも 1 つ見つかるまでは、先に進まないでください。

実例については、references/examples.md の「ステップ 2：ドキュメントの調査」を参照してください。

ステップ 3：主要エンドポイントの特定

各ユースケースを特定の API エンドポイントに対応付けます。これらは、ユーザーが明示的に指定したエンドポイントです。

重要 — ユースケースによる絞り込み。 このスキルでは、ユーザーのユースケースと、接続テスト用のエンドポイント 1 つ（ステップ 11 で追加）をカバーする最小限の仕様を作成します。API が提供するすべてのエンドポイントを含めないでください。目標は包括的なカタログではなく、必要最小限で忠実な仕様です。

各ユースケースについて、確認済みの API ドキュメントを読み、次の項目を特定します。

列	記録する内容	理由（後続の利用者向け）
ユースケースのアクション	エンドポイントが実行する内容	仕様生成のコンテキスト
メソッド	HTTP メソッド（GET、POST、PUT、DELETE）	仕様生成で OpenAPI オペレーションを構築するため
パス	パラメーターのプレースホルダーを含む正確なパス	仕様生成と検証で URL を構築するため
パスパラメーター	パラメーター名と型	仕様生成で OpenAPI のパス項目に型を指定するため
ボディの有無	エンドポイントがリクエストボディを受け付けるかどうか	検証でボディを送信すべきか判断するため
コンテンツタイプ	通常は `application/json`	仕様生成でコンテンツタイプを設定するため

次の列を過不足なく含む対応表を作成します。

| Use Case Action | Method | Path | Path Parameters | Has Body | Content Type |
|---|---|---|---|---|---|
| ... | GET | /resource/{id} | id (string) | No | application/json |

ユースケースが複数のエンドポイントに対応する場合（例：Jira チケットのステータス更新には単純な PUT ではなく、Transitions API が必要）、すべてを含め、相違点を記載します。

ユースケースをエンドポイントに対応付けられない場合は、そのことを明示して理由を説明します。

すべてのユースケースが少なくとも 1 つのエンドポイントに対応付けられるまで、先に進まないでください。

作業例については、references/examples.md →「Step 3: Primary Endpoint Identification」を参照してください。

ステップ 4：主要エンティティの抽出

主要エンドポイントが操作するエンティティを特定し、その識別子を記録します。

識別子フィールドは、ステップ 13 の検証ループにおいて重要です。テストエンティティを作成するとき、後続のリクエストで使用する ID がレスポンスのどのフィールドに含まれるかを把握する必要があります。正確に特定してください。

次の列を過不足なく含む表を作成します。

| Entity | Identifier Field | Alt Identifier | Role |
|---|---|---|---|
| Issue | id (string) | key (string, PROJ-123) | Primary |
| Project | id (string) | key (string, PROJ) | Secondary (dependency) |

CRUD のカバレッジ不足について、別の表を作成する必要はありません。ステップ 5 の CRUD カタログで、Source 列を使ってユースケース由来の操作と CRUD 補完による操作を記録します。

すべての主要エンティティとその識別子フィールドが特定されるまで、先に進まないでください。

ステップ 5：CRUD の補完

各主要エンティティについて、不足している CRUD 操作のエンドポイントを探します。検証ループでは、テストデータを管理するために次の操作が必要です。

作成 → test-setup — ユースケースの実行前にテストエンティティを作成する
一覧表示／検索 → test-validation — 操作が機能したことを検証する
削除 → test-cleanup — テスト後にクリーンアップする
読み取り／更新 → エンドポイントが存在する場合、CRUD の対象範囲を補完する

次の列を含む表を作成します。

列	記録する内容
操作	Create、Read、Update、Delete、List
メソッド	HTTP メソッド
パス	パラメーターのプレースホルダーを含む正確なパス
パスパラメーター	パラメーター名と型
ボディの有無	真偽値
ライフサイクル上の目的	`test-setup`、`test-validation`、`test-cleanup`、または `—`

API に CRUD 操作が存在しない場合（例：Delete エンドポイントがない場合）は、そのことを明記します。検証ループでは、これがクリーンアップ戦略に影響することを把握する必要があります。

すべての主要エンティティの CRUD の不足分を補完するまで、先に進まないでください。

ステップ 6：依存関係の分析

主要エンティティが存在するために必要とするエンティティを特定します。これは検証ループにおいて最も重要なフェーズです。処理の順序、テストデータ作成の連鎖、テスト開始前にセットアップが必要なエンティティをここで決定します。

必須の依存関係テスト

主要エンティティが参照する各エンティティについて、次のテストを適用します。

「このエンティティへの参照を指定せずに主要エンティティを作成した場合、API はエラーを返しますか？」

YES → セカンダリエンティティ — 含めます。検証ループでは、主要エンティティを作成する前にこれを作成する必要があります。

NO → 除外 — 関係は任意なので、省略します。

参照フィールドの詳細を記録する

必須の依存関係ごとに、以下を記録してください。

列	記録する内容	理由
参照先エンティティ	依存先エンティティ名	検証時に作成する対象を把握する必要があります
必須フィールド	正確な JSON フィールドパス（例：`fields.project.id`）	検証時に作成リクエストでこのフィールドを設定する必要があります
参照形式	ID とキーのどちらを使用するか	依存先の作成レスポンスから抽出する識別子を把握する必要があります
判定	SECONDARY ENTITY / PRE-EXISTING / EXCLUDED	次の手順を決定します

既存の依存先

一部の必須フィールドは、API 経由では作成も削除もできないシステム管理エンティティ（Jira の課題タイプ、優先度、ステータスなど）を参照します。これらは二次エンティティではありません。テストでは作成する代わりに、有効な値を検出します。既存の依存先ごとに、有効な値を返すList/Get エンドポイントを記録してください。

ツリーを再帰的にたどる

二次エンティティ自体に必須の依存関係がある場合があります。同じテストを再帰的に適用し、必須の依存関係を持たず単独で作成できるエンティティに到達するまで続けてください。

依存関係図を作成する

依存関係ツリーを示す Mermaid 図を作成してください。必須の依存関係には実線の矢印を、既存の依存関係には破線の矢印を使用してください。各矢印にフィールド参照を含めてください。

すべての判定を文書化する

採用、除外、既存としての分類をすべて、その理由とともに記録してください。ワークフローは完全に自律して実行されます。完了後に判定を確認できるようにする必要があります。

依存関係ツリー全体のマッピングとすべての判定の文書化が完了するまで、次に進まないでください。

Step 7：二次エンティティの CRUD

Step 6 で特定した二次エンティティごとに、完全な CRUD エンドポイントを調査してください。検証ループでは、以下のためにこれらが必要です。

作成：依存関係チェーンを末端から作成する（例：Issue の前に Project を作成する）
削除：依存関係チェーンを最上位から削除する（例：Project の前に Issue を削除する）

Step 5（CRUD の完了）と同じ表の形式を使用し、各二次エンティティのライフサイクル上の目的ラベルと識別子フィールドを含めてください。

すべての二次エンティティの CRUD エンドポイント一覧がそろうまで、次に進まないでください。

Step 8：アクションプラン

すべての調査結果を、下流の利用者ごとに整理した構造的なアクションプランにまとめてください。これが調査および計画フェーズの最終成果物です。

アクションプランを次のセクションに分けて作成します

1. 仕様生成向け（ステップ 11）

主要エンドポイントカタログ — OpenAPI のオペレーションになります。次の表形式を使用してください。

| Use Case Action | Method | Path | Path Parameters | Has Body | Content Type |
|---|---|---|---|---|---|
| {action} | {method} | {path} | {params or —} | {Yes/No} | {content type} |

識別子フィールドを含むエンティティ一覧 — スキーマ定義になります

2. ライブ検証向け（ステップ 12～13）

ライフサイクルの目的ラベルを付けた完全な CRUD エンドポイントカタログ（主要＋二次） — 検証ループでは、テストデータの作成に test-setup エンドポイントを使用し、削除に test-cleanup を使用します
フィールド参照を含む依存関係グラフ（Mermaid 図） — オペレーションの順序を決定します
作成順序（下から上）と削除順序（上から下） — 各順序は番号付きリストではなく、1 行にインラインの矢印表記（→）を使用してください（例：A を作成 → B を作成 → C を作成）
検出エンドポイントを含む既存の依存関係 — 検証ループでは、作成を試みる代わりに、これらを呼び出して有効な値を取得します
決定ログ — すべての依存関係に関する決定（二次として含める、既存、除外）とその理由を 1 つの表にまとめ、各エンティティを含めた、または含めなかった理由を検証ループで確認できるようにします

3. 認証情報の収集向け（ステップ 12）

ドキュメントから特定できた認証方式（この段階で判明している場合）：種類（Bearer、API Key、Basic、OAuth）、必要な認証情報キー、ヘッダー形式
認証の詳細がまだ不明な場合は、ステップ 9 の詳細調査で確認する項目として記載します

4. 調査計画

調査順序：まず二次エンティティ（依存関係ツリーの下位）を調査し、次に主要エンティティを調査します。こうすることで、主要エンティティを記述する時点で、その依存関係の詳細が判明しています。
範囲：調査対象のエンティティ総数、発見したエンドポイント総数
除外したエンティティとその理由

アクションプランを作成する

Write ツールを使って、アクションプランを {PROJECT_FOLDER}/action-plan.md に保存します。このファイルには発見した内容が保持され、詳細調査フェーズ（ステップ 9）で使用されます。

完全な作成例については、references/examples.md →「Step 8: Action Plan」を参照してください。

ステップ 9：詳細調査

調査計画に記載されている各エンティティについて、API ドキュメントを読み、後続の利用者がリクエストを作成し、レスポンスを検証し、依存関係を接続し、認証情報を収集するために必要な、詳細なスキーマ、フィールド、動作を記録します。

入力： ステップ 8 のアクションプラン（{PROJECT_FOLDER}/action-plan.md）には、調査順序、エンドポイントカタログ、依存関係グラフ、およびステップ 2 で確認したドキュメントのソースが記載されています。

ドキュメントソースの優先順位： リクエスト／レスポンスのスキーマとフィールドの詳細については、ステップ 2 で利用可能な場合、OpenAPI 仕様を主な情報源として使用してください。OpenAPI 仕様には、正確な型、必須／任意のマーカー、スキーマ定義が記載されています。ページネーションのパターン、レート制限の動作、副作用、仕様に記載されていない動作の詳細については、人間が読める API リファレンスを補足として使用してください。OpenAPI 仕様がない場合は、すべて人間が読めるドキュメントを使用してください。

重要： フィールド名、型、制約はドキュメントの記載どおりに正確に転記してください。フィールドの詳細を推測したり、憶測で補ったりしないでください。

処理順序

アクションプランの「調査計画」セクションに従ってください。

まず API レベルの注記（認証方式とレート制限）を調査します。これらは全体に適用されます。
次に 既存のエンティティを記録します（簡易的な扱いとし、検出スキーマのみを記載します）。
二次エンティティを下から上の順序で調査します（依存関係ツリーの最下位から開始します）。
最後に 主要エンティティを調査します。

各エンティティの調査を完了したら、すぐにその内容を出力ファイルに書き込みます。すべての調査内容を会話内に蓄積してから書き込むことはしないでください。

API レベルの注意事項

個々のエンティティを調査する前に、API レベルのカテゴリを 2 つ記録してください。WebFetch を使って、API の認証とレート制限に関するドキュメントページを取得します。

項目	記録する内容	理由（後続の利用者向け）
認証タイプ	Bearer、Basic、API Key、OAuth	認証情報の収集には、注入パターンが必要です
ヘッダー形式	正確なヘッダー名と値のパターン	検証ではリクエストヘッダーを構築します
必須の認証情報	認証情報のキー名	認証情報の収集時にユーザーに入力を求めます
ベース URL	URL パターン（変数部分を明記）	検証ではリクエスト URL を構築します
グローバルレート制限	1 秒あたり／1 分あたりのリクエスト数	検証ではリクエストの頻度を調整します
429 の動作	Retry-After ヘッダーの有無、本文の形式	検証ではバックオフを実装します
再試行戦略	推奨される方法	検証では失敗したリクエストを再試行します

既存エンティティの扱い

既存エンティティ（依存関係分析で PRE-EXISTING と識別されたもの）はシステムによって管理されており、API から作成または削除することはできません。テストでは作成する代わりに、有効な値を検出します。

既存エンティティごとに記録するのは、次の項目のみです。

検出エンドポイントのレスポンススキーマ — List/Get エンドポイントから返されるフィールド
抽出するフィールド — 後続の利用者が必要とするフィールド（例：id、name）とその型

既存エンティティについては、リクエストスキーマ（Create/Update なし）、フィールドカタログ、エンティティ参照、ページネーション、副作用は省略してください。

エンティティごとの詳細調査

各セカンダリエンティティとプライマリエンティティについて、以下の 6 つのカテゴリを調査して記録してください。認証方式とレート制限は API レベルの情報なので、エンティティごとに繰り返す必要はありません。

カテゴリ 1：リクエストスキーマ

リクエスト本文を受け付ける各操作（通常は Create と Update）について、正確なリクエスト構造を記録してください。

項目	記録する内容
操作	Create、Update、またはリクエスト本文を受け付けるその他の操作
Content-Type	`application/json`、`application/x-www-form-urlencoded` など
最小リクエスト本文	有効なリクエストの最小構成（必須フィールドのみ）
完全なリクエスト本文	任意項目を含むすべてのフィールド

各操作を次の形式で記述します。

**Create — POST `/path`**
Content-Type: application/json

Minimal request body (required fields only):
{json}

Full request body (all fields):
{json}

操作が本文を受け付けない場合（例：DELETE）、このセクションでは省略してください。

カテゴリ 2：レスポンススキーマ

各操作について、ステータスコードを含むレスポンス構造を記録してください。

項目	記録する内容
操作	Create、Read、List、Delete など
成功時のステータスコード	200、201、204 など
レスポンス本文	正確な JSON 構造（204 の場合は「レスポンス本文なし」）
識別子の場所	レスポンス内でエンティティ ID が示される場所

各操作を次の形式で記述します。

**Read — GET `/path/{id}` → 200**
{json}

**Create — POST `/path` → 201**
{json}

**Delete — DELETE `/path/{id}` → 204**
No response body.

List 操作では、レスポンスのエンベロープ（ページネーションフィールドを含むラッパー構造）と、コレクション内の項目を 1 つ示してください。

カテゴリ 3：フィールドカタログ

すべての操作における全フィールドをまとめた表です。フィールドの詳細情報の唯一の参照元として使用します。

列	記録する内容
Field	JSON パス（例：`fields.project.id`）
Type	string、number、boolean、array、object、または enum
Required for	このフィールドが必須となる操作（Create、Update、両方、または —）
Constraints	最大長、形式パターン、許容される enum 値
Default	フィールドが省略された場合のデフォルト値、または —

次の形式で表を作成します。

| Field | Type | Required for | Constraints | Default |
|---|---|---|---|---|
| `name` | string | Create | max 255 chars | — |
| `status` | enum | — | `active`, `inactive` | `active` |

enum フィールドについては、有効な値をすべて列挙してください。enum の値が 10 を超える場合は、代表的な値を列挙し、「完全なリストは API ドキュメントを参照」と記載してください。

カテゴリ 4：エンティティ参照

このエンティティが他のエンティティをどのように参照するかを記録してください。これにより、ステップ 6 の依存関係分析がフィールドレベルの詳細で補完され、検証ループで依存関係を接続できるようになります。

列	記録する内容
Field	参照を保持するフィールドパス（例：`fields.project.id`）
Referenced Entity	参照先のエンティティ
Reference Format	ID、キー、名前、または複合
Mandatory	Yes / No / Pre-existing

次の形式で表を作成します。

| Field | Referenced Entity | Reference Format | Mandatory |
|---|---|---|---|
| `fields.project.id` | Project | ID (string) | Yes |
| `fields.assignee.accountId` | User | Account ID (string) | No |

カテゴリ 5：ページネーション

List／Search エンドポイントがページネーションをどのように処理するかを記述します。エンティティに List エンドポイントがない場合は、「List エンドポイントなし — ページネーションは該当しません」と記述します。

ページネーションの検出順序（重要）：

必ず最初にカーソルベースのページネーションを確認します — 次の項目を探してください：continuation、continuation_token、next_cursor、cursor、after、before、next_page_token、offset（数値ではなくトークン／文字列の場合）。
オフセットとカーソルを区別します：オフセットでは数値（0、10、20 など）を使用します。offset という名前のパラメーターに "eyJ0eXAi..." のようなトークン／文字列が含まれている場合、オフセットではなくカーソルベースです。
一部の API では、レスポンスにカーソルトークンとページメタデータ（page_count、page_number）の両方が含まれますが、実際のページネーション方式はカーソルベースです。継続／カーソルトークンがある場合は、必ずカーソルベースを使用してください。
ドキュメントに「page」パラメーターが明示されており、カーソルを示すものがない場合に限り、ページベースのページネーションを使用します。
各エンドポイントのページネーション種別は必ず 1 つです。種別を混在させないでください。
公式な方式を見つけるには、"{apiName} pagination" をドキュメント内で検索してください。

各 List エンドポイントについて、次の厳密な構造の形式で記述します。

**List — GET `/path`**
- **Pagination type:** offset | cursor | page | timestamp | none
- **Items field:** {dot-notation path to items array, e.g., "data", "results", "values"}

該当する種別のフィールドのみを含めます。

カーソルの場合：

- **Cursor param:** {query parameter name, e.g., "cursor", "after", "nextToken"}
- **Reference type:** marker | uri
- **Reference expression:** {dot-notation path to next cursor value, e.g., "pagination.nextCursor"}

レスポンスにカーソル値（トークン／文字列）が含まれる場合は、marker を使用します。
レスポンスに次のページの完全な URL が含まれる場合は、uri を使用します。
参照タイプには、marker または uri 以外の値を絶対に使用しないでください。

オフセットの場合：

- **Offset param:** {query parameter name, e.g., "startAt", "offset"} — must be NUMERIC
- **Initial offset value:** {number, typically 0}

ページの場合：

- **Page number param:** {query parameter name, e.g., "page", "pageNumber"}
- **Initial page number:** {number, typically 0 or 1}

タイムスタンプの場合：

- **Timestamp param:** {query parameter name, e.g., "since", "after"}

カテゴリ 6：副作用と動作

後続のエージェントによる操作の構築、実行、検証に影響する動作を記述します。各項目には、該当する動作を記述するか、該当しない場合は「none」と記述します。

- **Delete behavior:** hard delete / soft delete / archive / deactivate / no delete endpoint
- **Cascade on delete:** deleting this entity also deletes {children} / no cascade
- **Immutable fields:** {field list} cannot be changed after creation / none
- **Async operations:** {operation} returns 202, poll {url} for completion / none
- **Conditional requirements:** {field} required only when {condition} / none
- **Non-standard patterns:** {any API-specific quirks, e.g., status changes via transitions}

詳細調査の作成

Write ツールを使用して、詳細調査を {PROJECT_FOLDER}/api-reference.md に保存します。各エンティティの調査が終わったら、調査内容を蓄積せず、すぐにそのセクションを書き込んでください。

ファイルは次の構成にします。

# {Service} API Reference — Deep Research

## API-Level Notes
{auth scheme + rate limits}

## Pre-Existing Entities
### {Entity} [PRE-EXISTING]
{discovery schema only}

## Secondary Entities
### {Entity} [SECONDARY]
{6 categories}

## Primary Entities
### {Entity} [PRIMARY]
{6 categories}

調査計画のすべてのエンティティについて、該当するすべてのカテゴリを含むドキュメントが完成するまで、先に進まないでください。

ステップ 10：api-reference.md の統合

アクションプラン（ステップ 8）と詳細調査（ステップ 9）を、自己完結型の単一の api-reference.md に統合します。このステップ以降、後続の利用者（ステップ 11 の OpenAPI ジェネレーター、ステップ 12～13 の検証ループ、build-mule-integration スキルの呼び出し側）はこのファイル 1 つだけを参照すればよくなり、action-plan.md を読む必要はありません。

入力

ステップ 8 の {PROJECT_FOLDER}/action-plan.md
ステップ 9 の {PROJECT_FOLDER}/api-reference.md（詳細調査ファイル）

手順

action-plan.md を読み込み、以下を抽出します。
- ユースケースのエンドポイント表（§1 For Spec Generation より）
- CRUD エンドポイントの完全なカタログ（§2 For Live Validation より）
- Mermaid の依存関係グラフ（§2 より）
- 作成順序と削除順序（§2 より）
- 既存の依存関係の表（§2 より）
- 決定ログの表（§2 より）
- 認証方式の詳細（§3 For Credential Collection より）
- ドキュメントのソース URL（ヘッダーより）
api-reference.md（ステップ 9 の詳細調査）を読み込み、以下を確認します。
- API レベルの注記の内容（認証方式とレート制限）。これらは最上位の「認証」および「レート制限」セクションになります。
- すべてのエンティティセクション（既存、二次、主要）と、それぞれの全カテゴリの詳細
以下の厳密なテンプレートに従って、最終版の api-reference.md を作成します。Write ツールを使用して、ステップ 9 のファイルを統合後の内容で上書きしてください。

出力テンプレート

最終版の api-reference.md は、次の構成に厳密に従って作成します。

# {Service} API Reference

## Overview
- **Service:** {apiName}
- **API Version:** {version from documentation, e.g., "v3", "v1", "2023-08-01"}
- **Base URL:** {base URL from API-Level Notes}
- **Documentation:** {primary documentation URL from action plan header}

## Authentication
- **Type:** {Bearer / Basic / API Key / OAuth}
- **Header format:** {exact header pattern, e.g., `Authorization: Basic base64({email}:{api_token})`}
- **Required credentials:** {credential key names, e.g., `BASIC_USERNAME`, `BASIC_PASSWORD`}
{include any additional auth details from the deep research — alternative auth methods, transport requirements, test mode info}

## Rate Limits & Constraints
{Rate Limits content from Step 9 API-Level Notes — copy the full detail including global limits, burst limits, 429 behavior, retry strategy, endpoint-specific limits}

## Use Cases

{endpoint table from action plan §1, copied exactly:}

| Use Case Action | Method | Path | Path Parameters | Has Body | Content Type |
|---|---|---|---|---|---|
| ... | ... | ... | ... | ... | ... |

{include any deviation notes from the action plan}

## Entity Dependency Graph

{Mermaid diagram from action plan §2, copied exactly}

- **Creation order:** {bottom-up arrow notation from action plan}
- **Deletion order:** {top-down arrow notation from action plan}

**Pre-existing dependencies (discover, don't create):**

{pre-existing dependencies table from action plan §2, or "None — all mandatory dependencies can be created and deleted via the API." if no pre-existing deps}

**Decision log:**

{decision log table from action plan §2, copied exactly}

## Full CRUD Endpoint Catalog

{CRUD catalog table from action plan §2, copied exactly:}

| Entity | Operation | Method | Path | Lifecycle Purpose | Source |
|---|---|---|---|---|---|
| ... | ... | ... | ... | ... | ... |

## Entity Reference

### Pre-Existing Entities
#### {Entity} [PRE-EXISTING]
{discovery schema only — copied from Step 9}

### Secondary Entities
#### {Entity} [SECONDARY]
{all 6 categories — copied from Step 9}

### Primary Entities
#### {Entity} [PRIMARY]
{all 6 categories — copied from Step 9}

見出しレベルの調整

ステップ 9 では、エンティティのセクションを次の見出しレベルで記述します。

## Pre-Existing Entities、## Secondary Entities、## Primary Entities
### {Entity} [TYPE]
#### Category N: {name}

最終出力では、これらは ## Entity Reference の下に配置されるため、それぞれ 1 レベル下げます。

### Pre-Existing Entities、### Secondary Entities、### Primary Entities
#### {Entity} [TYPE]
##### Category N: {name}

Entity Reference に含めないもの

## API-Level Notes（認証方式 + レート制限）は Entity Reference セクションに含めないでください。この内容はトップレベルの Authentication セクションと Rate Limits セクションに移されています。Entity Reference セクションは ### Pre-Existing Entities（既存エンティティがない場合は ### Secondary Entities）から直接開始します。

検証チェックリスト

このステップを完了する前に、最終的な api-reference.md に次の項目が含まれていることを確認してください。

すべてのチェック項目に合格するまで先に進まないでください。

Step 11: OpenAPI 3.0 仕様の生成

ステップ 10 で統合した api-reference.md を読み、{PROJECT_FOLDER}/<apiName>.yaml に完全な OpenAPI 3.0 仕様を作成してください。この仕様には、api-reference に記載されているすべての操作、スキーマ、パラメーター、認証要件を正確に反映し、それ以外を含めてはなりません。

要件

OpenAPI バージョンは 3.0.x とします。
info セクションを完全に記述します。title は「API」で終わること、version はセマンティックバージョニング形式（例：1.0.0）であること、description は 1 文の命令形であること。
ベース URL を含む servers セクションを記述します（API がバージョンプレフィックスを使用する場合は、それも含めます）。
paths セクションには、api-reference.md の Use Cases テーブルに記載されたエンドポイントだけを含めます。調査で判明していないエンドポイントを追加してはいけません。
components セクションには、§Authentication の認証方式、リクエスト／レスポンスボディ用の再利用可能なスキーマ、共通パラメーター、エラーレスポンスを含めます。
各エンドポイントについて、完全なパラメーター定義（パス、クエリ、ヘッダー、ボディ）、データ型を含む完全なレスポンススキーマ、エラーレスポンス（4xx、5xx）、認証要件を記述します。
API に明らかに軽量な「ping」エンドポイント（例：GET /me、GET /health）がある場合は、接続テスト用エンドポイントを 1 つ追加します。この追加操作により、ステップ 12 の前提条件で、完全なループを実行する前に認証情報を検証できます。そのようなエンドポイントがない場合は、作成しないでください。その場合、ステップ 12 では paths 内の最初の GET を使用します。

重要：パスとバージョニングのルール

API バージョン（例：/v3）は、エンドポイントパスではなく、servers[].url に必ず含めてください。
エンドポイントパスから API バージョンプレフィックスをすべて取り除いてください。
エンドポイントパスの末尾にスラッシュを付けてはいけません。

正しい例：

servers:
  - url: https://api.example.com/v3
paths:
  /users:
    get: ...
  /users/{id}:
    get: ...

誤った例：

servers:
  - url: https://api.example.com
paths:
  /v3/users:
    get: ...
  /users/{id}/:
    get: ...

その他のルール

すべての操作には、camelCase 形式の一意な operationId を指定します（例：listCourses、getCourseById）。
すべての操作には、説明文を指定します（命令形で、1 文にします）。
すべての操作には、リクエスト例を少なくとも 1 つ、レスポンス例を少なくとも 1 つ指定します。
すべてのスキーマのすべてのプロパティに説明文を指定します。
値が制約された文字列には enum を使用します（制約のない文字列は使用しません）。
該当するすべてのオブジェクトスキーマで、required フィールドを明示します。
パスパラメーターとクエリパラメーターには、説明と型を指定します。

Write ツールを使用してファイルを書き込みます。仕様をユーザーに表示せず、直ちにステップ 12 に進んでください。

ステップ 12：ライブ検証 — 前提条件

操作ごとの検証ループに入る前に、4 つの前提条件を順番に確認してください。いずれかが失敗した場合は、具体的な問題を報告して停止してください。失敗しない限り、各確認について説明する必要はありません。

1. OpenAPI 仕様ファイル

{PROJECT_FOLDER}/<apiName>.yaml を読み込みます。
有効な YAML であることを確認します。
openapi キーがあり、その値が 3. で始まることを確認します（OpenAPI 3.x）。
paths に少なくとも 1 つの操作が含まれていることを確認します。
操作の総数を数えます。これは進捗行（N/M）の分母 M です。

2. `api-reference.md`

{PROJECT_FOLDER}/api-reference.md を読み込みます。
次のセクションが含まれていることを確認します：認証、エンティティ依存関係グラフ、完全な CRUD エンドポイントカタログ、エンティティリファレンス。
認証セクションを読み込み、次の情報を抽出します。
- 認証タイプ（例：Bearer トークン、Basic、API キー）
- ヘッダー形式（例：Authorization: Bearer <TOKEN>）
- 必須の認証情報キー名（例：CODA_API_TOKEN）
- API キー認証の場合：注入場所 — ヘッダー名（例：X-API-Key）またはクエリパラメーター名（例：key、token）

3. `config.properties`

{PROJECT_FOLDER}/config.properties が存在するか確認します。

ファイルが存在しない場合 — 作成します：

手順 2 で抽出した認証情報キー名（例：CODA_API_TOKEN、または TRELLO_API_KEY と TRELLO_API_TOKEN）を使用します。
各キーのプレースホルダー値を生成します。キー名を小文字にし、アンダースコアをハイフンに置き換え、先頭に your-、末尾に -here を付けます（例：CODA_API_TOKEN → your-coda-api-token-here）。

{PROJECT_FOLDER}/config.properties を作成し、認証情報ごとに KEY=placeholder の行を 1 行記述します。

printf '%s\n' 'CODA_API_TOKEN=your-coda-api-token-here' > {PROJECT_FOLDER}/config.properties

キーが複数ある場合は、1 つのコマンドですべての行を記述します。

printf '%s\n' 'TRELLO_API_KEY=your-trello-api-key-here' 'TRELLO_API_TOKEN=your-trello-api-token-here' > {PROJECT_FOLDER}/config.properties

ユーザーに報告し、応答を待ちます。

Created config.properties with placeholder credentials:

  CODA_API_TOKEN=your-coda-api-token-here

Please replace the placeholder value(s) with real credentials and let me know when ready.

▸ 待機 — ユーザーが認証情報を設定したと確認するまで、先に進まないでください。

ユーザーが確認したら、以下のキーの確認に進みます。

キーの確認（ファイル作成後にユーザーが確認した場合、またはファイルがすでに存在する場合に実行）：

手順 2 で特定した各認証情報キーについて、そのキーが存在することを確認します。
```
grep -c '^CREDENTIAL_KEY=' {PROJECT_FOLDER}/config.properties
```
結果は 1 でなければなりません。値を読み取ったり表示したりしてはいけません。

4. ベース URL

api-reference.md の概要セクションを読み込み、Base URL の値（例：https://coda.io/apis/v1）を抽出します。
https:// または http:// で始まることを確認します。

前提条件の確認

4 つすべてを黙って確認します。すべて合格した場合は、各確認について説明せずにステップ 13 に進みます。いずれかが失敗した場合は、具体的な問題をユーザーに報告して停止します。

▸ 停止 — 4 つすべての前提条件が満たされるまで、ステップ 13 に進まないでください。

ステップ 13：ライブ検証 — ループ

前提条件を満たしたら、個別の操作を処理する前に反復ループを設定します。

操作の列挙

OpenAPI 仕様の paths オブジェクトをドキュメントの順序どおりに確認します。各パスについて、そのパスに定義された各 HTTP メソッド（GET、POST、PUT、PATCH、DELETE）を 1 つの操作として (method, path) を記録します。すべての操作を順序付きリストにします。総数 = M。

エンティティ ID を事前に収集する

ループに入る前に、列挙されたリスト内のすべての操作をスキャンし、パスパラメーターを確認します。各パスパラメーター名について、次の手順を実行します。

api-reference.md の Entity Reference セクションと照合し、そのパラメーターがどのエンティティを指すかを特定します。
(parameter_name, entity_type, description) の重複を除いたセットを作成します。

セットが空でない場合、すべての値をまとめてユーザーに 一度だけ 尋ねます。

The operations in this spec require the following entity IDs:

- `docId` (string) — references a Doc entity. Used by 8 operations. Please provide an existing Doc ID.
- `pageIdOrName` (string) — references a Page entity. Used by 4 operations. Please provide an existing Page ID or name.

入力された値は、ループ中に再利用できるよう保存します。パスパラメーターを持つ操作がない場合は、この手順を省略します。

ループカウンター

初期化します：completed = 0、passed = 0、fixed = 0、failed = 0、skipped = 0、auth_halted = false、any_2xx_seen = false。

列挙されたリスト内の各操作について、順番に、操作ごとの再試行状態をリセットします。

attempt_count = 0 — この操作に対して curl リクエストを実行するたびにインクリメントします。
retry_history = [] — 各試行後に { attempt_number, status_code, error_summary, fix_applied_if_any } を追加します。
last_failure_signature = null — 直近の失敗試行の (status_code, error_message_key) ペアです。

次に、各操作について以下を実行します。

現在の操作を (method, path) に設定します。
操作の分析 — ステップ 13.1。
リクエストの実行とレスポンスの検証 — ステップ 13.2。
auth_halted が true の場合は、直ちにループを終了します。ステップ 5～9 には進まず、ステップ 14 に進みます。
completed をインクリメントします。
結果（passed、fixed、failed、skipped）を分類し、該当するカウンターを更新します。
進捗行を出力します：Validation: {completed}/{M} | passed {X} | fixed {Y} | failed {Z} — skipped > 0 の場合に限り、末尾に | skipped {S} を追加します。
操作が失敗した場合は、詳細行を出力します： ✗ {METHOD} {path} {status_code} — {reason}。
次の操作に進みます。

すべての操作の処理後（または認証エラーによってループが中断された後）、ステップ 14（最終レポート）に進みます。

▸ STOP — 必要なエンティティ ID がある場合は、すべて収集するまでループに入らないでください。

ステップ 13.1 — 操作の分析

ループから現在の操作を読み取り、HTTP リクエストの構築に必要な情報をすべて抽出します。

13.1.1 — 現在の操作を特定します。 操作の (method, path) は、列挙時にすでに決定されています。

13.1.2 — 操作定義を抽出します。 仕様から、以下を抽出します。

HTTP メソッド（GET、POST、PUT、DELETE、PATCH）。
パステンプレート（例：/docs/{docId}/pages/{pageIdOrName}）。
パスパラメーター — 各パラメーターの名前、型、必須かどうか（はい／いいえ）。
クエリパラメーター — 各パラメーターの名前、型、必須かどうか、デフォルト値。
リクエストボディのスキーマ — メソッドに requestBody の定義がある場合（通常は POST、PUT、PATCH）。必須フィールドとその型を抽出します。
成功時に期待されるレスポンス — 仕様の responses セクションで宣言されている 2XX ステータスコード（例：200、201、202）。2XX コードが複数ある場合は、すべて記録します。
レスポンスボディのスキーマ — responses.{status}.content.application/json.schema にあるスキーマ。スキーマが $ref を使用している場合は、仕様内の components/schemas/{name} を参照して解決します。レスポンスボディが定義されていない場合（例：204）は、「ボディなし」と記録します。
セキュリティ要件 — 操作で使用されるセキュリティスキーム（操作レベルまたは仕様レベルの security フィールドから確認）。

13.1.3 — エンティティ ID を代入します。 現在の操作の各パスパラメーターについて、保存した値をパステンプレートに代入します。列挙時に収集されていないパスパラメーター（想定外のパラメーター）がある場合は、ここでユーザーに尋ねます。操作にパスパラメーターがない場合は、このサブステップを省略します。

13.1.4 — 準備状況を確認します。 次に進む前に、操作定義がすべて抽出され、必要なエンティティ ID がすべて提供されていることを内部で確認します。

ステップ 13.2 — リクエストの実行とレスポンスの検証

HTTP リクエストを構築し、稼働中の SaaS に対して実行して、レスポンスを検証します。

13.2.1 — curl コマンドを構築する

操作の定義に基づいて curl コマンドを作成します。

URL。 ベース URL とパステンプレートを結合し、パスパラメーターをユーザー指定の値に置き換えます。例：https://coda.io/apis/v1/docs/AbCDeFGH/pages/canvas-abc123。

メソッド。 -X フラグを使用します（例：-X GET、-X POST）。

認証ヘッダー。 api-reference.md に記載された認証タイプに基づいて作成します。シェル置換を使用して、config.properties から認証情報を挿入します。

Bearer トークン：

-H "Authorization: Bearer $(grep '^CODA_API_TOKEN=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

Basic 認証：

-H "Authorization: Basic $(echo -n "$(grep '^API_USER=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-):$(grep '^API_PASS=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)" | base64)"

API キー（ヘッダー）：

-H "{header_name}: $(grep '^API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

API キー（クエリパラメーター）： 認証情報を URL のクエリパラメーターとして追加します。最初のパラメーターには ?、それ以降には & を使用します。
```
"https://api.example.com/endpoint?{param_name}=$(grep '^API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"
```
複数のクエリパラメーター認証情報を必要とする API の場合（例：key と token の各パラメーター）：
```
"https://api.example.com/endpoint?key=$(grep '^TRELLO_API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)&token=$(grep '^TRELLO_API_TOKEN=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"
```
URL にすでにクエリパラメーターがある場合（13.1.2 の必須クエリパラメーターなど）は、& で追加します。

Content-Type ヘッダー。 -H "Content-Type: application/json"（すべてのリクエストに含めます）。

リクエストボディ。 操作でボディが必要な場合（POST、PUT、PATCH）、仕様のリクエストボディスキーマから必須フィールドのみを使用して、最小限の JSON ペイロードを作成します。フィールドの型と制約に合った現実的なプレースホルダー値を使用します。-d '{...}' で渡します。

レスポンスの取得。 -s -w "\n%{http_code}" -D /tmp/validation_headers.txt を追加して進捗出力を抑制し、最終行に HTTP ステータスコードを出力し、必要に応じて検査できるようレスポンスヘッダーを一時ファイルに書き出します（例：429 レスポンスの Retry-After）。

13.2.2 — 破壊的操作の確認

curl コマンドを実行する前に、現在の操作が破壊的かどうかを確認します。

DELETE（任意のエンティティ）— 常に破壊的です。
エンティティ全体を置き換える PUT — 破壊的です（既存の状態を上書きします）。

PATCH 操作は破壊的とは見なされません。部分的な更新を適用するため、一般に安全です。POST（作成）操作も破壊的ではありません。既存のエンティティを変更するのではなく、新しいエンティティを作成します。

操作が破壊的な場合：

実行前にユーザーに警告します。

⚠️  Destructive operation: {METHOD} {path}
This will {consequence} the {entity_type} with ID `{entity_id}`.
This action may not be reversible.

Proceed? (yes / skip)

{consequence} は次のとおりです。

DELETE → "permanently delete"
PUT → "overwrite all fields of"

ユーザーが「yes」と答えた場合（または同等の肯定）→ 13.2.3 に進み、リクエストを実行します。
ユーザーが「skip」と答えた場合（または同等の否定）→ リクエストを実行しないでください。操作をスキップ済みとして分類します。skipped カウンターを増やします。スキップの詳細を含む進捗行を出力します。
```
  ⏭ {METHOD} {path}  skipped — user declined destructive operation
```
13.2.7 に直接進みます。これを失敗として数えないでください。

操作が破壊的でない場合は、プロンプトを表示せずに 13.2.3 に進みます。

13.2.3 — リクエストを実行する

Bash ツールを介して curl コマンドを実行します。シェル置換によって認証情報がインラインで解決されるため、実際の値が会話コンテキストに表示されることはありません。

現在の操作の attempt_count を増やします。レスポンスを解析した後（13.2.4）、2XX 以外の場合は、retry_history にエントリー（attempt_number、status_code、error_summary、fix_applied_if_any）を追加し、last_failure_signature を (status_code, レスポンスボディ内の主要なエラー詳細) で更新します。

13.2.4 — レスポンスを解析する

curl の出力から、次の情報を取得します。

ステータスコード： 出力の最終行（-w "\n%{http_code}" によるもの）。
レスポンスボディ： 最終行を除くすべての行。空の場合、レスポンスにボディはありません。
レスポンスヘッダー： エラーハンドラーで必要な場合は /tmp/validation_headers.txt から取得できます（例：429 レスポンスの Retry-After）。

ステータスコードが 2XX の範囲（200～299）にあることを確認します。ステータスコードが 2XX の場合は、any_2xx_seen = true を設定します。これは、このセッション中に認証情報が少なくとも一度は機能したことを追跡するものです。ステータスコードが 2XX 以外の場合は、結果を記録する前に13.2.5（エラーレスポンススキーマの確認）に進みます。

13.2.5 — エラーレスポンススキーマの確認（非2XXのみ）

エラーを分類する前に、エラーレスポンスボディが仕様で定義されたエラースキーマに一致するか確認します。

実際のステータスコードに対応するエラーレスポンススキーマを仕様から確認します：responses.{status_code}.content.application/json.schema。このステータスコードに対するスキーマが定義されていない場合は、defaultレスポンススキーマも確認します。
仕様にエラースキーマが存在しない場合 → スキーマの確認をスキップします。
エラースキーマが存在し、レスポンスにボディがある場合 → 13.2.7 分岐 A（手順1～6）と同じ比較ロジックを使って、エラーボディをスキーマと比較します。
不一致が見つかった場合 → 13.2.7と同じ自動修正方針を適用して、仕様内のエラースキーマを修正します。更新した仕様をディスクに書き込み、修正内容をログに記録します。
エラースキーマの再検証は不要です。エラー自体は引き続き有効です。エージェントは、エラーレスポンス形式について仕様に記述された内容のみを修正します。

エラースキーマの確認後、13.2.6に進み、エラーを分類して処理します。

13.2.6 — エラー原因の処理（非2XXのみ）

ステータスコードに基づいて適切なアクションを決定します。

401/403 — 認証／権限エラー。 認証情報が無効または期限切れであるか、必要な権限がありません。エージェントは自律的に認証情報を修正できません。これは、検証ループ全体を停止させるブロッキング例外です。

失敗の状況を分類します：
- any_2xx_seen == falseの場合 → 恒常的な認証失敗（認証情報が誤っているか、権限が不足しています）。
- any_2xx_seen == trueの場合 → セッション途中のトークン期限切れ（認証情報は以前は機能していましたが、現在は期限切れです）。
認証失敗を記録します：
- auth_halted = trueに設定します。
- 現在の操作(method, path)とステータスコード（401または403）を記録します。
- 失敗の状況（恒常的またはセッション途中）を記録します。
停止を示す進捗行を出力します：
```
Validation: {completed}/{M} | passed {X} | fixed {Y} | failed {Z} | AUTH HALTED
  ⛔ {METHOD} {path}  {status_code} — {reason from response body}
```
認証による停止を通常の失敗と視覚的に区別するため、✗ではなく⛔を使用します。
completedまたはfailedをインクリメントしてはいけません。操作は完全には処理されていません。
13.2.7または13.2.8に進んではいけません。
検証ループに戻ります。検証ループはauth_haltedを確認し、ステップ14に進みます。

5XX（500～599）— サーバーエラー。 SaaSサービスが利用できないか、サーバー側で問題が発生しています。仕様やリクエストの問題ではなく、エージェントには修正できません。

理由を「server error ({status_code})」（例：「server error (503)」）として失敗に分類します。
操作を再試行してはいけません。
13.2.7をスキップし、直接13.2.8に進んで結果を記録します。

404 — 見つかりません（エンティティIDの修正）。 エンドポイントには既存のエンティティへの参照が必要ですが、エンティティが見つかりませんでした。通常これは、事前収集時に指定されたエンティティIDが誤っているか、古くなっているか、削除済みのエンティティを参照していることを意味します。

疑わしいパスパラメーターを特定します：
- 現在の操作のパステンプレートからすべてのパスパラメーターを抽出します。
- 各パスパラメーターについて、現在置き換えられている値（保存済みのエンティティIDマップから取得）を記録します。
- パスに複数のパラメーターがある場合は、レスポンスボディを使って、見つからなかったエンティティを推定します。レスポンスボディから誤っているパラメーターを特定できない場合は、最も具体的な（階層が最も深い）パラメーターを最初に疑います。

修正したエンティティIDをユーザーに尋ねます：

1つのパラメーターが明らかに疑わしい場合：

404 Not Found — {METHOD} {path}

The API returned 404, which means the entity referenced by `{suspect_param}`
(current value: `{current_value}`) was not found.

Please provide a valid {entity_type} ID for `{suspect_param}`:

複数のパスパラメーターに誤りがある可能性がある場合：

404 Not Found — {METHOD} {path}

The API returned 404. The following entity IDs may be incorrect:
- `{param1}` (current value: `{value1}`) — {entity_type_1}
- `{param2}` (current value: `{value2}`) — {entity_type_2}

Please provide corrected values (or confirm if a value is correct):

保存済みのエンティティ ID を更新する： ユーザーから修正値が提供された後、保存済みのエンティティ ID マップを更新し、同じパラメーター名を使用する以降のすべての操作で、修正値が使用されるようにします。
再構築して再試行する：
- 修正後のエンティティ ID を使用して、13.2.1 の curl コマンドを再構築します。
- 操作が破壊的（DELETE または PUT）の場合は、実行前に13.2.2 の破壊的操作の確認を再度行います。
- 再構築した curl コマンドを実行し（13.2.3）、レスポンスを解析します（13.2.4）。
再試行の結果を評価する：
- 2XX レスポンス → 修正後の ID が機能しました。通常どおり、スキーマ検証のために 13.2.7 に進みます。
- 再び 404（同じエラー） → 理由を「404 — エンティティが見つかりません（ユーザー提供の ID でも見つかりません）」として失敗に分類します。ユーザーに再度尋ねないでください。13.2.8 に進みます。
- 異なる 2XX 以外のエラー → 初回のレスポンスと同様に、新しいエラーを13.2.5 と 13.2.6 に渡します。
再試行の上限： 404 ごとに、ユーザーとの対話を伴う再試行は 1 回までです。再試行で 404 が返された場合は、直ちに失敗とします。

400 — Bad Request（3 段階の修正）。 構文の不備、必須フィールドの欠落、または無効な値が原因で、API がリクエストを拒否しました。エージェントは、段階的に進む 3 つのレベルを通じて、自律的に問題の修正を試みます。ユーザーとのやり取りはなく、すべて自律的に処理されます。このハンドラー内のすべての再試行には、以下の再試行戦略が適用されます。13.2.3 を再実行する前に、attempt_count < 10 を確認し、進捗ゲートを実行してください。

Tier 1 — エラーメッセージの診断：
- エラーレスポンス本文を解析し、修正に役立つ詳細（例：「フィールド X は必須です」「パラメーター Y の値が無効です」「不明なフィールド Z」）を確認します。
- メッセージから特定のフィールド、制約、または形式の問題が特定できる場合：
  - それに応じてリクエストを修正します（不足しているフィールドを追加する、値を修正する、無効なフィールドを削除する）。
  - curl コマンドを再実行し（13.2.3）、レスポンスを解析します（13.2.4）。
  - 2XX → スキーマ検証のために 13.2.7 に進みます。
  - 引き続き 400 → 進捗ゲートを確認します。進捗がない場合は失敗に分類し、13.2.8 に進みます。進捗がある場合は Tier 2 に進みます。
  - 異なる 2XX 以外 → 新しいエラーコードについて、13.2.5 と 13.2.6 に渡します。400 の段階的処理は続行しません。
- メッセージから修正方法を特定できない場合 → 再試行せず、Tier 2 に直接進みます。
Tier 2 — api-reference.md の参照：
- api-reference.md の関連セクションを読みます。
  - 操作対象のエンティティに関する Entity Reference — 必須フィールド、フィールドの型、列挙値、制約。
  - 現在のエンドポイントに関する CRUD Endpoint Catalog — リクエスト本文の形式、必須パラメーター。
- 現在のリクエストを、文書化された要件と照らし合わせます。
- 相違点を特定し、文書化された形式に合うようリクエストを再構築します。
- curl コマンドを再実行し（13.2.3）、レスポンスを解析します（13.2.4）。
- 2XX → 13.2.7 に進みます。
- 引き続き 400 → 進捗ゲートを確認します。進捗がない場合は失敗に分類し、13.2.8 に進みます。進捗がある場合は Tier 3 に進みます。
- 異なる 2XX 以外 → 新しいエラーコードについて、13.2.5 と 13.2.6 に渡します。
Tier 3 — 公式 API ドキュメントの調査：
- WebSearch および／または WebFetch を使用して、このエンドポイントに関する公式 SaaS API ドキュメントを検索します。
- 必須フィールド、フィールドの形式や制約、有効な値、api-reference.md に記載されていない API 固有の検証ルールを確認します。
- 見つかった修正内容をリクエストに適用します。
- curl コマンドを再実行し（13.2.3）、レスポンスを解析します（13.2.4）。
- 2XX → 13.2.7 に進みます。
- 引き続き 400 → 理由を「400 — {エラーメッセージ}（すべての修正レベルを試行済み）」として失敗に分類します。13.2.8 に進みます。
- 異なる 2XX 以外 → 新しいエラーコードについて、13.2.5 と 13.2.6 に渡します。

429 — Too Many Requests（レート制限）。 API がリクエストをレート制限しています。エージェントは待機してから自律的に再試行します。ユーザーとのやり取りはありません。

Retry-After ヘッダーを確認します：
- /tmp/validation_headers.txt を読み込み、Retry-After ヘッダー（大文字と小文字を区別しません）を探します。
- 整数（例：Retry-After: 5）で指定されている場合 → 待機時間はその秒数です。
- HTTP 日付で指定されている場合 → その時刻までの秒数を計算します。日付が過去の場合は、0 として扱います。
- **上限：**計算した待機時間が 120 秒を超える場合は、120 秒に制限します。
- Retry-After ヘッダーがない場合 → 指数バックオフを使用します（手順 2）。
指数バックオフ（Retry-After ヘッダーがない場合）：
- 1 回目の 429：2 秒待機します。
- 連続 2 回目の 429：4 秒待機します。
- 連続 3 回目の 429：8 秒待機します。
- 以降は倍増させます。ただし、1 回の待機時間は最大 120 秒です。
待機して再試行します：
- Bash で sleep {seconds} を実行し、計算した時間だけ待機します。
- 同じ curl コマンド（13.2.3）を再実行し、レスポンスを解析します（13.2.4）。
再試行結果を評価します：
- 2XX → レート制限が解除されました。スキーマ検証のため、13.2.7 に進みます。
- 再び 429 → まだレート制限中です。手順 1 から繰り返します。
- 異なる非 2XX → 新しいステータスコードについて、13.2.5 および 13.2.6 を実行します。429 の再試行シーケンスは継続しません。
**進捗ゲートの例外：**429 が繰り返される場合は、進捗ゲートをバイパスします。各再試行の前に、attempt_count < 10 であることを確認します。
**上限到達：**絶対上限（10 回）に達してもレスポンスが 429 の場合、理由「429 — レート制限中（{N} 回の試行後に再試行上限に到達）」として failed に分類します。13.2.8 に進みます。
**サイレント動作：**429 の待機中に進捗行を出力してはいけません。操作完了時に最終結果のみを出力します。

**その他すべての非 2XX ステータスコード（例：409 Conflict、422 Unprocessable Entity、405 Method Not Allowed）。**400 と同じ 3 段階の修正を行います。第 1 段階では、エラーコード固有のガイダンスを確認します。

**409 Conflict：**リソース名または ID の競合を探し、競合する値を変更します。
**422 Unprocessable Entity：**フィールド単位の検証エラーを探し、そのフィールドを修正します。
**405 Method Not Allowed：**有効なメソッドを示す Allow レスポンスヘッダーがあるか確認し、HTTP メソッドを修正します。

第 2 段階と第 3 段階は、400 の場合と同じです。

再試行戦略

この統一フレームワークは、13.2 におけるすべての再試行シナリオに適用されます。個別のエラーハンドラー（400、429、その他）とスキーマの自動修正（13.2.7）は、再試行の判断にこのフレームワークを参照します。

失敗シグネチャ。(HTTP ステータスコード, 主なエラー詳細) の組です。主なエラー詳細とは、レスポンスボディに含まれる主要なエラーメッセージまたはエラーコードのことです。タイムスタンプ、リクエスト ID、トレース ID などの動的な内容は無視します。ステータスコードと主なエラー詳細の両方が一致する場合、2 つの失敗は「同じ」です。いずれかが異なる場合は「異なる」とみなします。

**進捗ゲート。**いずれかのハンドラーが 13.2.3 を再実行する前に、現在の失敗シグネチャを last_failure_signature と比較します。

異なる ＝前進しています。上限の範囲内で再試行を許可します。
同じ＝進捗がありません。直ちに再試行を停止し、解決不能として failed に分類して、13.2.8 に進みます。

**429 の例外。**429 のレスポンスが繰り返される場合は、進捗ゲートをバイパスします。429 はレート制限が有効になっている一時的な状態であり、継続的な失敗ではありません。

**絶対上限。**1 回の操作につき、試行回数は最大 合計 10 回 です（初回 1 回＋最大 9 回の再試行）。attempt_count は、同じ操作に対するすべてのハンドラーで共有されます。13.2.3 を再実行する前に、attempt_count < 10 であることを確認します。上限に達した場合は、進捗の有無にかかわらず直ちに停止します。

**上限到達時の処理。**進捗ゲート（同じ失敗）または絶対上限のいずれかによって再試行を停止した場合、操作を解決不能として failed にマークし、以下を含めます。

attempt_count の合計。
「進捗なし」（進捗ゲート）または「再試行上限に到達」（上限）のどちらが停止理由か。
retry_history の全内容。

失敗分類を引き継いで 13.2.8 に進みます。

13.2.7 — レスポンスを検証する

レスポンスにボディがあるかどうかに基づいて分岐します。

分岐 A：ボディがある2XXレスポンス。 実際のレスポンスJSONを仕様のレスポンススキーマと比較します。

レスポンスボディをJSONとして解析します。解析に失敗した場合は「Response is not valid JSON」と報告して終了します。
仕様のスキーマを解決します。 一致したステータスコードのレスポンススキーマを仕様から読み取ります。$ref を使用している場合は、参照先の components/schemas/{name} をたどって展開します。ネストされた $ref 参照もすべて解決します。
フィールドを比較します。 レスポンス内の各フィールドについて、次の操作を行います。
- そのフィールドが仕様スキーマの properties に定義されているか確認します。
- 定義されている場合、JSONの型がスキーマの型と一致するか確認します。
  - string ↔ 文字列
  - integer または number ↔ 数値
  - boolean ↔ 真偽値
  - array ↔ 配列
  - object ↔ オブジェクト
- スキーマにフィールドがない場合は、余分なフィールドとして記録します。
必須フィールドを確認します。 スキーマの required 配列にある各フィールドがレスポンスに存在するか確認します。存在しない場合は、必須フィールドの欠落として記録します。
ネストされたオブジェクトを確認します（1階層）。 スキーマに properties の定義がある object 型のフィールドについて、ネストされたオブジェクトに対して手順3～4を繰り返します。
配列を確認します。 array 型のフィールドについて、レスポンス値が配列であることを確認します。スキーマに items の定義がある場合は、配列が空でなければ、配列の最初の要素を items スキーマと比較します。
結果を判定します。
- 不一致が見つからない場合 → 合格と分類します。13.2.8に進みます。
- 不一致が見つかった場合 → 以下の自動修正方法を適用してから、再検証します。

自動修正方法（分岐 Aのみ）：

不一致の種類	修正方法
型の不一致 — 仕様が宣言する型とレスポンスが返す型が異なる	仕様スキーマ内のプロパティの `type` を、レスポンスの実際の型に合わせて更新します。
余分なフィールド — レスポンスに存在するが、仕様スキーマにはないフィールド	スキーマの `properties` に任意項目としてフィールドを追加します（`required` には追加しないでください）。レスポンス値から型を推測します。
必須フィールドの欠落 — 仕様の `required` に列挙されているフィールドがレスポンスにない	スキーマの `required` 配列からフィールドを削除します。フィールドは `properties` に残します。
構造の不一致 — ネストされたオブジェクトまたは配列の構造が仕様と異なる	仕様スキーマを実際の構造に合わせて更新します。

現在の不一致すべてに対する修正を1回で適用します。同じスキーマを $ref で参照するすべての操作に修正が反映されるよう、インラインのレスポンススキーマではなく components/schemas/{name} の定義を変更します。Editツールを使用して、更新した仕様をディスクに書き込みます。適用した修正をそれぞれ次の形式で記録します：{schema_name}.{field_path}: {mismatch_type} — {description of change}。

自動修正後の再検証：

13.2.3と同じcurlコマンドを再実行します（必ず新しいレスポンスを使用します）。
13.2.4のロジックを使用してレスポンスを解析します。
レスポンスが引き続き2XXの場合、更新後の仕様スキーマを使用して、分岐 Aの手順1～6のスキーマ比較を繰り返します。
次のように評価します。
- 不一致なし → 修正済みと分類します。13.2.8に進みます。
- 不一致は残っているが、前回の試行とは異なる → 進展あり。追加の修正を適用して再検証します。
- 前回と同じ不一致が残っている → 進展なし。「schema mismatch (auto-fix unsuccessful)」を理由として失敗と分類します。13.2.8に進みます。
- 再検証で2XX以外のレスポンスが返された → エラーステータスコードと理由を付けて失敗と分類します。13.2.8に進みます。
スキーマの自動修正の再試行では、エラーハンドラーと attempt_count を共有します。合計試行回数は10回を超えないでください。

分岐 B：ボディがない2XXレスポンス。

実際のHTTPステータスコードが仕様の期待ステータスコードと一致することを検証します。
一致する場合 → 合格と分類します。
一致しない場合 → 「status code mismatch」を理由として失敗と分類し、実際のコードと期待値を報告します。

13.2.8 — 結果を記録して進捗を通知する

結果を分類します。

passed — 2XX レスポンスで、スキーマが一致しました（または本文がなく、ステータスが一致しました）。404 エンティティ ID の修正後に成功した操作も含みます。
fixed — 2XX レスポンスで、最初はスキーマが一致しませんでしたが、エージェントが仕様を自動修正し、再検証に成功しました。
failed — すべての修正後も 2XX 以外のレスポンスが返った場合、または 2XX レスポンスでスキーマの自動修正を試みても、再試行後に不一致をすべて解消できなかった場合です。
skipped — 13.2.2 の確認プロンプトの後、ユーザーが破壊的な操作の実行を拒否した場合です。

認証エラー（401/403）はこのステップには進みません。13.2.6 でループが停止し、Step 14 で報告されます。

ユーザーに進捗行を通知します。

Validation: 1/5 | passed 1 | fixed 0 | failed 0
Validation: 2/5 | passed 1 | fixed 0 | failed 1
  ✗ POST /docs/{docId}/pages  400 — missing required field: name (3 attempts)
Validation: 3/5 | passed 2 | fixed 0 | failed 1

ルール：

完了した操作ごとに進捗行を 1 行出力します。
詳細行は、ループ中の failed 操作に限り出力します。attempt_count > 1 の場合は、末尾に ({attempt_count} attempts) を追加します。
failed 操作の retry_history と、fixed 操作の修正概要を記録します。Step 14 で最終レポートに含める場合があります。
Fixed 操作は進捗上、成功として扱います。ループ中に詳細行を出力しません。
エージェントが修正を試みている間は、詳細行を出力しないでください。

結果を記録したら、ループに戻って次の操作を処理します。これが最後の操作だった場合は、Step 14 に進みます。

Step 14: 最終レポートとナレッジの準備完了

このステップは、検証ループですべての操作を処理した後、または認証エラーによってループが途中で停止した後に実行します。

認証エラー — ループが途中で停止

auth_halted が true の場合、通常の要約ではなく、認証エラーのレポートを表示します。

永続的な認証エラー（any_2xx_seen == false）：

Auth failure — validation halted.

  ⛔ {METHOD} {path}  {status_code} — {reason}

The API returned {status_code} on the first operation attempted. The credentials in
config.properties may be invalid or lack permissions for this API.

Please verify the credentials and re-run validation.

セッション途中のトークン有効期限切れ（any_2xx_seen == true）：

Auth failure — validation halted after {completed}/{M} operations.

  ⛔ {METHOD} {path}  {status_code} — {reason}

  Completed before failure: passed {X}, fixed {Y}, failed {Z}

The first {completed} operations were processed, but operation {completed+1} returned {status_code}.
This likely indicates the API token has expired mid-session.

Please refresh the token in config.properties and re-run validation.
The agent will re-validate all operations from the beginning.

認証エラーのレポートを表示した後、停止します。通常の要約を表示したり、「再試行しますか？」と尋ねたりしないでください。

正常終了

要約行の後に、fixed、failed、skipped 操作の詳細行を表示します。passed 操作の詳細行は表示しません。skipped > 0 の場合に限り、| skipped {S} を追加します。

詳細行の順序：fixed 操作（✔）、failed 操作（✗）、skipped 操作（⏭）。

Validation complete: 5/5 | passed 2 | fixed 1 | failed 1 | skipped 1

  ✔ GET /docs/{docId}  fixed — Doc.owner: type mismatch (object → string), Doc.sourceDoc: structural mismatch (string → object)
  ✗ POST /docs/{docId}/pages  400 — missing required field: name (3 attempts)
  ⏭ DELETE /docs/{docId}  skipped — user declined destructive operation

詳細行のルール：

Fixed（✔）： ✔ {METHOD} {path} fixed — {fix_summary}。attempt_count > 1 の場合は、末尾に ({attempt_count} attempts) を追加します。
Failed（✗）： ✗ {METHOD} {path} {status_code} — {reason}。attempt_count > 1 の場合は、末尾に ({attempt_count} attempts) を追加します。
Skipped（⏭）： ⏭ {METHOD} {path} skipped — user declined destructive operation。

failed 操作がある場合（skipped は含めません）、要約を表示し、ユーザーに次の対応を尋ねます。

{N} operation(s) could not be validated. How would you like to proceed?

1. Provide additional information so I can retry the failed operations
2. Keep the failed operations in the spec as-is (no changes to their definitions)
3. Remove the failed operations from the spec and proceed with the corrected spec
4. Cancel — stop the validation process

ユーザーがオプションを選択した場合：

オプション 1： failed 操作ごとの retry_history を提示し、すでに試した内容をユーザーに伝えます。ユーザーから追加情報を受け取り、failed 操作のみを再検証します。再検証後、要約を更新して提示し、failure が残っている場合は選択フローを繰り返します。
オプション 2： 仕様をそのまま引き渡します。検証中に適用した自動修正は、すでにディスクに書き込まれています。
オプション 3： Edit ツールを使用して、仕様の paths オブジェクトから failed 操作を削除します。更新した仕様をディスクに書き込みます。
オプション 4： 停止します。仕様を引き渡さないでください。

オプション 1～3 の場合、仕様が確定した後に出力を確認します。

Knowledge ready: {PROJECT_FOLDER}
  - api-reference.md
  - {apiName}.yaml
  - config.properties

すべての操作が passed、fixed、または skipped の場合（つまり failed == 0 の場合）は、ユーザーに追加の確認を求めず、要約を報告して出力を確認します。

Knowledge ready: {PROJECT_FOLDER}
  - api-reference.md
  - {apiName}.yaml
  - config.properties

呼び出し元（通常は build-mule-integration Step 3a）は、HTTP-Connector の設定と DataWeave 変換に使用する api-reference.md を読み取ります。<apiName>.yaml は修正済みで、検証テスト済みの OpenAPI 仕様です。

Markdown 対応

ログインしてコメント

基本情報

作者: mulesoft
リポジトリ: mulesoft/mulesoft-dx
カテゴリ: 開発
インストール数: 226
GitHub スター: 14

問題を報告