これは、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がツール接続に優れている一方で、検証、読み戻し、検証を伴う多段階プロセスのような複雑な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は現在、以下に参加しています：
| 段階 | Agentの活動 |
|---|---|
| API設計 | PRDからのエンドポイント定義の生成 |
| テスト生成 | API仕様からのテストケースの作成 |
| デバッグ | 障害の分析、修正の提案 |
| 移行 | プロジェクト間でのAPIの移動 |
| メンテナンス | API変更時のテストの更新 |
これらのワークフローでは、CLIは既存のテストを実行する最後のステップだけではいけません。
Agentが以下のことを安定して行える方法も提供する必要があります：
- APIアセット（エンドポイント、スキーマ、環境）を読み取る
- テストアセット（テストケース、テストシナリオ）を作成または更新する
- 書き込み前に構造化された変更を検証する
- それらをプロジェクトに書き戻す
- 結果を検証する
増分的な追加ではなく、体系的な拡張
新しいApidog CLIは、古いCLIにいくつかのコマンドを追加するだけではありません。
それはApidogのコア機能をCLIに体系的に導入し、開発者、スクリプト、AI Agentのためのワークフローレイヤーとして機能させます。
| 古いCLIの質問 | 新しいCLIの質問 |
|---|---|
| 「Apidogのテストを外部で実行するにはどうすればよいですか？」 | 「AI AgentはApidogを安定してどのように使用できますか？」 |
背後にあるアーキテクチャの境界線は劇的に変化しました。
MCPとCLIの比較：実行チェーンの比較
複雑なワークフローの典型的な実行チェーンを比較してみましょう。
MCPルート（ツール接続に適している）
MCPセッションの初期化
↓
ツールリスト + ツール説明のロード
↓
Agentがツールを選択
↓
さらなるツールを検索 (listOpenApiEndpoints)
↓
スキーマを取得 (getOpenApiDetails)
↓
HTTP呼び出しを実行 (executeOpenApi)MCPの強み： ツールをAgentに接続するための標準化されたプロトコル。
複雑性の配置： ほとんどの複雑性はモデルコンテキストとツール選択段階にあります。Agentは以下を理解する必要があります：
- ツールリスト
- ツール説明
- 入力スキーマ
- 呼び出しシーケンス
- 戻り構造
うまく機能する場所： 明確なツールとタスクのマッピングを持つシンプルな操作。
課題となる場所： Agentが複数のツールをオーケストレーションし、製品のセマンティクスを理解し、検証を処理する必要がある複雑なワークフロー。
CLI + SKILLルート（複雑なワークフローに適している）
SKILLがタスクタイプを判断
↓
CLIが製品セマンティックなコマンドを実行
↓
cli-schemaが構造を検証
↓
agentHintsが次のステップの提案を行う
↓
検証ループ（読み戻しまたはapidog runの取得）CLI + SKILLの強み： 複雑性をエンジニアリングシステムに分散させます。
複雑性の配置：
- SKILL：方法論とワークフローガイダンス
- CLI：製品セマンティックな実行
- cli-schema：書き込み前の検証
- agentHints：実行後のナビゲーション
うまく機能する場所： 多段階ワークフロー、検証重視の操作、Agent駆動テスト。
重要な違い：複雑性がどこに存在するのか
これら2つのアプローチの違いは、複雑性がどこに配置されるかです。
| アプローチ | 複雑性が存在する場所 | 最適な用途 |
|---|---|---|
| MCP | モデルコンテキスト + ツール選択段階 | シンプルなツール呼び出し、MCPエコシステム |
| CLI + SKILL | エンジニアリングシステム（SKILL、CLI、検証、ヒント） | 複雑なワークフロー、多段階操作 |
MCPでは、モデルが以下を保持する必要があります：
- どのツールを使用するか
- ツールの説明が何を言っているか
- どのフィールドが必要か
- どのシーケンスに従うか
- 戻り構造が何を意味するか
これは、タスクとツールのマッピングが単純な場合に機能します。
CLI + SKILLでは、エンジニアリングシステムが以下を保持します：
- これがどのタスクタイプであるか (SKILL)
- どのコマンドを実行するか (CLI)
- どの構造が有効か (cli-schema)
- 次何をすべきか (agentHints)
これは、ワークフローに検証ゲート、読み戻し要件、検証ループがある場合に、より効果的に機能します。
典型的なワークフローの例
CLI + SKILLワークフローの具体的な例を以下に示します：
# ステップ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これらの3つのコマンドは、3つのエンジニアリングアクションを表しています：
| コマンド | アクション |
|---|---|
endpoint get |
プロジェクトから事実を読み取る |
cli-schema validate |
書き込み前に構造を検証する |
apidog run |
検証を実行する |
複雑なワークフローのためのAgentパス
複雑な多段階ワークフローの場合、AgentのパスはCLI + SKILL構造から恩恵を受けます。
複雑なワークフローのためのMCPパス
「ツールを選択 → スキーマを理解 → シーケンスをオーケストレーション → エラーを処理」Agentは：
- 多くのオプションから適切なツールを選択する
- ツールの説明とスキーマを理解する
- 正しいシーケンスをオーケストレーションする
- リトライを通じてエラーを処理する
これは機能しますが、各決定点でモデルにかなりの推論を必要とします。
複雑なワークフローのためのCLI + SKILLパス
「事実を読み取る → 変更を生成 → 構造を検証 → 書き込み → 検証を実行」Agentは：
- まず既存の事実を読み取る (SKILLによって誘導される)
- 事実に基づいて変更を生成する
- 構造をローカルで検証する (cli-schema)
- プロジェクトに書き込む
- 検証を実行する (agentHintsが次のステップをガイドする)
エンジニアリングシステムが検証、ガイダンス、検証を処理することで、モデルの推論負担が軽減されます。
どちらのパスもタスクを完了できます。CLI + SKILLは、モデルコンテキスト段階の複雑さを軽減します。
CLIが現在カバーしているもの
アップグレードにより、CLIはより多くのコアApidogリソースをカバーするようになりました：
| リソース | CLI機能 |
|---|---|
| プロジェクトとメタデータ | リスト表示、読み取り |
| APIとAPI定義 | 取得、作成、更新 |
| 環境と変数 | リスト表示、管理 |
| テストケース | 作成、更新、検証 |
| テストシナリオ | 作成、更新、ステップのインポート、詳細付きで取得 |
| テストスイート | 管理 |
| レポート | apidog runから生成 |
| インポート/エクスポート | プロジェクトのエクスポート、ファイルのインポート |
これにより、Apidog CLIの役割が変わります。
それは単に他のすべてが完了した後にテストを実行する方法ではありません。
Agentが以下を必要とする開発ループの早い段階で参加できるようになりました：
- プロジェクトを理解する
- テストアセットを生成または更新する
- 変更を検証する
- 検証を実行する
アーキテクチャの概要
| 側面 | MCP | CLI + SKILL |
|---|---|---|
| 主な強み | ツール接続 | ワークフロー実行 |
| 複雑性の配置 | モデルコンテキスト | エンジニアリングシステム |
| 複雑なタスクのAgentパス | 選択、オーケストレーション、リトライ | 読み取り、検証、書き込み、検証 |
| カバレッジ | 126の生成されたツール + ネイティブツール | 完全なリソース管理 + 検証 |
| 最適な用途 | シンプルな操作、MCPエコシステム | 複雑なワークフロー、CI/CD |
両方とも利用可能です。タスクに基づいて選択してください。
次は何ですか
CLI + SKILLがMCPをどのように補完するかを確立したところで、次の疑問は：
CLI + SKILLが複雑なワークフローで効果的である核となる原則は何ですか？
パート3、「黄金律：CLIは事実を生成し、モデルは事実に従って行動する」では、失敗した書き込みになる前にエラーを捕捉する品質ゲートであるcli-schema validateから始まる、すべてのCLI + SKILLの決定を導く設計哲学を探求します。
主要なポイント
- MCPは引き続き機能します — シンプルな操作やMCPエコシステム統合に利用してください
- CLI + SKILLはMCPを補完します — 検証を伴う複雑なワークフローにより適しています
- 重要な違いは複雑性がどこにあるかです：モデルコンテキスト vs. エンジニアリングシステム
- CLI + SKILLは、検証、ガイダンス、検証を通じてモデルの推論負担を軽減します
- CLIは現在、プロジェクト、API、環境、テストケース、シナリオなどをカバーしています
- 両方のアプローチが利用可能です — タスクの複雑性に基づいて選択してください
Apidogをダウンロードして、APIを1つのワークスペースで設計、モック、テスト、ドキュメント化しましょう。コマンドラインAPIテスト、CI自動化、AI AgentワークフローのためのApidog CLIについてさらに詳しく学ぶ。