これは、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 | AgentツールにとってCI/CD互換性が不可欠である理由 | 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は、どのツールをどの順序で呼び出すべきか、どの検証を挟むべきか、どの結果を読み戻すべきかを判断する必要があります。126個のツールがあると、Agentは「使えるツールの一覧」ではなく「ランダムなツールの壁」に直面します。
そこで私たちは次の結論に至りました。
MCPはツール接続に優れています。しかし、複雑なR&Dタスクには、ツール接続だけでなく、実行可能なエンジニアリングプロセスが必要です。
この洞察が、Apidog CLIを開発するきっかけになりました。
Apidog CLIとは？
Apidog CLIは、APIテスト用のコマンドラインツールです。ターミナルやCI/CDパイプラインから、テストシナリオの実行、APIドキュメントの管理、テストワークフローの自動化を行えます。
特にAI AgentがAPIリソースを扱う場面を想定し、従来のAPIテストCLIに加えて、次の要素を提供します。
- 構造化された出力
- スキーマ検証
- 次に実行すべきステップのガイダンス
- Agentが安全にワークフローを進めるための実行パターン
たとえば次のようなユースケースで、Apidog CLIはAI AgentとAPIテスト基盤の橋渡しになります。
- GitHub Actionsで自動APIテストを実行する
- Claude CodeなどのAgentにコードからテストケースを生成させる
- プロジェクト間でテストシナリオを保守する
- API仕様、テストケース、テストシナリオを読み書きしながら検証する
クイックスタート：Apidog CLI + SKILLを試す
まずCLIとAI Agent向けの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タスク
インストール後は、いきなり大きな変更を任せるのではなく、小さくリスクの低いタスクから始めます。
Apidog CLIを使用して、Apidogで最初のAPIエンドポイントを作成するのを手伝ってください。
まず、Apidog CLIの設定を確認し、アクセスできるプロジェクトを一覧表示してください。
どのプロジェクトを使用するか尋ねてください。
確認後、200レスポンスの例を含む
Health Checkという名前のシンプルなGET /healthエンドポイントを作成してください。
書き込む前に構造化された入力を検証し、
その後エンドポイントを読み戻して要約してください。
この指示では、Agentに次のループを実行させます。
- 設定を確認する
- 利用可能なプロジェクトを一覧する
- 書き込み前にユーザーへ確認する
- 小さなAPI定義を生成する
- 書き込み前に構造を検証する
- 保存後に読み戻して確認する
ポイントは、Agentにいきなり書き込ませないことです。生成 → 検証 → 書き込み → 読み戻し の順序を守ることで、失敗を早期に検出できます。
コアアーキテクチャ
| レイヤー | 責務 |
|---|---|
| Apidog | APIおよびテスト資産（ドキュメント、スキーマ、モック、テスト、レポート）を管理 |
| CLI | 決定的な実行（読み取り、検証、書き込み、実行）を提供 |
| SKILL | タスク判断と操作パス（8つのコンパニオンSkill）を提供 |
| AI Branch | マージ前に人間がレビューできるよう、変更を隔離 |
| Agents | 目標を理解し、コマンドを呼び出し、フィードバックに基づいて調整 |
Agent駆動型テストのための安全なループ
AI Branchを安全層として使う場合、ワークフローは次のようになります。
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (安全層) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ アセットを読む │────▶│ 生成 │────▶│ 検証 │ │
│ │ (CLI get) │ │ (Agent) │ │ (cli-schema) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ テストを実行 │◀────│ 読み戻し │◀────│ 書き込み │ │
│ │ (apidog run) │ │ (CLI get) │ │ (AI Branch) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ 人間によるレビューとマージ │ │
│ │ メインブランチへのマージ前に確認する │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
このループが重要なのは、Apidogの多くのリソースが構造化されているためです。
テストケースやテストシナリオには、たとえば次の要素が含まれます。
- リクエストデータ
- アサーション
- 変数抽出
- プリプロセッサ / ポストプロセッサ
- ステップ順序
- 環境参照
Agentがこれらの構造を推測だけで生成すると、小さなミスが次の問題につながります。
- 書き込み失敗
- UI上で不完全に表示される
- テストが期待どおりに動かない
- 再試行によってトークンと時間を消費する
そのため、基本ルールは次のとおりです。
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が複雑さをエンジニアリングシステムに分散させる方法を説明します。
パート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の両方に役立ちます。
- CIは終了コード、レポートファイル、安定したパラメータを重視する
- Agentは構造化された結果、失敗理由、次のステップの提案を重視する
1つのコマンドで複数のコンシューマに対応できます。
9. AIブランチ：AI Agentによるより安全なプロジェクト変更
Agentがプロジェクトリソースを変更する場合、安全性が重要です。
AI Branchは分離された編集環境を提供します。人間によるレビューが完了するまで、変更は別ブランチに留まります。これにより、自動化された変更がメインブランチに直接影響を与えることを防ぎます。
パート10：ビジョンと未来
10. Spec-Firstは昨日。Skill-Firstへようこそ。
API開発は、AI Agentがワークフローに参加することで変化しています。
Spec-Firstは人間同士のコラボレーションを支える考え方でした。Skill-Firstは、仕様、テスト、シナリオを実行可能で検証可能なスキルとしてパッケージ化し、Agent時代の既存アプローチを補完します。この投稿では、未来像と具体的な開始手順を説明します。
重要なポイント（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の詳細をご覧ください。
Top comments (0)