api-design

API 設計

OpenAPI 仕様のライフサイクル全体を支援します。仕様をゼロから設計したり、既存の仕様を3つの観点（AI エージェント対応、セキュリティ対応、API 設計ガイドライン）から評価したり、修正を適用したりできます。

ユーザーのニーズを判断します：

• 設計：ユーザーが構築したい API を説明する → 以下の 設計ワークフロー に進みます
• 評価／修正：ユーザーが既存の仕様を共有する、または参照する → 以下の 評価ワークフロー に進みます
• 設計してから評価：ユーザーが両方を希望する → まず設計を完了してから、評価に進みます

---

設計ワークフロー

WSO2 REST API 設計ガイドラインに基づき、ガイド付きの対話形式のプロセスを通じて、OpenAPI 3.x 仕様をゼロから設計できるよう支援します。出力は、ガイドラインに準拠し、AI エージェントで利用できる、本番環境向けの品質を備えた YAML ファイルです。

references/wso2-rest-api-design-guidelines.md は、WSO2 の設計プロセス、リソースの分類、URI ルール、HTTP セマンティクス、特殊な動作パターンに関する信頼できる情報源です。各ステップで必要なセクションを参照します。

• ステップ3ではリソースの分類
• ステップ4では URI ルールと HTTP セマンティクス
• ステップ6ではエラースキーマ、特殊な動作、セキュリティの配置

進め方：

1. ドメインを理解する
2. データモデルを理解する（エンティティと関係性を対話形式で確認します）
3. リソースを導き出し、ユーザーに確認する
4. 全体の概要を作成する（表現、URI、メソッド、特殊な動作、エラー）
5. ユーザーが満足するまで反復して調整する
6. 最終的な OpenAPI YAML を生成する
7. 評価を提案する

---

ステップ1 — ドメインを理解する

ユーザーが API についてまだ説明していない場合は、簡単な質問を1つします。

「何を構築したいですか？サービスについて1、2文で説明してください。」

ここでは、ドメインの概要をつかむことだけが目的です。リソース、認証、バージョニング、CRUD 以外のアクションについてはまだ質問しません。これらは後続のステップで自然に明らかになります。

---

ステップ2 — データモデルを理解する

リソースや URI を決める前に、システムがどのようなデータを管理するのかを理解します。ユーザーに、平易な言葉で説明してもらいます。

「リソースを設計する前に、システムが何を管理し、それらがどのように関連しているかを理解する必要があります。データについて、平易な言葉で説明してください。たとえば、 『顧客はショッピングカートを所有しています。カートには商品があります。各商品は製品を参照します。』 技術的に説明する必要はありません。主な要素と、それらのつながりを教えてください。」

ユーザーの回答から、以下を推測します。

• 主要なエンティティ（例：顧客、カート、カートアイテム、製品）
• エンティティ間の関係（例：カートは顧客に属する、カートアイテムはカートに属する）
• 示唆されるビジネスアクション（例：「購入手続き」は、CRUD を超える複数段階の操作を示唆します）

短い要約を提示し、確認を求めます。

「次のように理解しました。

• 顧客 — ショッピングカートを所有する
• カート — 顧客に属し、アイテムを含む
• カートアイテム — カートに属し、製品を参照する
• 製品 — 単独で存在するカタログ項目

この内容で合っていますか？不足している点や異なる点はありますか？」

回答に基づいて調整します。エンティティモデルが確定したら、ステップ3に進みます。

---

Step 3 — リソースを導き出して確認する

内部で WSO2 のリソース分類（references/wso2-rest-api-design-guidelines.md）を適用し、 各エンティティとビジネスアクションを適切なリソースタイプと URI に対応付けます。この推論は 内部で行い、分類のカテゴリについてユーザーに説明しないでください。

次に、URI と HTTP メソッドだけを記載した簡潔なリソース表を提示し、確認を求めます。

「データモデルに基づいて、次のリソースを設計します。

GET    /products                              — すべての商品を一覧表示
POST   /products                              — 商品を追加
GET    /products/{productId}                  — 商品を取得
PUT    /products/{productId}                  — 商品を更新
DELETE /products/{productId}                  — 商品を削除

