Claude Codeは、ファイルを編集し、ターミナルでコマンドを実行し、出力を読み取り、次のアクションを決定するループで動作します。APIテストもこのループに組み込めば、GUIで手動実行するだけのテストから、コード変更を検証する自動ゲートへ変えられます。
Apidog CLIはnpmパッケージapidog-cliとして提供されており、Apidogで作成したテストシナリオをターミナルから直接実行できます。Claude CodeがCLIの実行方法を知っていれば、ユニットテストと同じようにapidog runを実行し、終了コードとレポートをもとに修正の要否を判断できます。
この記事では、Claude Codeの編集・テスト・修正ループへApidog CLIを組み込む方法を説明します。具体的には、CLAUDE.mdに追加する設定、apidog runの実行権限、実行結果の確認方法を扱います。
まだCLIをインストールしていない場合は、先にセットアップしてください。AIコーディングエージェントによるApidog CLIのインストール方法では、npmでのインストールから初回実行までを説明しています。この記事では、以下を満たしていることを前提にします。
-
apidog --versionがバージョン番号を出力する -
apidog loginによる認証が完了している
どのClaude Codeについてか
対象はAnthropicのコーディングエージェントであるClaude Code CLIです。リポジトリを読み込み、ファイルを編集し、シェルコマンドを実行し、権限設定に応じて承認を求めます。
リポジトリ内で次のコマンドを実行し、編集やコマンド実行を提案する対話型エージェントを使っている場合は、この手順の対象です。
claude
Claude Codeでは、プロジェクト固有のルールをCLAUDE.mdに記述します。Claude Codeスラッシュコマンドと同様に、CLIの実行ルールもこのファイルで管理できます。
重要なのは、チャットで一度だけ「APIテストを実行して」と依頼するのではなく、CLAUDE.mdに恒久的なルールとして書くことです。これにより、Claude Codeは各セッションでAPIテストの存在と実行方法を認識できます。
ステップ1: ApidogブロックをCLAUDE.mdに追加する
Claude Codeはセッション開始時にCLAUDE.mdを読み取ります。これはCodexのAGENTS.mdに相当するファイルです。Claude Codeのドキュメントでも、Claude CodeはAGENTS.mdではなくCLAUDE.mdを読み取ることが説明されています。
すでに他のエージェント向けにAGENTS.mdを使っている場合は、CLAUDE.mdから@AGENTS.mdとして読み込む構成も可能です。CodexでApidog CLIをセットアップしている場合も、考え方は同じです。
CLAUDE.mdは通常、リポジトリルートに配置します。Claude Codeは以下の場所も読み込めます。
./CLAUDE.md./.claude/CLAUDE.md~/.claude/CLAUDE.md
リポジトリ全体に適用するには、ルートのCLAUDE.mdに次のブロックを追加してください。<scenario_id>と<env_id>は実際の値に置き換えます。
## Apidog CLIによるAPIテスト
このプロジェクトにはApidogテストシナリオがあります。APIをチェックするには、以下を実行します。
`apidog run -t <scenario_id> -e <env_id> -r cli`
- 終了コード0はすべてのアサーションが成功したことを意味します。0以外は何らかの失敗を意味します。レポートを確認し、先に進む前に修正してください。
- マシンは`apidog login`を介してすでに認証されています。`--access-token`フラグを追加したり、このファイルにトークンを置いたりしないでください。
- フラグが不明な場合は、`apidog run --help`を実行し、表示された正確なフラグを使用してください。
このルールは、以後のClaude Codeセッションでも利用されます。CLAUDE.mdは起動時に読み込まれ、/compact後も指示が維持されます。
ステップ2: Apidogから実行コマンドを取得する
<scenario_id>と<env_id>を推測で入力しないでください。
- Apidogで対象のテストシナリオを開きます。
- CI/CDタブへ移動します。
- 生成された
apidog run ...コマンドをコピーします。 - コピーしたコマンドを
CLAUDE.mdのApidogブロックへ貼り付けます。
生成されたコマンドには、実際のシナリオID、環境ID、レポーター設定が含まれています。
apidog run -t <scenario_id> -e <env_id> -r cli
-r cliは、各リクエスト、アサーション結果、実行サマリーをターミナルに出力します。この出力をClaude Codeが読み取り、次に修正すべき内容を判断します。
フラグの詳細は、Apidog CLI完全ガイドおよびapidog runコマンドリファレンスを参照してください。
ステップ3: Claude Codeにテストを実行させる
リポジトリのルートでClaude Codeを起動します。
claude
Claude Codeは起動時にCLAUDE.mdを読み込みます。APIに影響する変更を加えた後、または明示的に確認したいときに、次のように依頼します。
チェックアウトAPIを変更しました。CLAUDE.mdのApidogテストを実行し、失敗した場合はレポートを確認して修正してください。
Claude CodeはCLAUDE.mdに記載したコマンドを使って、次のような実行を行います。
apidog run -t <scenario_id> -e <env_id> -r cli
apidog runの実行権限を設定する
デフォルトのClaude Codeでは、未承認のシェルコマンドを実行する前に確認が表示されます。最初は表示された承認プロンプトでapidog runを許可してください。
信頼できるコマンドとして毎回の確認を省略したい場合は、セッション内で/permissionsを実行するか、.claude/settings.jsonに許可ルールを追加します。
{
"permissions": {
"allow": [
"Bash(apidog run *)"
]
}
}
ステージング環境に対して読み取り専用でテストするシナリオなら、許可リストに追加しやすい構成です。
無人実行では--dangerously-skip-permissionsも利用できますが、日常のローカル作業ではなくCI用途として扱ってください。
ステップ4: Claude Code内でレポートを読み取る
テストが失敗した場合は、-r cliの出力を確認します。Claude Codeはターミナル上で以下を確認できます。
- 実行されたリクエスト
- 実行されたアサーション
- 期待値と実際値の差分
- 失敗したフィールド名
- 失敗したステータスコード
- コマンドの終了コード
失敗したアサーションに表示される情報は、修正箇所を絞り込むための入力になります。
ブラウザで共有・確認できるレポートも必要なら、HTMLレポーターを追加します。
apidog run -t <scenario_id> -e <env_id> -r cli,html
htmlレポーターは自己完結型のファイルを./apidog-reportsに出力します。Claude Codeが判断に使うターミナル出力を残すため、cliは削除しないでください。
JUnit形式など、CIで解析するレポーターについてはApidog CLIテストレポートを参照してください。
Claude Code自身のループ内でテストする
設定後のClaude Codeは、コード編集のたびに次のループを実行できます。
- ハンドラーやサービスのコードを編集する
-
apidog runでステージング環境のシナリオを実行する - 終了コードとCLIレポートを確認する
- 成功なら次の作業へ進む
- 失敗なら、ステータスコード・不足フィールド・不正な値を確認する
- コードを修正し、再実行する
たとえば、チェックアウトレスポンスを返すハンドラーを変更した場合、Claude Codeは変更後にApidogシナリオを実行できます。失敗時はレポートからアサーションの失敗内容を確認し、修正して再実行します。
これは、APIテストをユニットテストと同じ編集・テスト・修正ループへ組み込む方法です。
より広い運用パターンについては、AIエージェントをAPIテストに利用する方法とApidog AIテストハーネスを参照してください。
Claude Codeが実際にCLIを実行したか検証する
エージェントの「テストは成功しました」という要約だけで判断しないでください。以下の3点を確認します。
1. apidog runが実行されたか
Claude Codeは実行したコマンドと出力をインラインで表示します。以下のようなコマンド行と、その直後の結果があることを確認してください。
apidog run -t <scenario_id> -e <env_id> -r cli
Claude Codeが「テストを実行した」と報告していても、このコマンドや生の出力が表示されていない場合、実行せずに要約しただけの可能性があります。その場合は、次のように依頼してください。
Apidogテストをもう一度実行し、コマンド、CLI出力、終了コードをそのまま表示してください。
2. 終了コードが0か
apidog runは、すべてのアサーションが成功した場合に終了コード0を返します。アサーションが1つでも失敗すると、終了コードは0以外になります。
Claude Codeには次のように確認できます。
そのapidog runコマンドの終了コードは何でしたか？
要約が成功となっていても終了コードが0以外なら、失敗として扱ってください。終了コードをゲートの判定基準にします。
3. 正しいシナリオと環境を使用したか
「シナリオが見つかりません」といったエラーが出た場合は、シナリオIDまたは環境IDが誤っている可能性があります。
次の値を照合してください。
-
CLAUDE.mdの-t <scenario_id> -
CLAUDE.mdの-e <env_id> - ApidogのCI/CDタブで生成されたコマンド
IDは、Apidogが生成したコマンドを正として管理してください。
オプション: Apidog MCPサーバーに接続する
CLAUDE.mdからapidog runを実行するだけでも、APIテストの自動実行には十分です。さらに、MCPサーバーを接続すると、Claude Codeはコーディング中にAPI仕様を参照できます。
Claude CodeはModel Context Protocol（MCP）をサポートしています。claude mcp add ...でサーバーを追加するか、プロジェクトルートの.mcp.jsonをコミットして--scope projectでチーム共有できます。
Apidog MCPサーバーは、MCP経由でAPI仕様を公開します。
役割は次のように分けられます。
- Apidog CLI: テストシナリオを実行する
- Apidog MCPサーバー: Claude CodeにAPI仕様を提供する
Claude Codeが誤った場合の対処
CLAUDE.mdブロックが無視される
Claude Codeが一般的なコマンドを実行したり、コマンド自体を実行しなかったりする場合、CLAUDE.mdが読み込まれていない可能性があります。
以下を確認してください。
- ファイル名が正確に
CLAUDE.mdである - ファイルがリポジトリルート、または現在のディレクトリの親にある
- セッション内で
/memoryを実行し、読み込まれたファイル一覧に対象ファイルがある
ファイルを追加・変更した直後は、Claude Codeセッションを再起動して再読み込みしてください。
--access-tokenを追加しようとする
Claude Codeが--access-tokenを追加しようとする場合は、公開されている例をもとに推測している可能性があります。
すでにapidog loginで認証済みであれば、CLAUDE.mdにトークンを保存する必要はありません。トークンは絶対にCLAUDE.mdへ書き込まないでください。
認証手順はApidog CLI認証を参照してください。
存在しないフラグを使う
unknown optionエラーは、インストール済みのCLIバージョンに存在しないフラグを使用していることを示します。
以下を実行し、表示されたフラグだけを使ってください。
apidog run --help
失敗した実行を成功と報告する
もっとも重要なのは、終了コードを確認することです。
- 終了コード
0: 成功 - 終了コード
0以外: 失敗
サマリーの文章と終了コードが一致しない場合は、終了コードを優先してください。
日常のエージェントからテスト済みのループへ
セットアップはシンプルです。
-
インストールガイドに従って
apidog-cliをインストールする - Apidogでテストシナリオを作成する
- CI/CDタブから
apidog runコマンドをコピーする - リポジトリの
CLAUDE.mdにコマンドと終了コードのルールを記述する - Claude CodeにAPI変更後のテスト実行を依頼する
GUIの背後にあるテストは人がクリックしたときだけ実行されます。一方、CLAUDE.mdに記述した1行のコマンドは、Claude Codeがコード変更を検証するタイミングで実行できます。
Apidogでシナリオを作成し、そのapidog runコマンドをCLAUDE.mdに追加してください。Apidogをダウンロードして最初のシナリオを作成したら、次のコード変更時にClaude Codeのループへ組み込めます。
Claude CodeなしのCIパイプラインでも同じコマンドを実行したい場合は、GitHub ActionsにおけるApidog CLIを参照してください。
Top comments (0)