DEV Community

Cover image for PRDからテストまで：Apidog CLIで効率化するエージェント開発ワークフロー
Akira
Akira

Posted on • Originally published at apidog.com

PRDからテストまで：Apidog CLIで効率化するエージェント開発ワークフロー

これは、APIテストとAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをApidogがどのように開発したかを共有する全10回のシリーズです。順番に読むか、興味のある記事に直接アクセスしてください。

Apidogを今すぐ試す

タイトル 焦点
1 当社は126のMCPツールを構築しました。しかし、それはAgentにとって最良のソリューションではありません 問題の発見
2 当社が真新しいApidog CLIを開発した理由 アーキテクチャ開発
3 黄金律：CLIは事実を生成し、モデルは事実に基づいて動作する 中核となる哲学
4 agentHints: CLIにAgentと話す方法を教える 構造化された出力
5 SKILL: 運用経験をコードとして出荷する 運用経験
6 数字は嘘をつかない：ツール呼び出し30%減、トークン25%減 定量的結果
7 PRDからテストループまで：Apidog CLIによる完全なAgentワークフロー 実用的なチュートリアル
8 AgentツールにとってCI/CD互換性が不可欠な理由 DevOpsの視点
9 AIブランチ：AI Agentによるより安全なプロジェクト変更 セキュリティレイヤー
10 仕様ファーストは昨日。スキルファーストへようこそ。 ビジョンと未来

この記事では、注文返金機能を例に、PRDとコードベースからOpenAPIを生成し、Apidog CLI + SKILLでテストケース作成、シナリオ構築、検証実行までをエンドツーエンドで進めます。

シナリオ

前提は次のとおりです。

  • チームは「注文返金」に関するPRDを作成済み
  • コードベースには対応するルートとコントローラーが存在する
  • AgentにAPIテストの生成と検証を依頼する

Agentへのユーザーリクエスト：

PRDとコードベースに基づいて、返金機能のAPIテストを生成し、検証を実行してください。

古いアプローチの問題

MCPツールだけで進める場合、Agentは実装作業の前に多くの判断を行う必要があります。

決定点 不確実性
まずプロジェクトを照会するか？ それともまずエンドポイントを作成するか？
まずテストケースを作成するか？ それともまずスキーマを生成するか？
直接テストを実行するか？ それともまずリソースを読み戻すか？
各ステップにどのツールを使用するか？ 126個のツールの中から検索する

結果として、Agentはタスクの実行よりも、実行パスの決定に多くのコストを使います。

CLI + SKILLで進めるワークフロー

CLI + SKILLでは、R&Dフローを明確な手順に分解します。

PRDとコードベースからOpenAPIを生成
        ↓
Apidogにインポート
        ↓
単一エンドポイントのテストケースを追加
        ↓
書き込む前に検証
        ↓
ビジネスフローのテストシナリオを生成
        ↓
書き込む前に検証
        ↓
自動テストを実行
Enter fullscreen mode Exit fullscreen mode

以下では、この流れを実装手順として見ていきます。

ステップ1: OpenAPIを生成してApidogにインポートする

AgentはPRDとコードベースを読み込み、OpenAPI仕様を生成します。

PRDの例：

Order Refund API

POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number }
- Response: { "refundId": string, "status": string, "processedAt": datetime }

GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number }
Enter fullscreen mode Exit fullscreen mode

生成されるOpenAPIの例：

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Create refund request",
        "parameters": [],
        "requestBody": {},
        "responses": {}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Get refund status"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Apidogにインポートします。

apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

CLI出力例：

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPIが正常にインポートされました。2つのエンドポイントが作成されました。",
    "nextSteps": [
      "インポートされたエンドポイントをリストして構造を確認する。",
      "各エンドポイントのテストケースを追加する。",
      "完全な返金フローのテストシナリオを作成する。"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

ここで重要なのは、CLIが単なる成功/失敗だけでなく、次に行うべき操作をagentHintsとして返す点です。

ステップ2: 単一エンドポイントのテストケースを作成する

次に、返金作成エンドポイントを対象にテストケースを作成します。

まず、インポート済みエンドポイントを読み込みます。

apidog endpoint get ep-001 --project <projectId>
Enter fullscreen mode Exit fullscreen mode

CLIはエンドポイント構造を返します。

{
  "id": "ep-001",
  "method": "POST",
  "path": "/api/orders/{orderId}/refund",
  "requestBody": {
    "schema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["reason", "amount"]
    }
  },
  "responses": {
    "200": {}
  }
}
Enter fullscreen mode Exit fullscreen mode

この構造をもとに、AgentはテストケースJSONを生成します。