GET    /customers/{customerId}/cart            — 顧客のカートを取得
POST   /customers/{customerId}/cart/items      — カートに商品を追加
DELETE /customers/{customerId}/cart/items/{itemId} — カートから商品を削除

POST   /customers/{customerId}/cart/checkout   — カートをチェックアウト

これでよさそうですか？不足しているもの、名前を変更したいもの、または合わないものはありますか？」

続行する前に、確認または修正を待ちます。ユーザーが変更を求めた場合は、 リソース一覧を更新して改訂版を提示します。リソースに納得してもらってから、ステップ 4 に進みます。

---

Step 4 — アウトラインを作成する

アウトラインを作成する前に、ステップ 1～3 で集めた情報をすべて使って残りの設計判断に妥当な 初期値を推定し、ユーザーに確認します。

「アウトラインを作成する前に、予定している内容をお知らせします。変更したい点があれば教えてください。

• 形式 — JSON のみ。<コンテキストから必要と判断される場合は XML も追加します。例：エンタープライズ／B2B 統合>
• バージョン — v1.0。
• 認証 — <コンテキストに基づいて提案します。例：「この API にはユーザー所有のリソースがあるため、OAuth2」または「B2B サービス API のようなので、API キー」>
• ページネーション — <対象となるコレクションエンドポイントを列挙>で limit/offset を使用します。 <コレクション GET がない場合は省略>」

ユーザーが確認するか、「よさそうです」と答えた場合は続行します。修正があれば反映します。

確認済みのリソースに基づいて、API の完全なアウトラインを作成します。これは YAML を生成する前の最後の確認段階です。これ以上推測しなくて済むほど、アウトラインを十分に完成させます。

アウトラインでは、残りの WSO2 設計判断をすべて扱います。

## API Overview
Name: <api-name>
Base path: /<feature-code>/v1.0
Purpose: <one-line description>

## Resources & Operations
<list all confirmed resources with their HTTP methods and a brief description of each>
(note where pagination applies, where long-running 202 applies, where concurrency matters)

## Representations
- Format: JSON (application/json)
- Key schemas:
  - <ModelName>: <field> (<type>), <field> (<type>), ...
  (3–5 most important fields per model — not exhaustive)

## Special Behaviour
- Pagination: limit (default 20) + offset (default 0) on collection GETs;
  response envelope: { count, next, previous, data: [...] }
- <any long-running operations>: 202 Accepted + Content-Location for polling
- <any resources needing concurrency control>: If-Match / If-Unmodified-Since headers

## Auth
- <recommended scheme and why>

## Errors
- Schema: { code (integer), message (string), description (string, optional),
            moreInfo (string, optional) }
- Standard responses: 400, 401, 403, 404, 429 (with Retry-After), 500

提示後：

「このアウトラインでよさそうですか？それとも、仕様を生成する前に変更したい点がありますか？」

---

Step 5 — 繰り返し調整する

自然な言葉での変更を受け付け、変更があったセクションだけを更新します。 変更のたびに、次のように尋ねます。

「更新しました。他に変更はありますか？それとも、生成に進みますか？」

ユーザーの要望が WSO2 ガイドライン（例：camelCase のパス、コレクション URI での動詞の使用）と 矛盾する場合は、その旨を簡潔に伝え、それでもユーザーが希望する場合は要望を適用します。

「WSO2 ガイドラインでは kebab-case のパスを推奨しています。/orderItems ではなく /order-items を提案します。ガイドラインを適用しますか？それとも、ご希望どおりにしますか？」

Step 6 — OpenAPI YAML を生成する

ユーザーがアウトラインを承認したら、次のように伝えます。

"OpenAPI 仕様を生成しています…"

完全な OpenAPI 3.x YAML を生成します。この仕様は WSO2 の設計ガイドラインと AI エージェント対応チェックを最初から満たす必要があります。修正を加えなくても、評価で高いスコアを得られる内容にしてください。

構成：

• openapi: "3.0.3"
• info：タイトル、説明（目的、利用者、主なユースケースを含む50文字以上）、バージョン（v1.0）、連絡先（名前 + メールアドレス）
• servers：説明付きのエントリーを1つ以上（例：「本番 API」）
• tags：リソースグループごとに1つ。アルファベット順に並べ、それぞれに説明を付けます
• paths：承認済みアウトラインのすべての操作
• components.schemas：すべてのモデルと共有 Error スキーマ
• components.securitySchemes：適切なスキーム

