これは、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へようこそ。 | ビジョンと未来 |
126個のMCPツールを構築しましたが、AgentとのAPI開発作業においてそれが最善の解決策ではないとわかりました。
2025年初頭にMCP（Model Context Protocol）が業界のホットスポットになったとき、すべてのAPI製品が直面した質問は単純でした：「MCPを持っていますか？」
Apidogの場合、私たちは「はい」と答えました。私たちは単なるデモではなく、完全なMCPサーバーを構築しました。MCPクライアントがセッションを初期化し、サーバーがsessionIdを生成し、Redisを介してセッションの状態を保存しました。それはプロトコルレベルのセッションシステムでした。ツールは、ネイティブプロジェクトツール、組み込みドメインツール、OpenAPIエンドポイント定義から自動的に変換された126個の生成ツールに分類しました。
Apidog MCPは、MCP統合を必要とするユーザーに引き続き機能し、サービスを提供しています。これは、MCPプロトコルに従った標準化されたツール接続を提供し、エコシステムにとって価値のあるものです。
しかし、複雑なR&Dワークフローを伴う実際のタスクに着手すると、限界を発見しました。ユーザーが「このエンドポイントのテストを追加して検証を実行してほしい」と言うと、Agentはどのツールをどの順序で、どのような検証と合わせて使用するかを決定する際に、ランダムなツールの壁に直面します。
私たちは気づきました：MCPはツール接続に優れていますが、複雑なR&Dタスクにはツール接続以上のもの、つまり実行可能なエンジニアリングプロセスが必要です。
この洞察が、開発ワークフローをより適切に処理するためのより良いアプローチとしてApidog CLIを開発するきっかけとなりました。
Apidog CLIとは？
Apidog CLIは、APIテスト用のコマンドラインツールで、ターミナルやCI/CDパイプラインから直接テストシナリオを実行したり、APIドキュメントを管理したり、テストワークフローを自動化したりできます。AI AgentがAPIリソースを管理するために特別に構築されており、従来のAPIテスト用CLIを超え、Agentが複雑なワークフローを安全に実行するために必要な構造化された出力、スキーマ検証、次のステップのガイダンスを提供します。GitHub Actionsで自動APIテストを実行している場合でも、Claude Codeでコードからテストケースを生成している場合でも、プロジェクト間でテストシナリオを維持している場合でも、Apidog CLIはAI AgentとAPIテストインフラストラクチャ間の橋渡し役となります。
クイックスタート：Apidog CLI + SKILLを試す
このシリーズで説明されているアプローチを試したい場合は、次の手順で開始してください。
# Apidog CLIをインストール
npm install -g apidog-cli@latest
# AI Agent用コンパニオンSKILLをインストール
apidog skill install
# バージョンを確認（新機能には2.2.5+が必要）
apidog -v
# 認証
または、AI Agentにインストールを依頼することもできます。
手順を読んで、Apidog CLIのインストールを手伝ってください。
最初のAgentタスク
インストール後、Agentに小さくてリスクの低いタスクを与えてください。
Apidog CLIを使用して、Apidogで最初のAPIエンドポイントを作成するのを手伝ってください。
まず、Apidog CLIの設定を確認し、アクセスできるプロジェクトを一覧表示してください。
どのプロジェクトを使用するか尋ねてください。確認後、200レスポンスの例を含む
Health Checkという名前のシンプルなGET /healthエンドポイントを作成してください。
書き込む前に構造化された入力を検証し、その後エンドポイントを読み戻して要約してください。
これにより、具体的な開始点が得られます。Agentは設定を確認し、書き込む前に尋ね、小さなAPI定義を作成し、書き込む前に検証し、保存された結果を確認します。
コアアーキテクチャ
| レイヤー | 責務 |
|---|---|
| Apidog | APIおよびテスト資産（ドキュメント、スキーマ、モック、テスト、レポート）を管理 |
| CLI | 決定的な実行（読み取り、検証、書き込み、実行）を提供 |
| SKILL | タスク判断と操作パス（8つのコンパニオンSkill）を提供 |
| AI Branch | マージ前に人間によるレビューのために変更を隔離 |
| Agents | 目標を理解し、コマンドを呼び出し、フィードバックに基づいて調整 |
Agent駆動型テストのためのより安全なループ
AI Branchを外部の安全層として、完全なワークフローは次のようになります。
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (安全層) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ アセットを読み込み│────▶│ 生成 │────▶│ 検証 │ │
│ │ (CLI get) │ │ (Agent) │ │ (cli-schema)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ テストを実行 │◀────│ 読み戻し │◀────│ 書き込み │ │
│ │ (apidog run)│ │ (CLI get) │ │ (AI Br.へ) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ 人間によるレビューとマージ │ │
│ │ (メインブランチへのマージ前にユーザーが確認) │ │
│ └──────────────────────────────────────┘ │
このループは重要です。なぜなら、多くのApidogリソースは構造化されているからです。テストケースとテストシナリオには、リクエストデータ、アサーション、変数抽出、プリ/ポストプロセッサ、ステップ順序、環境参照が含まれます。Agentが構造を推測すると、小さな間違いが書き込みの失敗、不完全な表示、または期待どおりに動作しないテストを引き起こします。
Agentに生成させ、CLIに検証させ、AI Branchに変更を隔離させて人間がレビューするまで待ちましょう。
Apidog CLIジャーニーの概要
このシリーズでは、API R&Dワークフローのためのより良い戦略としてApidog CLIをどのように開発したかを記録しています。
Apidog MCPは引き続き標準化されたツール接続を提供しており、これは価値があるため維持しています。しかし、多段階ワークフロー、検証ゲート、構造化された実行を伴うタスクには、CLI + SKILLがより良い体験を提供することを発見しました。
私たちは古いCLIにコマンドを追加しただけではありませんでした。そこでは、ユーザーがCI/CDと統合して自動APIテストを実行していました。私たちはApidogのコア機能をCLIに体系的に導入し、開発者、スクリプト、AI Agentのためのワークフロー層にしました。
主な違いは、複雑さがどこにあるかです。
- MCPルート： モデルのコンテキストとツール選択段階に複雑さが集中—シンプルなツール呼び出しに最適
- CLI + SKILLルート： 複雑さがエンジニアリングシステムに分散—より高度なワークフローに最適
その結果、複雑なタスクのためのより安全なAgentワークフロー、より少ないツール呼び出し、より少ないトークンの無駄、より良いエラーリカバリが実現しました。一方で、MCPはアプローチを好むユーザーのために引き続き利用可能です。
Apidog CLIジャーニーマップ
┌─────────────────────────────────────────────────────────────────┐
│ APIDOG CLI + SKILLの旅 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [問題発見] │
│ │ │
│ ┌───┐ │
│ │ 1 │ 126個のMCPツールを構築したが、 │
│ └───┘ ワークフローのためのより良いアプローチを見つけた。 │
│ │ │
│ ▼ │
│ [アーキテクチャ開発] │
│ ┌───┐ │
│ │ 2 │ なぜApidog CLIを新たに開発したのか │
│ └───┘ │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ [核となる哲学] [技術設計] │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ 3 │ CLIは事実を生成│ 4 │ agentHints: │ 5 │ SKILL: 運用経験を │
│ └───┘ └───┘ CLIに └───┘ コードとして │
│ │ │ 対話させる │ 出荷する │
│ │ │ │ │
│ └──────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ [検証と実践] │
│ ┌───┐ ┌───┐ │
│ │ 6 │───────│ 7 │ │
│ └───┘ 数字が │ PRDからテストループまで │
│ │ 語る │ │
│ ▼ ▼ │
│ [基盤] [セキュリティ層] │
│ ┌───┐ ┌───┐ │
│ │ 8 │───────│ 9 │ │
│ └───┘ CI/CD │ AI Branch │
│ │ │ │
│ └────────┘ │
│ │ │
│ ▼ │
│ [ビジョン] │
│ ┌────┐ │
│ │ 10 │ Spec-First → Skill-First │
│ └────┘ │
│ │
クイックジャーニーナビゲーション
パート1：問題発見
126個のMCPツールを構築したが、その後AI Agentを使ったAPI開発ワークフローのより良いアプローチを見つけた。
MCPは標準化されたツール接続を提供しますが、複雑なR&Dワークフローでは限界があることを発見しました。タスクが多段階プロセスを伴う場合、Agentはランダムなツールの壁に直面しました。この投稿では、4つの構造的課題と、なぜCLI + SKILLがワークフロー重視のタスクに適しているかを探ります。
パート2：アーキテクチャ開発
MCPを放棄したわけではありません。MCPが最適化しないもの、つまり検証ゲートと構造化された実行を伴う複雑なワークフローを処理するためにCLI + SKILLを構築しました。この投稿では、実行チェーンを比較し、CLI + SKILLが複雑さをエンジニアリングシステムに分散させる一方で、MCPがその目的を果たし続ける方法を説明します。
パート3：核となる哲学
3. 黄金律：CLIは事実を生成し、モデルは事実に従って行動する
核となる原則は、モデルにすべてのルールを記憶させないことです。ルールを適切な場所で実行させます。この投稿では、`cli-schema validate`を紹介します。これは、フィールドエラー、間違った列挙型、構造的な問題が書き込みの失敗になる前に捕捉する品質ゲートです。
パート4-5：技術設計
4. agentHints: CLIにAgentと対話させる
従来のCLI出力は人間向けです。Agentには構造化された結果、失敗の理由、次のステップの提案が必要です。`agentHints`は製品の経験を機械が読み取れるガイダンスに変換し、Agentが意思決定する必要があるまさにその場所に表示されます。
SKILLは単なるコマンドリファレンスではありません。それはAI Agentのための運用ガイドです。いつコマンドを使用するか、何が最初に来るか、どのフィールドを推測すべきでないか、いつ検証するか、いつ読み戻すか。SKILLはワークフローの知識をバージョン管理可能で進化可能なガイドとしてパッケージ化します。
パート6-7：検証と実践
6. 数字は嘘をつかない：ツール呼び出し30%減、トークン25%減
一般的なタスクでMCPとCLI + SKILLを比較しました。ツール呼び出しステップは約30%減少しました。無効な説明や再試行によるトークン消費は約25%減少しました。構造エラーの再試行は約40%減少しました。この投稿では、どこからこの節約が来るのかを分析します。
7. PRDからテストループまで：Apidog CLIを使ったAgentの完全なワークフロー
実際の例を見てみましょう。チームは注文返金PRDとコードベースを持っています。AgentがCLI + SKILLを使用してOpenAPIを生成し、テストケースを作成し、構造を検証し、テストシナリオを構築し、検証を実行するエンドツーエンドのプロセスをご覧ください。
パート8-9：基盤とセキュリティ
8. AgentツールにとってCI/CD互換性が不可欠である理由
Agentの使いやすさはCI/CDの使いやすさの上に構築されなければなりません。`apidog run`は両方に役立ちます。CIは終了コード、レポートファイル、安定したパラメータを重視します。Agentは構造化された結果、失敗の理由、次のステップの提案を重視します。1つのコマンドで複数のコンシューマに対応します。
9. AIブランチ：AI Agentによるより安全なプロジェクト変更
Agentがプロジェクトリソースを変更する場合、安全性は重要です。AI Branchは分離された編集を提供し、人間によるレビューがあるまで変更は別のブランチに留まります。これにより、自動化された変更がメインブランチに直接影響を与えるのを防ぎます。作成、レビュー、そして自信を持ってマージできます。
パート10：ビジョンと未来
10. Spec-Firstは昨日。Skill-Firstへようこそ。
API開発は、AI Agentがワークフローに参加することで変化しています。Spec-Firstは人間によるコラボレーションのためでした。Skill-Firstは、仕様、テスト、シナリオを実行可能で検証可能なスキルとしてパッケージ化し、Agent時代 existing approaches を補完します。この投稿では、未来の概要と具体的な開始手順を提供します。
重要なポイント (TL;DR)
| 洞察 | 意味するもの |
|---|---|
| MCPとCLI + SKILLは異なるニーズに対応する | MCPはツールを接続し、CLI + SKILLはワークフローを実行する—タスクに合ったものを使用する |
| 複雑さはコンテキストではなくエンジニアリングに属する | 複雑なワークフローの場合、126個のツール × 500トークン = 50,000トークンの負担 |
| `cli-schema validate`が品質ゲートである | 書き込み失敗ではなく、ローカルでエラーを捕捉する |
| `agentHints`が次のステップをガイドする | Agentが「想像」に基づいて書き込むのを防ぐ |
| SKILLは運用経験をパッケージ化する | 単なるコマンドではなく—Agentのためのワークフローの知恵 |
| CI/CDは基盤であり続ける | Agent機能はCIを置き換えるのではなく、その上に構築される |
| AI Branchは安全層を提供する | マージ前に分離された編集 + 人間によるレビュー |
読み始める
すぐに読みたいですか？パート1：126個のMCPツールを構築したが、その後ワークフローのためのより良いアプローチを見つけた。から始めてください。
Apidogをダウンロードして、APIの設計、モック、テスト、ドキュメント化を単一のワークスペースで行いましょう。 コマンドラインAPIテスト、CI自動化、AI Agentワークフローについては、Apidog CLIの詳細をご覧ください。