Traeはループです。そのBuilderエージェントは、リポジトリを読み取り、ファイルを編集し、ターミナルでコマンドを実行し、その出力から次に行うべきことを決定します。では、なぜAPIテストがそのループに入っていないのでしょうか？APIテストはApidogのGUIの背後にあり、誰かがクリックすると思い出したときに実行されます。エージェントは決してそれらに触れません。
解決策は1つの設定ブロックです。Apidog CLIは`apidog-cli`というnpmパッケージで、Apidogで構築したテストシナリオをターミナルから直接実行します。CLIがインストールされ、Traeがその存在を認識すると、Builderはユニットテストを実行するのと同じ方法でApidogシナリオを実行します。つまり、コマンドを発行し、終了コードを読み取り、赤（失敗）であればコードを修正します。
まだCLIをインストールしていない場合は、まずそれを行ってください。AIコーディングエージェントを使用したApidog CLIのインストール方法では、エージェントが入力を行いながらnpmインストール、認証、初回実行の手順を説明しています。この記事では、`apidog --version`が数値を出力し、Apidogアカウントが認証されていることを前提としています。
どのTraeについての話か
TraeはByteDanceのAI IDEで、VS Code上に構築されており、ファイルを編集したりターミナルコマンドを自身で実行したりするBuilderというエージェントモードを備えています。製品の詳細はTraeの公式サイトで確認できます。この記事はデスクトップIDEに関するものであり、GitHub上のスタンドアロンの`trae-agent`研究プロジェクトに関するものではありません。Traeを開いてエディターの横にチャットパネルが表示され、エージェントをBuilderに切り替えられるのであれば、正しい場所にいます。
この区別は重要です。なぜなら、Traeにはプロジェクトのルールを学習する独自の方法があり、そのメカニズムにより一度きりの「テストを実行する」が、Builderが自ら実行するものに変わるからです。そのメカニズムがプロジェクトルールファイルです。このワークフローのツールに依存しないバージョンをまず知りたい場合は、Apidog CLI完全ガイドでCLIについて単独で説明しています。
ステップ1：プロジェクトルールファイルを追加する
Builderが作業を開始する前にTraeはルールファイルを読み込みます。プロジェクトレベルのファイルは、Traeのルールに関するドキュメントに従い、リポジトリのルートにある`.trae/rules/project_rules.md`に存在します。エージェントは初期化中にこれらのルールを読み込み、コードの生成と編集中にそれらを参照します。すべてのプロジェクトに適用されるユーザーレベルの`user_rules.md`もありますが、このワークフローではリポジトリルートに1つのプロジェクトファイルで十分です。
`.trae/rules/project_rules.md`を作成し、CLIの名前、正確なシナリオコマンド、およびBuilderを正直に保つためのルールを記述した短いブロックを追加します。
## Apidog CLIによるAPIテスト
APIエンドポイントに触れるコードを変更した際は、ユニットテストだけでなく、Apidogテストシナリオを実行して検証してください。
コマンド:
apidog run -t <scenario_id> -e <env_id> -r cli
ルール:
- `apidog run`はすべてのアサーションがパスした場合に0を返し、いずれかの失敗で非ゼロを返します。
サマリーが問題なさそうに見えても、非ゼロの終了コードはテストの失敗と見なしてください。
- このマシンは`apidog login`経由で既に認証されています。`--access-token`フラグを追加したり、このファイルにトークンを記述したりしないでください。
- 不明なフラグがある場合は、`apidog run --help`を実行し、そこから正確なフラグを使用してください。
これが、CLIをチャットパネルで言及するのではなく、`project_rules.md`に書き込む理由です。チャットパネルに入力されたシナリオIDはセッション終了時に消えてしまいます。しかし、`.trae/rules/project_rules.md`にあるものは、今後すべてのチームメイトとすべてのBuilder実行で利用できます。Traeはサブディレクトリ内の`.trae/rules/`フォルダも読み込むため、モノレポではサービスごとにルールを各サービスの隣に配置できます。
ステップ2：Apidogからコマンドを取得する
コマンドを推測する必要はありません。Apidogでテストシナリオを開き、そのCI/CDタブに移動して、生成された`apidog run`行をコピーします。`-t`の後に実際のシナリオIDが、`-e`の後に環境IDが既に入力されているため、手作業でIDを考案するのではなく、Apidogが有効であることを知っているコマンドを貼り付けることになります。
それらの正確なIDを`.trae/rules/project_rules.md`のブロックにドロップし、``と``のプレースホルダーを置き換えます。フラグの完全なセットとそれぞれの機能については、apidog runコマンドリファレンスを参照してください。
ステップ3：Builderにテストを実行させる
ブロックが配置されたら、TraeのエージェントをBuilderに切り替え、リポジトリで開始します。Builderは初期化時に`project_rules.md`を読み込むため、CLIが存在することを既に知っています。APIに影響を与える変更を行うか、単にチェックを実行するように依頼します。
Apidogテストシナリオを実行して、終了コードを教えてください。
Builderはルールファイルから`apidog run`コマンドを発行します。ここでTraeの承認モデルが重要になります。エージェントがシェルコマンドを実行したい場合、そのコマンドを推奨し、「実行」ボタンを表示します。コマンドは、あなたがクリックして初めてTraeのターミナルで実行されます。一度実行されると、Builderは自動的に出力を読み取り、分析します。したがって、あなたは`apidog run`を一度承認すれば、エージェントはそこから結果を受け取ります。
`-r cli`レポーターは、Builderが各リクエストとアサーションをリアルタイムで読み取るターミナル内に、ステップバイステップの結果とサマリーを直接出力します。実行が進行し、Builderがサマリーと終了コードの両方を報告していることを確認したいはずです。
ステップ4：Trae内でレポートを読み取る
実行が失敗（赤色）した場合、レポートに答えがあります。`-r cli`を使用すると、BuilderはTraeのターミナルで読みやすい内訳（各リクエスト、各アサーション、そして期待値と実際値で何が失敗したか）を取得します。失敗したアサーションは正確なフィールド名やステータスコードを特定するため、通常はBuilderが修正点を見つけるのに十分です。
ブラウザで開いたり、チームメイトに渡したりできるレポートが必要な場合は、HTMLレポーターを追加します。
apidog run -t <scenario_id> -e <env_id> -r cli,html
`html`レポーターは、自己完結型のファイルを`./apidog-reports`に書き込みます。Builderが次のステップを決定するために読み取るインライン出力を引き続き取得できるよう、リストに`cli`を残しておいてください。CIダッシュボードが解析するJSONおよびJUnit形式を含むすべてのレポーターについては、Apidog CLIテストレポートのガイドを参照してください。
Trae独自のループ内でのテスト
重要なのは、あなたが指示しなくなり、`project_rules.md`が指示した通りにBuilderが自らシナリオを実行するようになったときに何が起こるか、という点です。
Builderがチェックアウト応答を構築するハンドラーを編集している状況を想像してください。そのループは変化します。コードを編集した後、成功を宣言する代わりに、ステージング環境に対してApidogシナリオを実行し、終了コードを読み取り、それに基づいて行動します。グリーン（成功）であれば次に進み、レッド（失敗）であればレポートを開き、どのアサーションが失敗したか（ステータスコード、不足しているフィールド、間違った値）を読み取り、修正を試み、再実行します。APIテストは、Builderがすでにユニットテストを実行しているのと同じ編集-テスト-修正のループの一部となります。あなたは1つの指示を書いただけで、Builderはそのコマンドを既存の作業方法に組み込んだのです。
これは、あらゆるエージェントワークフローを安全にする「委任して検証する」モデルです。Builderはコマンドを実行し結果を読み取ります。あなたはApidogで視覚的にシナリオを作成し続け、エージェントが終了コードを正直に読み取っているかをスポットチェックします。より広範なパターンについては、AIエージェントをAPIテストに利用する方法とApidog AIテストハーネスを参照してください。
Traeが実際にCLIを実行していることを確認する
エージェントは実際には達成していない成功を報告することがあり、Builderも例外ではありません。問題を発見する頻度順に3つのチェックがあります。
まず、コマンドがそもそも実行されたことを確認します。TraeはBuilderが実行したコマンドとその出力をターミナルに表示します。`apidog run`という文字通りの行と、その下の結果を探してください。Builderがテストを実行したと言っているのにコマンドが見当たらない場合、それは実行していないことを要約しただけです。再度実行して生出力を表示するように依頼してください。
次に、終了コードを確認します。
そのapidog runコマンドの終了コードは何でしたか？
`apidog run`は、すべてのアサーションがパスした場合に0で終了し、何かが失敗した場合は非ゼロで終了します。この単一の挙動により、Builderやパイプラインは実行をクリーンなゲートとして扱うことができます。Builderの説明が「テストはパスしました」と言っているのに終了コードが非ゼロの場合、終了コードが正しいです。
第三に、実際のシナリオが使用されたことを確認します。実行が「scenario not found」で失敗した場合、BuilderがIDをでっち上げたか、誤って記憶している可能性があります。`-t`と`-e`の値を`project_rules.md`、およびApidogがCI/CDタブで生成したコマンドと照合して再確認してください。ルールファイル内のIDが真実です。
オプション：Apidog MCPサーバーを接続する
`project_rules.md`から`apidog run`を実行するだけで、必要なことのほとんどはカバーできます。MCPサーバーを接続すると、さらに一歩進んだことができます。TraeエージェントはMCPクライアントとして機能するため、BuilderはMCPサーバーが公開するツールを呼び出すことができます。
追加するには、Traeの設定を開き、MCPタブに移動します。マーケットプレイスからサーバーを選択するか、「手動で追加」を選択し、TraeのMCPサーバー追加ガイドに従って、サーバーの`command`、`args`、`env`を含むJSONブロックを貼り付けます。Apidog MCPサーバーは、MCPを介してAPI仕様を公開するため、Builderはコードを記述しながらスキーマを読み取ることができ、事後的にではなく、その時点で利用できます。役割分担は明確です。CLIがテストを実行し、MCPがエージェントに仕様を提供します。
Traeが間違った場合
セットアップ中によく発生するいくつかの失敗があります。
ルールファイルが無視される。Builderが汎用コマンドを実行したり、何も実行しなかったりする場合、ファイルが読み込まれていない可能性があります。リポジトリのルートの`.trae/rules/project_rules.md`にファイルが存在すること、そしてフォルダ名が`rule`ではなく`rules`であることを確認してください。セッションを再起動すると、ルールが強制的に再読み込みされます。
アクセストークンを渡してしまう。Builderが`--access-token`を追加しようとする場合、それは公開されている例から推測している可能性があります。マシンは`apidog login`経由で認証されているため、ブロックにはすでにそうしないよう指示されています。その指示を強調し、決して実際のトークンを`project_rules.md`に置かないでください。対話的な使用とCIでのCLIの認証情報処理については、Apidog CLI認証を参照してください。
フラグをでっち上げる。「不明なオプション」エラーは、Builderがあなたのバージョンにはないフラグを推測したことを意味します。`apidog run --help`を実行し、そこから正確なフラグをコピーするように指示してください。それはインストールされているバージョンに対して常に正しいです。
失敗した実行なのに成功と報告する。これが最もコストがかかる問題であり、`project_rules.md`に終了コードのルールがあり、検証ステップが必要な理由です。サマリーと終了コードが一致しない場合、終了コードが優先されます。
日常のエージェントからテストされたループへ
これでセットアップは完了です。インストールガイドに従って`apidog-cli`を一度インストールし、`.trae/rules/project_rules.md`に短いApidogブロックを追加すると、Builderはコード編集にすでに使用しているのと同じループ内でAPIテストを実行し、その結果を読み取ることができるようになります。壊れたエンドポイントは、Builderが変更作業中に捕捉され、デプロイ後ではなくその場で修正されます。
GUIの背後にあるテストは人間がクリックしたときに実行されますが、Builderが判断するたびに1行のコマンドが実行されます。あなたはApidogで視覚的にシナリオを構築し続け、エージェントはあなたが監視していない場所でそれらを実行します。Apidogをダウンロードし、1つのシナリオを構築し、その`apidog run`コマンドを`.trae/rules/project_rules.md`にドロップして、次回の変更時にBuilderがそれを実行するのを見てください。エージェントがいない状況で同じシナリオを実行する準備ができた場合は、GitHub ActionsでのApidog CLIが、CIのためのシークレット、レポーター、および終了コードによるゲート処理をカバーしています。