操作ごとに：

• operationId：動詞 + 名詞のキャメルケース（例：listProducts、createOrder、getOrderById）
• summary：ビジネスアクションを説明する命令形の動詞句
• description：操作の内容と、エージェントがいつ呼び出すべきかを説明します（2～3文）
• tags：リソースグループのタグ
• parameters：パスパラメーターはパスレベルに配置し、クエリパラメーターは操作レベルに配置します。コレクションの GET には、説明と例を付けて limit（整数、デフォルト 20）と offset（整数、デフォルト 0）を追加します
• requestBody（POST/PUT）：スキーマ $ref と具体的なインライン例
• responses：
  • コレクション GET：エンベロープ { count, next, previous, data: [...] } を含む 200
  • POST（ファクトリー／作成）：新しいリソースを指す Location ヘッダー付きの 201
  • PUT：更新後のリソース表現を含む 200（全置換、冪等）
  • DELETE：204 No Content
  • 長時間実行される POST：ポーリング用の Content-Location ヘッダー付きの 202 Accepted
  • 400、401、403、404：共有 Error スキーマを参照
  • 412：同時実行制御（If-Match / If-Unmodified-Since）を使用するリソース向け
  • 429：Error スキーマを参照し、Retry-After レスポンスヘッダーを含めます
  • 500：Error スキーマを参照

references/wso2-rest-api-design-guidelines.md にあるすべての WSO2 設計ルール（URI 形式、大文字と小文字の使い分け、名詞／動詞のルール、パラメーターの配置、スキーマの規則、エラースキーマ、セキュリティの配置）を適用してください。

文章値の YAML 衛生管理。 インラインの example:、description:、summary: などの文字列フィールドでは、解析エラーが発生しやすく、4万行の仕様書では文脈からの修復に大きなコストがかかります。次の簡単なルールを適用してください。

句読点を含む文章の文字列値は、必ず二重引用符で囲みます（または >- ブロックスカラーとして記述します）。 「句読点を含む文章」とは、英数字だけの単語ではないものを指します。

引用符で囲まないと YAML パーサーを混乱させる文字には、次のものなどがあります。アポストロフィ（'）、バッククォート（`）、山括弧（< >）、中括弧（{ }）、角括弧（[ ]）、先頭のハイフン（-）、コロンの後にスペースが続くもの（: ）、#、および > | & * ! % @ ? で始まる値。二重引用符で囲む必要がある値の例：

# wrong — bare apostrophe starts a single-quoted scalar; rest of line breaks the parser
description: 'amount' must be greater than zero.

# wrong — backticks and angle brackets confuse the parser
description: Pass as `Authorization: Bearer <token>`.

# right
description: "'amount' must be greater than zero."
description: "Pass as `Authorization: Bearer <token>`."
description: >-
  Long multi-line prose with any punctuation works fine
  inside a block scalar without escaping.

また、例の形状をスキーマに一致させます。type: object のスキーマの下で、example: を YAML シーケンス（- ...）として記述しないでください。例の形状はスキーマに一致させる必要があります。一致しないと、YAML パーサーと後続ツールの両方で問題が発生します。

仕様を生成するときは、文章を含む description／summary／example の値に、原則として二重引用符を使用してください。フィールドごとに文字を1つ追加するだけで、エラーの原因となる一連の問題をなくせます。

ページネーションエンベロープ。 アウトラインからの生成で最も見落とされやすい項目です。すべてのコレクション GET レスポンスで、単独の配列ではなく、Step 4 の { count, next, previous, data: [...] } エンベロープ形式を使用してください。リストレスポンスのスキーマが type: array になっている場合は誤りです。エンベロープフィールドを含むオブジェクトでラップしてください。

ファイルを現在のディレクトリに <api-name>-openapi.yaml として保存します。ユーザーに次のように伝えます。

"保存先：<filename>.yaml。"

---

ステップ 7 — 評価の提案

「この仕様を、AI エージェントへの対応状況、セキュリティ、設計品質の観点から評価しましょうか？」

はいの場合は、以下の評価ワークフローに進みます。

---

評価ワークフロー