{
  "name": "Create refund - success",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Customer request",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "processed"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

書き込む前に、ローカルでスキーマ検証します。

apidog cli-schema validate test-case-create --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

検証結果の例：

{
  "success": true,
  "agentHints": {
    "summary": "テストケースの構造は有効です。",
    "nextSteps": [
      "Apidogでテストケースを作成する。",
      "作成されたテストケースを読み戻して確認する。",
      "必要に応じてアサーションを追加する。"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

検証に成功したら、テストケースを作成します。

apidog test-case create --project <projectId> --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

CLI出力例：

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Create refund - success"
  },
  "agentHints": {
    "summary": "テストケースが正常に作成されました。",
    "nextSteps": [
      "テストケースtc-001を読み戻してアサーションを確認する。",
      "GET /refund/{refundId}のテストケースを作成する。",
      "完全な返金フローのテストシナリオを構築する。"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

この手順により、Agentは無効なJSONや不完全なフィールドをApidogに書き込む前に検出できます。

ステップ3: 完全なビジネスフローのテストシナリオを作成する

PRDに基づく完全なビジネスフローは次のとおりです。

注文の作成 → 支払い → 返金 → 返金ステータスの照会
Enter fullscreen mode Exit fullscreen mode

Agentはこの流れをテストシナリオとして定義します。

{
  "name": "Order Refund Complete Flow",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

ここでも、書き込む前に検証します。

apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

問題がなければ、シナリオを作成します。

apidog test-scenario create --project <projectId> --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

ステップ4: 自動テストを実行する

テストケースとシナリオの準備ができたら、apidog runで検証を実行します。

apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

CLI出力例：

{
  "success": true,
  "stats": {
    "total": 4,
    "passed": 4,
    "failed": 0
  },
  "reportFiles": {
    "cli": "./apidog-reports/cli-report.txt",
    "html": "./apidog-reports/report.html",
    "junit": "./apidog-reports/junit.xml"
  },
  "agentHints": {
    "summary": "すべてのテストに合格しました。4つのステップが正常に実行されました。",
    "nextSteps": [
      "詳細な結果についてはHTMLレポートを確認する。",
      "失敗が発生した場合は、CLIのエラー詳細を使用してデバッグする。",
      "このテストをCIパイプラインに統合する。"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

htmlやjunitレポートを出力しておくと、ローカル確認だけでなくCI/CDにも接続しやすくなります。

完全な連鎖

このワークフローでは、次の要素が接続されます。

要素 ステータス
PRD 読み込みと処理済み
コードベース ルートを解析済み
OpenAPI 生成とインポート済み
エンドポイント資産 Apidogで作成済み
単一エンドポイントテスト 作成と検証済み
ビジネスシナリオ 構築と検証済み

すべてのステップがCLIコマンドとして実行され、検証可能で追跡可能になります。

フロー全体でのagentHints

agentHintsは、各ステップの後でAgentに次の行動を示します。

タイミング agentHintsの提案
エンドポイントのインポート後 エンドポイントをリストし、テストケースを追加する
テストケース作成後 読み戻し、さらにテストケースを作成し、シナリオを構築する
シナリオ作成後 アサーションを追加し、検証し、実行する
テスト実行後 レポートを確認し、必要に応じてデバッグし、CIに統合する

これにより、Agentは次に何をすべきかを推測する必要がありません。

MCPとCLI + SKILLの比較

同じタスクを実行する場合の違いは次のとおりです。

側面 MCPアプローチ CLI + SKILLアプローチ
開始点 Agentがプロジェクトツールを検索する SKILLがタスクタイプを識別する
エンドポイントの作成 Agentがどのツール、どのフィールドを使用するかを推測する OpenAPIからCLIインポート
テストケースの作成 フィールドエラーで複数回再試行 書き込み前のローカル検証
シナリオの構築 Agentが構造を手書きする ステップをインポートし、読み戻し、更新する
検証 Agentが実行ツールを見つける シナリオ後にagentHintsが提案する
合計ステップ数 再試行を含む〜20-25回の呼び出し 〜10-12回の検証済み呼び出し

CLI + SKILLの主な利点は、実行順序、入力構造、検証、次のアクションが明確になることです。

次は何？

この例では、CLI + SKILLを使って次の流れを実装しました。

PRD → OpenAPI → インポート → テストケース → シナリオ → 検証
Enter fullscreen mode Exit fullscreen mode

ただし、このワークフローを実運用に載せるには、CI/CDとの互換性が重要です。

パート8のAgentツールにとってCI/CD互換性が不可欠な理由では、apidog runがCIパイプラインとAI Agentの両方に役立つ理由、そしてその二重の目的が持続可能なツール設計にとって重要である理由を説明します。

主要なポイント

  • 完全なワークフローは、PRD → OpenAPI → インポート → テストケース → シナリオ → 検証
  • 各ステップはCLIコマンド、スキーマ検証、agentHintsで構成される
  • 書き込み前にapidog cli-schema validateで構造を確認する
  • ステップのインポートと読み戻しは、シナリオを手書きするより安全
  • --with-case-detailは更新に必要な実用的な構造を提供する
  • agentHintsがステップ間の遷移をガイドする
  • すべての操作が検証可能で追跡可能になる

Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント化を行いましょう。コマンドラインAPIテスト、CI自動化、AI Agentワークフロー向けのApidog CLIについてさらに詳しく学びましょう。

Top comments (0)