黄金律：CLIは事実を生成し、モデルは事実に基づいて動作する

ApidogがAPIテストとAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをどのように開発したかを紹介する10部構成のシリーズです。順番に読むか、興味のある記事に直接ジャンプしてください。

モデルにすべてのルールを記憶させないでください。ルールは適切な場所で実行されるべきです。cli-schema validateは、スキーマを知識から品質ゲートへと変えます。

核となる原則：ルールは適切な場所で実行されるべきである。

私たちは経験から一つの核となる原則を導き出しました。

モデルにすべてのルールを記憶させないでください。ルールは適切な場所で実行されるべきです。

これはAgentの評価から得られた教訓に似ています。

Apidog CLI + SKILLでは：

CLIで構造を検証し、Agentでコンテンツを生成します。

モデルの記憶に関する問題

AI AgentがApidogリソースの作成や更新を支援する際、リスクのある部分はコンテンツの生成だけではありません。

リスクのある部分は、十分な構造や検証なしに生成されたコンテンツを実際のプロジェクトに書き込むことです。

Apidogリソースは構造化されています。テストケースやテストシナリオが何を含むかを考えてみてください。

Agentが構造を推測した場合：

• フィールド名の間違い → 書き込み失敗
• 無効な列挙値 → サーバー拒否
• 必須フィールドの欠落 → 不完全なリソース
• 型の間違い → UI表示の問題
• 不適切なネスト → テストが期待通りに動作しない

cli-schema validate: 品質ゲート

私たちの原則を最も直接的に体現しているのがcli-schema validateです。

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Agentがテストシナリオを書き込んだり更新したりする際、AIに複雑なステップ構造を生成させると、非常にエラーが発生しやすくなります。

validateコマンドは以下のことを行います：

• フィールド名を確認する
• 構造の有効性をチェックする
• 列挙値の有効性を検証する
• 型制約を検証する

これらはすべて、書き込みリクエストを開始する前に行われます。

cli-schemaが検出する一般的なエラー

Agentが一般的に犯し、cli-schema validateが検出するエラーの実際の例を以下に示します。

これらは理論上の話ではありません。実際のAgentとのインタラクションを通じて発見しました。

各エラーは以下を引き起こすでしょう：

• 書き込みリクエストの失敗
• APIエラー応答
• Agentが何が問題だったか混乱する
• 複数回の再試行
• 繰り返し呼び出しによるトークンの浪費

cli-schema validateを使用すると、これらのエラーはネットワーク呼び出しの前にローカルで検出されます。

設計思想

代替案を考えてみましょう。

代替案1：プロンプトにルールを書き込む

もし、すべてのフィールドルールをAgentのプロンプトに書き込んだ場合：

• すべてのフィールド名が文書化されている
• すべての列挙値がリストされている
• すべての型制約が説明されている
• すべてのネストされた構造が記述されている

結果：途方もないコンテキストの負荷。

包括的なテストシナリオのスキーマは、容易に5,000トークン以上の説明を必要とする可能性があります。これは、ほとんどのルールが関連しない場合でも、モデルがすべてのタスクで保持しなければならないコンテキストとなります。

代替案2：モデルの記憶に頼る

もし、モデルが正しい構造を「知っている」ことに頼る場合：

• 一部のAPIパターンでトレーニングされたモデル
• しかし、Apidogのスキーマには特化していない
• フィールド名は製品によって異なる
• 列挙値は製品固有である

結果：高いエラー率。

モデルはApidog固有の慣習を完全に記憶しているわけではありません。推測するでしょうが、その推測は間違っているでしょう。

より良いアプローチ：ローカルで検証する

Agentにドラフトを生成させ、CLIで書き込み前に検証を実行させます。

# AgentがJSONを生成する
# (Agentはすべてのルールを記憶する必要はない)

# CLIが検証する
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLIがエラーがあれば特定のものを出力する
# Agentがエラーに基づいて調整する

# 有効な書き込みのみが進行する
apidog test-case create --project <projectId> --file ./test-case-create.json

スキーマの変革

cli-schema validateはスキーマの意味を変革します。

問題は無意味なネットワーク要求の往復で消費されません。

品質チェックはローカルコマンドを通じて完了します。

実践例

実際のワークフローを見てみましょう。

# 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

検証が失敗した場合：

エラー: フィールド "assertions[0].comparator" に無効な値 "contains" があります
有効な値: equal, not_equal, greater, less, include, not_include, exists, not_exists

エラー: フィールド "extractors[0].type" に無効な値 "global" があります
有効な値: globals, environment, collection, local

提案: これらのフィールドを修正し、書き込み前に再検証してください。

Agentは：

1. 特定のエラーを読み取る
2. 何が問題なのかを正確に理解する
3. JSONファイルを調整する
4. 検証を再実行する
5. 有効な場合にのみ処理を進める

書き込み失敗なし。混乱した再試行なし。トークンの無駄なし。

より広範な教訓

この原則は検証にとどまりません。

決定論的ルール → エンジニアリングシステム

意味的判断 → Agent

次は何ですか

検証の原則が確立された今、次の疑問は：

検証後、CLIはどのようにAgentを次のステップへと導くのか？

第4部、agentHints: CLIにAgentとの対話を教えるでは、次ステップの提案を伴う構造化出力が、CLIをコマンド実行者からワークフローナビゲーターへとどのように変貌させるかを探ります。

重要なポイント

• 核となる原則：ルールはコンテキストではなく実行に属する
• cli-schema validateは書き込み前の品質ゲートである
• 一般的なエラー：誤ったフィールド名、無効な列挙型、誤った型
• 検証はエラーをローカルで検出し、ネットワークの往復を削減する
• スキーマは「記憶すべき知識」から「通過すべきゲート」へと変革する
• 決定論的ルール → エンジニアリング；意味的判断 → Agent

Apidogをダウンロードして、APIの設計、モック、テスト、ドキュメント化を1つのワークスペースで行いましょう。 コマンドラインAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細をご覧ください。