あなたは API 対応状況の評価者兼修正担当者です。OpenAPI 仕様を評価する（チェックを実行してレポートを作成する）か、仕様内の問題を修正する（仕様ファイルを直接編集する）ことができます。

進め方：

1. 仕様ファイルのパスを受け取ります
2. 意図を判断します。評価（チェックの実行）か、修正（既存の問題への修正の適用）かを確認します
3. 評価の場合：指定された観点をチェックし、レポートを作成します
4. 修正の場合：修正ワークフローに従います。ユーザーの確認なしに修正を適用してはいけません

---

入力

ユーザーがまだ仕様を提示していない場合は、次のように尋ねます。

「OpenAPI 仕様ファイルのパスを教えてください。」

このスキルはディスク上のファイルを対象とします。評価と修正のどちらのフローでも、ファイルを直接読み取り、編集するためです。ユーザーが代わりに内容を貼り付けようとした場合は、まずファイルに保存してパスを共有するよう案内してください。保存先はどこでもかまいません。レポートは、作業している場所に隣接する ./api-reports/ に出力されます。

意図を判断する — 続行する前に、ユーザーが評価と修正のどちらを希望しているか判断します。

• 修正の意図：ユーザーが「fix」「correct」「apply fixes」「remediate」「patch」と言っている、課題 ID（例：「fix spec-001」）を指定している、または VS Code 拡張機能の Webview からレポートパスとともにメッセージが届いた場合は、修正ワークフローに直接進みます。
• 評価の意図：ユーザーが「check」「assess」「review」「evaluate」と言っている、または修正を示す表現なしに仕様を共有した場合は、以下に進み、実行するチェックを確認します。

実行するチェックを確認する（評価の場合のみ）— まずユーザーのメッセージから推測します。意図が本当に曖昧な場合にのみ質問してください。

次の表現がある場合は質問せずに判断します：

• 「agent readiness」「AI readiness」「LLM」「tool use」「agent」「agent-friendly」→ AI エージェント対応状況のみを実行
• 「security」「OWASP」「vulnerabilities」「auth」→ セキュリティ対応状況のみを実行
• 「design」「design guidelines」「WSO2 guidelines」「REST best practices」「API design」→ API 設計ガイドラインのみを実行
• 「all」「everything」「all three」「full assessment」→ 3 つすべてを実行
• 複数の観点に言及する表現 → 言及された観点を実行

どの観点を示す表現もなく、ユーザーが仕様を共有した場合にのみ質問します：

「何をチェックしますか？

• API 設計ガイドライン — WSO2 REST 設計ルール（28 項目）
• セキュリティ対応状況 — OWASP に基づく API セキュリティチェック
• AI エージェント対応状況 — Spectral ルール（69 項目）＋ AI 分析（11 のガイドラインカテゴリ）

1 つでも、複数でも、3 つすべてでも選べます。」

続行する前に、ユーザーの返答を待ちます。

---

事前確認 — Spectral の利用可否

Spectral はすべての観点（AI エージェント対応状況、セキュリティ、設計）で必要です。LLM による作業を始める前にインストールされていることを確認してください。こうすることで、ツールが見つからない問題を、数分かかる分析の後ではなく、すぐに把握できます。

spectral --version

コマンドが失敗するか、見つからない場合は、処理を止めてユーザーに次のように伝えます。

「この評価には Spectral CLI が必要です。次のコマンドでインストールしてください。 npm install -g @stoplight/spectral-cli インストール後、ここで確認してください。」

確認を待ってから spectral --version を再実行し、続行します。これが成功するまでは、LLM 分析や assess.js の実行に進まないでください。安全策として assess.js にも独自の事前確認がありますが、ここで問題を検出すれば、AI 分析に費やされるはずだった LLM トークンを節約できます。

---

AI エージェント対応状況 — LLM 分析

AI エージェント対応状況の評価が依頼されていない場合（セキュリティのみ、設計のみの実行など）は、このセクション全体をスキップし、Outputに進んでください。

機械的な処理（Spectral、レポートの組み立て、HTML、概要）はすべて、下記のOutputにある単一の assess.js 呼び出しで行われます。LLM 分析だけはコンテキスト内で実施する処理であり、その結果を渡せるよう、この呼び出しの前に完了しておく必要があります。

ユーザーに次のように伝えてください。

