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へようこそ。 | ビジョンと未来 |
SKILLは単なるコマンドリファレンスではありません。AI Agentのための運用ガイドです。いつコマンドを使用するか、何が最初に来るか、どのフィールドを推測すべきでないか、いつ検証するか、いつ読み戻すか。
CLIだけでは不十分
CLIコマンドはAgentに実行能力を与えます。
しかし、判断力のない能力は問題を引き起こします。
| CLIの能力 | 判断力なしのリスク |
|---|---|
| テストケースを作成する | 間違ったプロジェクトに作成する |
| テストシナリオを更新する | 読み戻さずに更新する |
| ステップをインポートする | 既存の構造を確認せずにインポートする |
| テストを実行する | 変更を検証せずに実行する |
Agentはコマンド以上のものを必要とします。運用判断力が必要です。
SKILLとは？
SKILLとは、AI Agentのために書かれた運用ガイドです。
それは次のものとは異なります。
- 簡単なコマンドリスト
- リファレンスマニュアル
- ヘルプページ
それは次のものです。
| SKILLの内容 | 目的 |
|---|---|
| いつコマンドを使用するか | タスクタイプ → コマンドマッピング |
| どのコマンドが最初に来るか | シーケンスガイド |
| どのフィールドを推測すべきでないか | 安全境界 |
| いつ検証するか | 品質ゲートの配置 |
| いつ読み戻すか | 検証のタイミング |
| いつテストを実行するか | 確認ワークフロー |
SKILLはAgentに運用判断力を与えます。
インストール
SKILLはApidog CLIのコンパニオンです。
# AI AgentのためにSKILLをインストール
apidog skill installこれにより、Agentが以下を理解するのに役立つ8つのコンパニオンSKILLがインストールされます。
- CLIコマンドのセマンティクス
- リソース構造
- タスクワークフロー
- エラー処理
- 検証パターン
SKILLが重要な理由: 隠れたワークフロー
Agentは、タスクがどのようにビジネス横断的な実行フローに分解されるべきかをまだ知る必要があります。
この経験は以下のようにはできません。
- ツール説明に包括的に記述する（コンテキストを過剰に消費する）
- チャットコンテキストに散乱させる（セッション間で失われる）
- モデルが記憶する（製品固有であり、一般的な知識ではない）
隠れたワークフローと「ビジネス上の落とし穴」には明示的なガイダンスが必要です。
例: テストシナリオのメンテナンス
複雑なテストシナリオのメンテナンスを考えてみましょう。
誤ったアプローチ（Agentが最初から手書きする場合）:Agent: 「テストシナリオの構造を手動で作成します」 Agent: アサーション、エクストラクター、プロセッサーを含む完全なステップ配列を記述 結果: フィールドエラー、誤った比較演算子、必須フィールドの欠落 CLI: 書き込みを拒否するか、不完全なシナリオを作成する
正しいアプローチ（SKILLにエンコードされている場合）:
| ステップ | 理由 |
|---|---|
| 1. エンドポイントまたはテストケースから既存のステップをインポートする | 複雑な構造を手書きしない |
| 2. 完全な構造を読み戻す | 実際にインポートされたフォーマットを確認する |
| 3. ローカルで修正を加える | 正確なベースで作業する |
| 4. 更新前に検証する | ローカルでエラーを捕捉する |
| 5. シナリオを実行する | 動作を検証する |
SKILLは単に「test-scenario updateコマンドがある」とは言いません。
それはこう言います。
「複雑なシナリオは、最初から完全な構造を手書きするのには適していません。より安定したパスは、まず既存のエンドポイントまたはケースステップをインポートし、次に完全な構造を読み戻し、最後にローカルで修正を加えることです。」
SKILLガイダンスの背後にあるコマンド
SKILLがAgentに利用をガイドする実際のコマンドは以下の通りです。
# ステップ1: エンドポイントからステップをインポート
apidog test-scenario import-steps <scenarioId> --project <projectId> \
--source endpoint --ids <endpointIds> --sync manual
# ステップ2: 詳細をすべて含めて読み戻す
apidog test-scenario get <scenarioId> --project <projectId> \
--with-case-detail
# ステップ3: 特定の部分を更新（Agentが更新JSONを生成）
# ステップ4: 更新前に検証
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# ステップ5: 更新を実行
apidog test-scenario update <scenarioId> --project <projectId> \
--file ./scenario-update.json
# ステップ6: 検証を実行
apidog run --project <projectId> --test-scenario <scenarioId>SKILLはAgentにいつ各コマンドを使用すべきか、そしてなぜかを伝えます。
重要な洞察: get--with-case-detail
SKILLは次の点を強調します。
「get--with-case-detailを使用して、ステップ内のケースを想像するのではなく、実際の構造を取得してください。」これが重要な理由:
get--with-case-detailなし |
get--with-case-detailあり |
|---|---|
| ステップにはIDのみ表示される | ステップには完全なケース構造が表示される |
| Agentは内部フォーマットを知らない | Agentは実際のアサーション/エクストラクターフォーマットを見る |
| Agentはフィールド名を推測する | Agentは実際の例から作業する |
実際の構造を取得することで、想像に基づいた更新を防ぎます。
進化可能性: SKILLは変更可能
Apidog SKILLは、進化可能でバージョン管理可能な運用経験です。
これが重要な理由
| 課題 | SKILLの解決策 |
|---|---|
| CLIコマンドが変更される | SKILLはそれに合わせて更新できる |
| ユーザーはパーソナライズされたワークフローを持つ | SKILLはカスタマイズできる |
| 新しい製品機能 | SKILLは拡張できる |
| ワークフローの改善 | SKILLは洗練できる |
仕組み
AgentにはSKILLに対する書き込み権限が付与されます。
SKILLが遅れたり、使いにくくなったりした場合:
- Agentはそれを修正できる
- Agentは改善を提案できる
- SKILLは利用を通じて進化する
SKILLは固定されたドキュメントではありません。生きた運用コードです。
互換性レイヤー
私たちは実際のバグからこれを学びました:
発見された問題:
二次更新中に、一部のシナリオステップで外側のステップは正常に更新されたが、内部HTTPケースが正しく更新されなかった。
根本原因:
- 内部ケース更新マーカーには特別な処理が必要だった
- Agentはこれらのマーカーについて知らなかった
- 製品のセマンティクスには特定のフラグが必要だった
解決策:
- CLIに互換性ロジックを組み込む
- CLIが内部マーカーを自動的に処理する
- ユーザーとAgentは内部の詳細を知る必要がない
制約の意味はSKILLにレイヤー化されています。
SKILLはAgentに正しいコマンドを使用するように指示します。CLIはそれらのコマンドの背後にある製品のセマンティクスを処理します。Agentは内部マーカーを理解する必要はありません。
オンデマンドローディング
SKILLはcli-schemaと同じ原則に従います。
複雑さは実行とドキュメントによって吸収されるべきであり、モデルに完全に公開されるべきではありません。
| 代替案 | 問題 |
|---|---|
| すべてのSKILLをコンテキストにロードする | トークン負荷 |
すべてのルールを--helpに置く |
注意を競合させる |
| プロンプトに書き込む | 更新できない |
SKILLのアプローチ:
- AgentはSKILLをオンデマンドでウォームアップする
- タスクタイプが特定されたときにSKILLがロードされる
- 関連するワークフローガイダンスのみがコンテキストに入る
SKILL vs. ドキュメント
| ドキュメント | SKILL |
|---|---|
| 人間が読むため | Agentが実行するため |
| コマンドが何をするかを説明する | いつ使用するかを説明する |
| 静的なリファレンス | 動的なワークフロー |
| 包括的 | タスク指向 |
| Agentの外部にある | Agentと統合されている |
8つのコンパニオンSKILL
Apidogは8つのコンパニオンSKILLを提供します。
| SKILL | カバレッジ |
|---|---|
| プロジェクト管理 | プロジェクト、メタデータ、リソース |
| APIデザイン | エンドポイント、スキーマ、定義 |
| 環境管理 | 環境、変数 |
| テストケース作成 | 単一エンドポイントテスト、アサーション |
| テストシナリオ管理 | 複数ステップテスト、インポート、更新 |
| テストスイート編成 | グループ化、実行 |
| インポート/エクスポートワークフロー | データ移行、バックアップ |
| CI/CD連携 | パイプラインコマンド、レポート |
各SKILLには以下が含まれます。
- タスクタイプの特定
- コマンドシーケンスガイダンス
- フィールドの安全境界
- 検証チェックポイント
- 検証パターン
次は何ですか
これで、3つのコアコンポーネントすべてを確立しました。
- cli-schema validate — 品質ゲート
- agentHints — 次のステップへのナビゲーション
- SKILL — ワークフロー判断
次の質問は:
これは本当に機能するのか？数字はどうなっているのか？
パート6「数字は嘘をつかない: ツール呼び出しが30%減、トークンが25%減」では、社内比較による定量的結果と、削減がどこから来るのかを説明します。
主なポイント
- CLIは実行能力を提供し、SKILLは運用判断力を提供する
- SKILLはコマンドリファレンスではなく、運用ガイドである
- 隠れたワークフローには明示的なガイダンスが必要である
- ステップをインポート → 読み戻す → ローカルで更新する方が手書きよりも安全である
--with-case-detailは想像に基づいた更新を防ぐ- SKILLは進化可能である — Agentが修正できる
- CLIは製品のセマンティクスを吸収し、SKILLはワークフローをガイドする
- オンデマンドローディングはコンテキストの負担を防ぐ
設計、モック、テスト、ドキュメントを一つのワークスペースで実現するためにApidogをダウンロードしてください。コマンドラインでのAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細をご覧ください。