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 | AgentツールにとってCI/CD互換性が不可欠である理由 | DevOpsの視点 |
| 9 | AIブランチ：AI Agentによる安全なプロジェクト変更 | セキュリティ層 |
| 10 | 仕様先行は過去のもの。スキル先行へようこそ。 | ビジョンと未来 |
モデルにすべてのルールを記憶させないでください。ルールは適切な場所で実行されるべきです。cli-schema validateは、スキーマを「知識」から「品質ゲート」へ変えます。
核となる原則：ルールは適切な場所で実行する
Agentにすべての仕様ルールを覚えさせるのではなく、決定論的に判定できるルールはCLIで実行します。
モデルにすべてのルールを記憶させないでください。ルールは適切な場所で実行されるべきです。
Agentの責務とCLIの責務は分けます。
| 指標タイプ | 属する場所 |
|---|---|
| 決定論的指標 | スクリプト、コード、自動チェック |
| 意味的判断 | LLM、モデル推論 |
Apidog CLI + SKILLでは、次のように分担します。
| 内容 | 場所 |
|---|---|
| 決定論的構造検証 | CLI（cli-schema） |
| タスクの判断と生成 | Agent |
実装上のポイントはシンプルです。
CLIで構造を検証し、Agentでコンテンツを生成します。
なぜモデルの記憶に頼ると危険なのか
AI AgentがApidogリソースの作成や更新を支援する場合、リスクは文章生成そのものだけではありません。
リスクが高いのは、十分な構造検証なしに生成結果を実プロジェクトへ書き込むことです。
Apidogリソースは構造化されています。たとえばテストケースやテストシナリオには、以下のような要素があります。
| コンポーネント | 複雑さ |
|---|---|
| リクエストデータ | メソッド、URL、ヘッダー、ボディ、認証 |
| アサーション | 比較演算子、対象、ターゲット値、条件 |
| 変数抽出 | 変数名、型、抽出パス |
| プリプロセッサ | リクエスト前のスクリプト |
| ポストプロセッサ | レスポンス後のスクリプト |
| ステップ順序 | シーケンス、依存関係 |
| 環境参照 | 環境ID、変数オーバーライド |
Agentがこれらの構造を推測すると、次のような問題が起きます。
- フィールド名の間違い → 書き込み失敗
- 無効な列挙値 → サーバー拒否
- 必須フィールドの欠落 → 不完全なリソース
- 型の間違い → UI表示の問題
- 不適切なネスト → テストが期待通りに動作しない
cli-schema validate: 書き込み前の品質ゲート
この問題に対する直接的な対策が、cli-schema validateです。
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
AgentがテストシナリオやテストケースのJSONを生成したら、APIへ書き込む前にローカルで検証します。
validateコマンドは、主に以下を確認します。
- フィールド名が正しいか
- 構造が有効か
- 列挙値が有効か
- 型制約を満たしているか
重要なのは、これらをすべて書き込みリクエストの前に実行することです。
cli-schemaが検出する典型的なエラー
Agentが生成しやすいエラーにはパターンがあります。
| 誤った値 | 正しい値 | コンテキスト |
|---|---|---|
global |
globals |
変数スコープタイプ |
contains |
include |
アサーション比較演算子 |
responseBody |
responseJson |
レスポンスボディ対象 |
"500"（文字列） |
500（数値） |
ミリ秒単位の遅延 |
equals |
equal |
アサーション比較演算子 |
header |
headers |
リクエストヘッダーフィールド |
これらは理論上の例ではありません。実際のAgentとのインタラクションから見つかったエラーです。
この種のエラーをAPI書き込み時に初めて検出すると、次のような無駄が発生します。
- 書き込みリクエストの失敗
- APIエラー応答の解析
- Agentの誤った修正
- 複数回の再試行
- 不要なトークン消費
cli-schema validateを使うと、これらのエラーをネットワーク呼び出しの前にローカルで検出できます。
実装方針：プロンプトではなくローカル検証に寄せる
代替案1：プロンプトにすべてのルールを書く
すべてのフィールドルールをAgentのプロンプトに入れると、次のようになります。
- すべてのフィールド名を文書化する
- すべての列挙値を列挙する
- すべての型制約を説明する
- すべてのネスト構造を記述する
結果：コンテキスト負荷が大きすぎます。
包括的なテストシナリオのスキーマは、簡単に5,000トークン以上の説明になる可能性があります。しかも多くのタスクでは、その大半のルールは使われません。
代替案2：モデルの記憶に頼る
モデルが正しい構造を「知っている」ことに期待する方法もあります。
しかし実際には、以下の制約があります。
- モデルは一般的なAPIパターンを学習している
- しかしApidog固有のスキーマに最適化されているとは限らない
- フィールド名は製品ごとに異なる
- 列挙値も製品固有である
結果：エラー率が高くなります。
モデルはApidog固有の慣習を完全には記憶していません。推測はできますが、その推測はしばしば間違います。
推奨アプローチ：Agentに生成させ、CLIで検証する
実装フローは次のようにします。
# 1. AgentがJSONを生成する
# Agentはすべてのルールを記憶する必要はない
# 2. CLIが構造を検証する
apidog cli-schema validate test-case-create --file ./test-case-create.json
# 3. エラーがあればCLIが具体的に出力する
# Agentはエラー内容に基づいてJSONを修正する
# 4. 検証済みのJSONだけを書き込む
apidog test-case create --project <projectId> --file ./test-case-create.json
この流れにすると、Agentは「仕様を暗記する」のではなく、「検証結果を読んで修正する」ワークフローに移行できます。
スキーマの役割を変える
cli-schema validateは、スキーマの扱い方を変えます。
| 前 | 後 |
|---|---|
| スキーマ = モデルが記憶すべき知識 | スキーマ = 通過しなければならない品質ゲート |
| 書き込み失敗によってエラーを発見 | ローカル検証によってエラーを発見 |
| ネットワーク呼び出しで再試行 | ローカル修正で再試行 |
| コンテキストの負担 | 実行ゲート |
ポイントは次の2つです。
- 問題をネットワーク往復で消費しない
- 品質チェックをローカルコマンドで完了させる
実践ワークフロー
実際のAgentワークフローでは、以下のように組み込みます。
# Agentがエンドポイント情報を取得する
apidog endpoint get <endpointId> --project <projectId>
# AgentがテストケースJSONを生成する
# ./test-case-create.json を作成する
# 書き込み前に検証する
apidog cli-schema validate test-case-create --file ./test-case-create.json
検証が通った場合だけ、作成コマンドを実行します。
apidog test-case create --project <projectId> --file ./test-case-create.json
検証に失敗した場合、CLIは具体的なエラーを返します。
エラー: フィールド "assertions[0].comparator" に無効な値 "contains" があります
有効な値: equal, not_equal, greater, less, include, not_include, exists, not_exists
エラー: フィールド "extractors[0].type" に無効な値 "global" があります
有効な値: globals, environment, collection, local
提案: これらのフィールドを修正し、書き込み前に再検証してください。
Agentはこの出力を使って、次のループを実行します。
- エラー内容を読む
- 問題のフィールドを特定する
- JSONファイルを修正する
-
cli-schema validateを再実行する - 検証が通った場合のみ書き込む
このループにより、書き込み失敗、曖昧な再試行、不要なトークン消費を減らせます。
より広範な設計ルール
この考え方はスキーマ検証だけに限りません。
| ルールタイプ | 属する場所 |
|---|---|
| フィールド名ルール | cli-schema |
| 列挙値ルール | cli-schema |
| 型制約 | cli-schema |
| ワークフローシーケンス | SKILL |
| 次ステップガイダンス | agentHints |
| タスク分解 | Agent |
判断基準は明確です。
決定論的ルール → エンジニアリングシステム
意味的判断 → Agent
Agentにすべてを任せるのではなく、決定論的に検証できるものはCLIやスクリプトへ移すべきです。
次は何ですか
検証の原則が確立されると、次の疑問が出てきます。
検証後、CLIはどのようにAgentを次のステップへ導くのか？
第4部、agentHints: CLIにAgentとの対話を教えるでは、次ステップの提案を含む構造化出力が、CLIを単なるコマンド実行者からワークフローナビゲーターへ変える方法を説明します。
重要なポイント
- ルールはコンテキストではなく、実行可能な検証として配置する
-
cli-schema validateは書き込み前の品質ゲートである - よくあるエラーは、誤ったフィールド名、無効な列挙値、誤った型
- ローカル検証により、ネットワーク往復と再試行を減らせる
- スキーマは「記憶すべき知識」ではなく「通過すべきゲート」になる
- 決定論的ルールはエンジニアリングへ、意味的判断はAgentへ任せる
Apidogをダウンロードして、APIの設計、モック、テスト、ドキュメント化を1つのワークスペースで行いましょう。コマンドラインAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細をご覧ください。
Top comments (0)