"AI 分析を実行しています — 11 のエージェント対応ガイドラインカテゴリに照らして仕様を確認しています…"

references/agent-readiness-guidelines.md を最後まで読んでください。

11 のカテゴリを順番に確認してください。各ルールについて、仕様の関連するすべての箇所（操作、パラメーター、スキーマ、レスポンスコード、パス）を調べてください。該当しそうにない場合でもカテゴリを省略せず、徹底的に確認してください。

見つかった違反ごとに、次のフィールドを含むオブジェクトを記録してください（id は不要です。assess.js が ID を割り当てて並べ替えます）。

• severity：ガイドラインで定義されている重大度（CRITICAL / HIGH / MEDIUM / LOW）。
• rule：ガイドラインに記載されたルール参照（例：Rule 3.3）。
• path：該当する要素への JSON パス（例：paths./orders.post）。
• issue：問題の簡潔な説明。
• description：エージェントへの影響 — この違反によってエージェントが誤った動作をする内容。
• fixSuggestion：変更内容を簡潔かつ具体的に示す修正案。

すべての違反を見つけたら、Write ツールを使って配列を ./api-reports/ai-issues.json に保存してください（Write ツールは ./api-reports/ が存在しない場合に作成します）。Outputセクションで assess.js に --ai-issues ./api-reports/ai-issues.json を渡してください。実行が成功すると、assess.js はこのファイルを削除します。レポートはそのまま残ります。

このパスを使う理由：相対パスなので macOS、Linux、Windows で同じように機能し、最終レポートの出力先と同じ ./api-reports/ ディレクトリに保存されます。そのため、Write の許可確認に表示されるパスもユーザーにとって見慣れたものになります。これにより、Bash の確認プロンプトに長いインライン JSON を含めることや、一時ディレクトリの解決方法がプラットフォームごとに異なる問題を避けられます。

---

セキュリティ対応状況と API 設計ガイドライン

これらの評価項目は完全に機械的に確認するもので、Spectral のみを使用し、LLM による処理はありません。Outputにある単一の assess.js 呼び出しの一部として実行されます。実際に実行されるときに assess.js が各評価項目の進行状況（Running security rules (OWASP-derived)...、Running design guidelines rules (WSO2 REST)...）を出力するため、事前に実行を予告しないでください。事前に予告すると、処理が始まる前に完了したような印象を与え、ユーザーがその後で Spectral の進行状況を見たときに混乱します。

---

出力

必要な LLM 分析（上記）が完了するまでは、最終レポートを出力しないでください。LLM の分析中に「AI 分析を実行中です…」などの簡潔な状況報告をするのは問題ありません。ただし、スクリプトを実行する前に「完了しました」や「レポートを生成しています」と伝えないでください。assess.js 自体が Spectral の実行を行うため、先走った「完了しました」というメッセージは、ユーザーがこれから目にする出力と矛盾します。

コマンドは 1 つだけ実行してください。assess.js は、指定されたルールセットをそれぞれ実行し、LLM 分析（--ai-issues が指定されている場合）を統合してレポートを作成し、HTML を生成し、概要を出力します。さらに、オプションで HTML をブラウザーで開きます。これらすべてを 1 つのプロセス、1 回の Bash 承認で実行します。Spectral が利用可能であることは Preflight の手順ですでに確認済みなので、ここで spectral --version を再実行したり、その他の予防的な確認（スクリプトに対する ls など）を行ったりしないでください。

node <absolute-path-to-skill>/scripts/assess.js \
  --spec <spec-file-path> \
  --skill-dir <absolute-path-to-skill> \
  --meta '{"specFile":"<path>","assessedAt":"<ISO-8601-UTC>","spectralVersion":"<version>","guidelinesVersion":"agent-readiness-guidelines.md","model":"<model-id>"}' \
  [--agent] [--security] [--design] \
  [--ai-issues ./api-reports/ai-issues.json] \
  [--open]

注：

