これは、Apidog が API テストおよび API ライフサイクル管理のためのコマンドラインツールである Apidog CLI をどのように開発したかを共有する全10回のシリーズです。順番に読むか、必要なテーマから直接参照してください。
| タイトル | 焦点 | |
|---|---|---|
| 1 | 当社は126のMCPツールを構築しました。しかし、それはAgentにとって最良の解決策ではありません | 問題の発見 |
| 2 | なぜ当社は全く新しいApidog CLIを開発したのか | アーキテクチャ開発 |
| 3 | 黄金律：CLIは事実を生成し、モデルは事実に従って行動する | 核となる哲学 |
| 4 | agentHints: CLIにAgentとの会話を教える |
構造化出力 |
| 5 | SKILL：運用経験をコードとして出荷する | 運用経験 |
| 6 | 数字は嘘をつかない：ツール呼び出しは30%減、トークンは25%減 | 定量的結果 |
| 7 | PRDからテストループまで：Apidog CLIによる完全なAgentワークフロー | 実践的なチュートリアル |
| 8 | なぜCI/CD互換性がAgentツールにとって不可欠なのか | DevOpsの視点 |
| 9 | AIブランチ：AI Agentによるより安全なプロジェクト変更 | セキュリティレイヤー |
| 10 | Spec-Firstは昨日。Skill-Firstへようこそ。 | ビジョンと未来 |
当社は、MCPが最適化しない複雑なワークフロー、つまり検証ゲートと構造化された実行を伴うワークフローを処理するために、CLI + SKILLを構築しました。
MCPはその目的を果たし続けています
CLI + SKILLに入る前に、前提を明確にします。
Apidog MCPは現在も利用可能で、メンテナンスされています。
MCPは、プロトコルに従って標準化されたツール接続を提供します。特に以下の用途に適しています。
- シンプルで明確に定義された操作
- MCPベースのワークフローを好むユーザー
- MCP準拠クライアントとのエコシステム統合
当社はMCPを置き換えたわけではありません。CLI + SKILLはMCPを補完するために構築されました。
MCPはツール接続に優れています。一方で、検証、読み戻し、実行確認を伴う多段階のR&Dワークフローでは、Agentに対して実行可能なエンジニアリングプロセスを提供するほうが安定します。そこにCLI + SKILLが適合します。
タスクごとに使い分けると、次のようになります。
| タスクタイプ | 推奨されるアプローチ |
|---|---|
| シンプルなツール呼び出し（例：エンドポイントの取得） | MCPまたはCLI。どちらも機能します |
| 多段階ワークフロー（例：テストの作成、検証、実行） | CLI + SKILL。より良い体験になります |
| CI/CD統合 | CLI。ネイティブに適合します |
| MCPエコシステム統合 | MCP。プロトコル標準に適合します |
古いCLI：最後にテストを実行する
Apidog CLIは長年、APIテストを実行するためのコマンドラインのエントリポイントでした。
apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>
この基盤は今も重要です。チームには以下を行うための信頼できる方法が必要です。
- ターミナルからAPIテストを実行する
- CIパイプラインでレポートを生成する
- 自動化ワークフロー内で品質ゲートを維持する
ただし、古いCLIの主な役割はテスト実行でした。つまり、ワークフローの終盤で使われます。
設計 → ドキュメント化 → モック → デバッグ → テスト → [CLIがテストを実行]
CLIは最後のステップでした。他の作業が完了したあとに、既存のテストを実行するためのものだったのです。
新しい要件：Agentにはより多くの操作が必要
API開発は変化しています。
AI Agentは現在、APIライフサイクルの複数段階に参加します。
| 段階 | Agentの活動 |
|---|---|
| API設計 | PRDからエンドポイント定義を生成する |
| テスト生成 | API仕様からテストケースを作成する |
| デバッグ | 障害を分析し、修正案を提示する |
| 移行 | プロジェクト間でAPIを移動する |
| メンテナンス | API変更時にテストを更新する |
このようなワークフローでは、CLIは既存テストを最後に実行するだけでは不十分です。
Agentが安定して作業するには、CLI側で次の操作を提供する必要があります。
- APIアセット（エンドポイント、スキーマ、環境）を読み取る
- テストアセット（テストケース、テストシナリオ）を作成または更新する
- 書き込み前に構造化された変更を検証する
- 変更をプロジェクトに書き戻す
- 実行結果を検証する
増分的な追加ではなく、体系的な拡張
新しいApidog CLIは、古いCLIにいくつかのコマンドを追加しただけではありません。
目的は、Apidogのコア機能をCLIに体系的に導入し、開発者、スクリプト、AI Agentのためのワークフローレイヤーとして機能させることです。
| 古いCLIの質問 | 新しいCLIの質問 |
|---|---|
| 「Apidogのテストを外部で実行するにはどうすればよいですか？」 | 「AI AgentはApidogを安定してどのように使用できますか？」 |
この問いの変化により、CLIのアーキテクチャ上の境界線も大きく変わりました。
MCPとCLIの比較：実行チェーンを見る
複雑なワークフローでは、実行チェーンの違いが重要です。
MCPルート：ツール接続に適している
MCPセッションの初期化
↓
ツールリスト + ツール説明のロード
↓
Agentがツールを選択
↓
さらなるツールを検索 (listOpenApiEndpoints)
↓
スキーマを取得 (getOpenApiDetails)
↓
HTTP呼び出しを実行 (executeOpenApi)
MCPの強みは、ツールをAgentに接続するための標準化されたプロトコルを提供することです。
一方で、複雑性の多くはモデルコンテキストとツール選択段階に置かれます。Agentは次の要素を理解する必要があります。
- ツールリスト
- ツール説明
- 入力スキーマ
- 呼び出しシーケンス
- 戻り値の構造
MCPは、明確なツールとタスクのマッピングを持つシンプルな操作に適しています。
課題になるのは、Agentが複数のツールをオーケストレーションし、製品のセマンティクスを理解し、検証を処理する必要があるワークフローです。
CLI + SKILLルート：複雑なワークフローに適している
SKILLがタスクタイプを判断
↓
CLIが製品セマンティックなコマンドを実行
↓
cli-schemaが構造を検証
↓
agentHintsが次のステップの提案を行う
↓
検証ループ（読み戻しまたはapidog run）
CLI + SKILLの強みは、複雑性をエンジニアリングシステム側に分散できることです。
役割は次のように分かれます。
- SKILL：方法論とワークフローガイダンス
- CLI：製品セマンティックな実行
- cli-schema：書き込み前の構造検証
- agentHints：実行後のナビゲーション
この構成は、多段階ワークフロー、検証重視の操作、Agent駆動テストに適しています。
重要な違い：複雑性がどこに存在するのか
MCPとCLI + SKILLの違いは、複雑性がどこに配置されるかです。
| アプローチ | 複雑性が存在する場所 | 最適な用途 |
|---|---|---|
| MCP | モデルコンテキスト + ツール選択段階 | シンプルなツール呼び出し、MCPエコシステム |
| CLI + SKILL | エンジニアリングシステム（SKILL、CLI、検証、ヒント） | 複雑なワークフロー、多段階操作 |
MCPでは、モデルが次の情報を保持する必要があります。
- どのツールを使用するか
- ツールの説明が何を意味するか
- どのフィールドが必要か
- どの順序で呼び出すか
- 戻り値の構造が何を意味するか
これは、タスクとツールの対応が単純な場合には機能します。
CLI + SKILLでは、エンジニアリングシステムが次の情報を保持します。
- これがどのタスクタイプであるか（SKILL）
- どのコマンドを実行するか（CLI）
- どの構造が有効か（cli-schema）
- 次に何をすべきか（agentHints）
検証ゲート、読み戻し要件、検証ループがあるワークフローでは、このほうが安定します。
典型的なCLI + SKILLワークフロー
CLI + SKILLワークフローの基本形は、次の3ステップです。
# ステップ1：事実を読み取る
apidog endpoint get <endpointId> --project <projectId>
# ステップ2：書き込み前に構造を検証する
apidog cli-schema validate test-case-create --file ./test-case-create.json
# ステップ3：検証を実行する
apidog run --project <projectId> --out-dir ./apidog-reports
それぞれのコマンドは、明確なエンジニアリングアクションに対応します。
| コマンド | アクション |
|---|---|
endpoint get |
プロジェクトから事実を読み取る |
cli-schema validate |
書き込み前に構造を検証する |
apidog run |
検証を実行する |
実装時のポイントは、Agentに直接「作成して」と指示する前に、まず既存状態を読ませることです。
推奨フローは次のとおりです。
読み取り → 生成 → 検証 → 書き込み → 実行確認
この順序にすることで、Agentが推測だけで変更を書き込むリスクを下げられます。
複雑なワークフローのためのAgentパス
複雑な多段階ワークフローでは、Agentの実行パスを設計する必要があります。
MCPパス
ツールを選択 → スキーマを理解 → シーケンスをオーケストレーション → エラーを処理
Agentは次の判断を行います。
- 多くのオプションから適切なツールを選択する
- ツールの説明とスキーマを理解する
- 正しいシーケンスを組み立てる
- エラー時にリトライする
この方法でもタスクは完了できます。ただし、各決定点でモデルに多くの推論が必要になります。
CLI + SKILLパス
事実を読み取る → 変更を生成 → 構造を検証 → 書き込み → 検証を実行
Agentは次の流れで動きます。
- 既存の事実を読み取る（SKILLによるガイド）
- 事実に基づいて変更を生成する
- 構造をローカルで検証する（cli-schema）
- プロジェクトに書き込む
- 検証を実行する（agentHintsが次のステップをガイド）
エンジニアリングシステムが検証、ガイダンス、実行確認を担うことで、モデルの推論負担を下げられます。
どちらのパスでもタスクは完了できます。CLI + SKILLは、モデルコンテキスト側の複雑さを減らすためのアプローチです。
CLIが現在カバーしているもの
アップグレードにより、CLIはより多くのApidogコアリソースをカバーするようになりました。
| リソース | CLI機能 |
|---|---|
| プロジェクトとメタデータ | リスト表示、読み取り |
| APIとAPI定義 | 取得、作成、更新 |
| 環境と変数 | リスト表示、管理 |
| テストケース | 作成、更新、検証 |
| テストシナリオ | 作成、更新、ステップのインポート、詳細付きで取得 |
| テストスイート | 管理 |
| レポート |
apidog runから生成 |
| インポート/エクスポート | プロジェクトのエクスポート、ファイルのインポート |
これにより、Apidog CLIの役割は変わりました。
CLIは、すべてが完了したあとにテストを実行するだけのものではありません。
開発ループの早い段階で、Agentが次の作業を行うための実行レイヤーになります。
- プロジェクトを理解する
- テストアセットを生成または更新する
- 変更を検証する
- 検証を実行する
アーキテクチャの概要
MCPとCLI + SKILLを比較すると、役割の違いは次のようになります。
| 側面 | MCP | CLI + SKILL |
|---|---|---|
| 主な強み | ツール接続 | ワークフロー実行 |
| 複雑性の配置 | モデルコンテキスト | エンジニアリングシステム |
| 複雑なタスクのAgentパス | 選択、オーケストレーション、リトライ | 読み取り、検証、書き込み、検証 |
| カバレッジ | 126の生成されたツール + ネイティブツール | 完全なリソース管理 + 検証 |
| 最適な用途 | シンプルな操作、MCPエコシステム | 複雑なワークフロー、CI/CD |
両方とも利用可能です。タスクの性質に基づいて選択してください。
実装時の判断基準
実際のプロジェクトでは、次の基準で選択できます。
MCPを選ぶケース
- 1回または少数のツール呼び出しで完了する
- 入力と出力が明確
- MCP準拠クライアントとの統合が目的
- ワークフローの検証ステップが少ない
CLI + SKILLを選ぶケース
- 読み取り、生成、検証、書き込み、実行確認が必要
- テストケースやテストシナリオを作成・更新する
- CI/CDに組み込みたい
- Agentに安定した手順を踏ませたい
- 書き込み前にスキーマ検証を行いたい
特に、Agentがプロジェクトに変更を書き込む場合は、次のような手順を基本にします。
# 1. 既存情報を取得する
apidog endpoint get <endpointId> --project <projectId>
# 2. 生成した変更ファイルを検証する
apidog cli-schema validate <schema-name> --file ./change.json
# 3. 必要な書き込みを行う
# 例：テストケースやシナリオの作成・更新
# 4. テストを実行して結果を確認する
apidog run --project <projectId> --out-dir ./apidog-reports
ポイントは、Agentの出力をそのまま書き込むのではなく、CLI側の検証ゲートを通すことです。
次は何ですか
CLI + SKILLがMCPをどのように補完するかを見てきました。次のテーマは、次の問いです。
CLI + SKILLが複雑なワークフローで効果的である核となる原則は何ですか？
パート3「黄金律：CLIは事実を生成し、モデルは事実に従って行動する」では、すべてのCLI + SKILLの設計判断を導く考え方を扱います。特に、失敗した書き込みになる前にエラーを捕捉する品質ゲートである cli-schema validate から説明します。
主要なポイント
- MCPは引き続き機能します。シンプルな操作やMCPエコシステム統合に利用できます
- CLI + SKILLはMCPを補完します。検証を伴う複雑なワークフローに適しています
- 重要な違いは、複雑性がどこにあるかです。モデルコンテキストか、エンジニアリングシステムか
- CLI + SKILLは、検証、ガイダンス、実行確認によってモデルの推論負担を軽減します
- CLIは現在、プロジェクト、API、環境、テストケース、シナリオなどをカバーしています
- どちらのアプローチも利用可能です。タスクの複雑性に基づいて選択してください
Apidogをダウンロードして、APIを1つのワークスペースで設計、モック、テスト、ドキュメント化しましょう。コマンドラインAPIテスト、CI自動化、AI AgentワークフローのためのApidog CLIについてさらに詳しく学ぶ。
Top comments (0)