• ユーザーが指定したディメンションのフラグだけを渡してください。少なくとも 1 つ必要です。
• --agent が設定されている場合は、AI Agent Readiness — LLM Analysis セクションで作成したファイルである --ai-issues ./api-reports/ai-issues.json が必須です。assess.js は実行が正常に完了すると、このファイルを削除します。セキュリティのみ、または設計のみの実行では、--ai-issues を指定しないでください。
• --spec はユーザーが指定したファイルパスです。
• CLI／スタンドアロンチャットで実行する場合、--open を指定すると既定のブラウザーで HTML が開きます。VS Code API Designer 拡張機能内では、代わりに openInApiDesigner がウェブビューを処理するため、指定しないでください。
• Spectral がインストールされていない場合、assess.js はインストール方法として npm install -g @stoplight/spectral-cli を表示して終了コード 1 で終了します。これをユーザーに伝え、インストールが完了するまで待ってから再実行してください。

スクリプトの標準出力をそのまま回答として表示してください。スクリプトは最後にレポートと HTML のパスを出力します。次の手順ではそのパスを使用してください。

ステップ 2 — 次の手順を提示する

VS Code API Designer 拡張機能内で実行している場合（使用可能なツール一覧に openInApiDesigner がある場合）：

• 引数なしで openInApiDesigner を呼び出します。拡張機能がレポートのウェブビューをすぐに開きます。
• 続けて、"仕様に修正を適用しますか？" と尋ねます。
• はいの場合は、修正ワークフローに進みます。

CLI またはスタンドアロンチャットモードで実行している場合（openInApiDesigner が利用できない場合）：

• 上記で --open を指定していない場合は、"HTML レポート全体をブラウザーで開きますか？" と尋ねます。はいの場合は、assess.js を再実行する必要はありません（ファイルはすでにディスク上にあります）。assess.js が出力した HTML のパスを使い、プラットフォームに応じたコマンドで開いてください。
  • macOS：open <html-path>
  • Linux：xdg-open <html-path>
  • Windows：start <html-path>
• 続けて、"仕様に修正を適用しますか？" と尋ねます。
• はいの場合は、修正ワークフローに進みます。

---

修正ワークフロー

このワークフローは、次の 2 つの状況で適用されます。

• 評価後：概要を提示した後、ユーザーが「はい、修正して」または「修正を適用して」と答えた場合
• 直接実行：直接修正するために呼び出された場合（例：VS Code 拡張機能のウェブビューから）

修正は常に、ユーザーが指定したパスにある仕様ファイルに直接適用します。

---

ステップ 1 — 問題の一覧を特定する

修正する問題の一覧が必要です。利用可能な情報源を上から順に確認してください。

1. 評価後：直前に生成したレポートの問題がすでにコンテキストにある場合は、それを使用します。
2. レポートのパスが指定されている場合：JSON レポートファイルを読み込み、すべてのセクション（agentReadiness.spectral.issues、agentReadiness.aiAnalysis.issues、securityReadiness.spectral.issues、designReadiness.spectral.issues）からすべての問題を収集します。
3. 問題 ID が指定されている場合：ユーザーが「spec-001 と des-003 を修正して」と言った場合は、レポートからそれらの ID の問題に絞り込みます。
4. 重大度フィルター：ユーザーが「HIGH をすべて修正して」と言った場合は、それに応じて絞り込みます。
5. 「autoFixable をすべて」：autoFixable: true の問題に絞り込みます。

上記のいずれにも該当せず、レポートも存在しない場合は、次のように尋ねます。

「評価レポートの JSON はありますか？ある場合は、パスを共有してください。ない場合は、先に評価を実行できます。」

例外 — レポートがない状態で「autoFixable をすべて」または「HIGH をすべて」と指定された場合。 条件 5（および「HIGH をすべて」のようなフィルター）は、評価レポートなしでは判定できません。ユーザーがレポートなしでの修正を明確に希望している場合（例：「my-spec.yaml にすべての autoFixable 修正を適用して」）は、質問せずに、評価ワークフローの出力ステップを使って自分で評価を実行します（--agent --security --design を指定して assess.js を 1 回実行します。spectral を手動で呼び出す必要はありません）。次に、その新しいレポートを問題の情報源として使用し、以下のステップ 2 に進みます。

---

ステップ 2 — 仕様を読む

仕様ファイルを最後まで読みます。複数の対象を編集するため、内容をコンテキストに保持してください。

---

ステップ 3 — 問題を分類する

修正する問題を、次の 3 つのグループに分けます。

A. 安全な構造的修正 — autoFixable: true で、パス名変更ルールではないもの： パスキーを変更せずにフィールドを追加または編集します。例：operationId の追加、スキーマへの type: object の追加、Retry-After ヘッダーを含む 429 レスポンスの追加、タグのアルファベット順での並べ替え。

B. パス名の変更 — ルール paths-no-trailing-slash、path-casing、paths-no-http-verbs： これらのルールはパスキーの名前を変更するため、既存の API クライアントに影響します。警告を添えて個別に扱います。

C. LLM 生成コンテンツ — autoFixable: false： 説明、要約、例、連絡先情報、セキュリティスキームの説明などです。LLM が仕様のコンテキストに基づいて適切な値を生成します。

---

ステップ 4 — 安全な構造的修正を適用する

グループ A の各問題について、順番に次の手順を実行します。

1. path フィールド（paths./orders.post.operationId のようなドット記法）を解析して、仕様内の要素を特定します。パスの各セグメントは、ネストされた YAML／JSON キーに対応します：paths → /orders → post → operationId。
2. fixSuggestion を読み、追加または変更する内容を正確に確認します。
3. Edit ツールを使って、最小限かつ対象を絞った編集を適用します。指摘された要素のみを変更し、周囲の内容には手を加えません。
4. 修正済みとして問題 ID を記録します。

---

ステップ 5 — パス名変更の修正を処理する（確認を取る）

グループ B に問題が 1 つでもある場合は、適用する前に変更案を提示します。

「次の修正ではパス URL の名前を変更します。これらのエンドポイントを使用している既存のクライアントには、破壊的変更となります。

• /users/ → /users（末尾のスラッシュを削除）
• /getUsers → /users（HTTP 動詞を削除）

適用する場合は確認してください。変更しない場合は「skip」と言ってください。」

確認が取れた場合：仕様内のパスキーの名前を変更します。パスキーは paths: の下にあり、他の箇所の $ref 文字列にも含まれている場合があります。両方の箇所を変更してください。

---

ステップ 6 — LLM が生成したコンテンツの問題を修正する

グループ C の各問題について：

1. fixSuggestion と、問題の path にある関連する仕様を読み、文脈を確認します。
2. 適切なコンテンツを作成します。実際の操作を反映した説明や、スキーマに合った例などを記述してください。「TODO」や「description here」のようなプレースホルダーテキストは使用しないでください。
3. Edit ツールを使って適用します。

グループ C に問題が 5 件を超える場合は、適用する前に各項目の内容を提示します。

「次の内容を追加します。適用するには確認してください。変更したい箇所があればお知らせください。

• paths./users.get.description："登録済みのすべてのユーザーを、ページネーション付きで返します。"
• paths./users.post.description："新しいユーザーアカウントを作成します。" ...」

---

ステップ 7 — 概要

すべての編集が完了したら：

「修正が完了しました。 適用済み（N 件）： spec-001、des-003、ai-007 … スキップ — path-rename（N 件）： des-010、des-011（未確認） 手動対応が必要（N 件）： sec-001 — OAuth スキームの設定にはアーキテクチャ上の判断が必要です。レポートの fixSuggestion を参照してください。

<path> の仕様をインプレースで更新しました。」

OWASP のセキュリティ問題と、仕様に記載されている情報だけでは解決できないドメイン知識が必要な問題（実際のサーバー URL や連絡先情報など）は、推測で補わず、「手動対応が必要」に記載してください。

---

参照ファイル

必要に応じて読み込んでください。最初にすべてを読み込む必要はありません。

• references/wso2-rest-api-design-guidelines.md — WSO2 の 7 ステップの設計プロセス、リソースの分類、URI のルール、HTTP のセマンティクス、特殊な動作、エラー。「Design Workflow」の開始時に読んでください。
• references/agent-readiness-guidelines.md — AI Agent Readiness のための 11 の LLM 分析カテゴリ（フェーズ 2）
• references/ai-readiness-metadata.json — 69 個の Spectral AI-readiness ルールのメタデータ
• references/owasp-top-10-metadata.json — OWASP に基づく API セキュリティルールのメタデータ
• references/wso2-design-guidelines-metadata.json — WSO2 REST 設計ルールのメタデータ
• references/report-schema.md — JSON レポート構造のドキュメント