AIエージェントにAPIプロジェクトへの書き込みアクセス権を与えると、実際に損害を与える可能性があります。悪意があるわけではなく、エージェントはプロンプトが示唆することを実行するだけです。「ユーザーエンドポイントを整理して」と指示すれば、あなたがまだ依存している稼働中のルートを削除してしまうかもしれません。「スキーマを更新して」と指示すれば、他の3つのエンドポイントが参照しているデータモデルを上書きしてしまう可能性があります。エージェントには、何が本番環境で稼働しているかの認識がありません。触れることを許可されたリソースしか見えず、それを触るのです。
これは新しい種類のリスクです。人間がこれらの編集を行う場合、エンドポイントを削除する前にためらいます。しかし、ターミナルからループで実行されるエージェントはためらいません。コマンドを実行し、成功応答を受け取ると、次に進みます。そのコマンドがメインブランチに適用された場合、その変更はすでに設計ソースにライブで反映されています。
解決策は、エージェントを締め出すことではありません。彼らが脱出できないサンドボックスを与えることです。ApidogのAIブランチはまさにそれを実現します。エージェントによるすべての編集は隔離されたブランチに着地し、あなたのソースブランチは手付かずのままで、人間が差分を確認してマージするまで、何もメインブランチに到達しません。この記事では、CLIのフローを最初から最後まで解説し、その周辺に配置すべき一般的な安全なエージェントの衛生管理について説明します。この機能の設計根拠については、AIブランチとより安全なエージェント駆動の変更に関する詳細な記事を参照してください。この記事は実践的な運用マニュアルです。
デフォルトでエージェントの書き込みアクセスが危険な理由
ほとんどのツールは、エージェントに1つのアクセスレベル、つまりプロジェクトへのアクセス権を与えます。エージェントがエンドポイントを作成できる場合、それを削除することもできます。スキーマを更新できる場合、互換性のないものに置き換えることもできます。「エージェントが変更を提案した」と「変更が信頼できる情報源に存在する」との間にギャップはありません。
3つの失敗モードが繰り返し現れます。
- 上書き。 エージェントがAPIの部分的な理解に基づいてスキーマを再生成し、他のエンドポイントが必要とするフィールドを削除してしまう。
- 削除。 エージェントがエンドポイントを「統合」し、稼働中のクライアントによってまだ呼び出されているルートを削除してしまう。
- サイレントドリフト。 エージェントがセッション全体で数十もの小さな編集を行う。個々の変更は間違っているように見えないが、その合計は出荷されたものから静かに逸脱していく。
これらはどれも特別なことではありません。エージェントが間違ったブランチで作業を行った場合の通常の出力です。目標は、間違ったブランチに到達できないようにすることです。
根本的な解決策：隔離されたAIブランチ
AIブランチは、外部AIおよびCLI操作のために構築された特別なスプリントブランチです。これを作成すると、エージェントはその内部で編集を行い、変更はそこに留まります。あなたがマージを決定するまで、あなたのソースブランチとメインブランチは影響を受けません。
CLIから作成します。まずApidog CLIをインストールして認証します。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
次にAIブランチを作成します。ドキュメントでは、後で簡単に見つけられるように、日付、ソースブランチ、および目的を含めて命名することを推奨しています。
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
ここで重要な点が2つあります。ブランチはmainから作成されますが、作成によってmainが変更されることはありません。そして、ブランチは空で開始されます。AIブランチはプロジェクト全体を自動的にコピーするわけではなく、エージェントが明示的に持ち込むリソースのみを保持します。これは意図的な安全特性です。エージェントはインポートしたものしか編集できないため、影響範囲はあなたが指定したものに限られ、プロジェクト全体ではありません。
任意のブランチコマンドのすべてのフラグを表示するには、-hを付けて実行します。
apidog branch create -h
編集前にソースリソースをインポートする
AIブランチは空であるため、エージェントの最初の仕事は、作業に必要な特定のリソースを取り込むことです。これにより、エージェントが盲目的に操作するのを防ぎます。変更したいエンドポイント、スキーマ、またはドキュメントをインポートし、それ以外のものは一切持ち込みません。
エージェント（またはあなた自身）に、IDで正確なリソースを指定します。Apidog CLIは、これらの操作のために複数の、カンマ区切りのIDフラグを使用します。
apidog branch pick-to \
--type ai \
--from main \
--to "ai/20260708-from-main-user-register" \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
これで、AIブランチにはmainに存在するエンドポイント1と2、およびスキーマ3のコピーが含まれます。エージェントはこれらのコピーに対して作業を行います。エージェントがそれらに何を行っても、main上のオリジナルは変更されません。エージェントがここでエンドポイントを削除した場合、それはコピーを削除するものであり、稼働中のルートではありません。これは「エージェントが私たちのAPIを破壊した」と「エージェントが捨てられる一時的なコピーを破壊した」の違いです。
これをコーディングエージェントを介して実行する場合、同じコマンドがエージェントループ内で実行されます。Apidog CLIは、構造化されたJSONをagentHints.nextStepsと共に返すため、エージェントは各コマンドの結果を読み取り、あなたがその出力を翻訳することなく、次に何をすべきかを決定できます。Cursorにおけるapidog-cliのガイドは、このパターンが実際のエディタに組み込まれている様子を示しています。
エージェントに編集させ、その後差分を確認する
リソースがインポートされたら、エージェントに作業をさせます。エージェントはAIブランチ内でエンドポイント、スキーマ、ドキュメント、テストシナリオを作成、更新、または削除します。これらのすべての書き込みは隔離されています。
作業が完了したら、マージする前に確認します。AIブランチのフローには自動的なものはなく、マージは人間の判断に委ねられます。CLIまたはApidogクライアントから変更を確認し、差分が実際に意図したものと一致していることを確認します。これがあなたのゲートです。もしエージェントが暴走した場合、ここでそれに気づき、修正策はブランチを破棄することであり、本番環境をロールバックすることではありません。
このレビューはオプションではなく、必須として扱ってください。このフロー全体の目的は、人間がエージェントの出力が現実になる前に確認することです。レビューをスキップすると、隔離の意味がなくなります。
マージリクエストで変更を反映する
どのようにマージするかは、ターゲットブランチが保護されているかどうかにかかっています。ここに保護されたメインブランチの価値があります。
ターゲットブランチが保護されていない場合、直接マージすることができ、移行する正確なリソースを指定します。
apidog branch merge \
--type ai \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
mainが保護されている場合（そうすべきですが）、直接マージはブロックされます。代わりに、マージリクエストを開き、レビューを通じて変更をルーティングします。
apidog merge-request create \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--reviewer-ids <REVIEWER_USER_IDS> \
--description "AI branch: user register changes" \
--project <PROJECT_ID>
マージリクエストは、エージェントによって生成されたものすべてにとって推奨されるパスです。それは、人間の貢献者が直面するのと同じレビューフローを通して変更を強制します。チームメイトがそれを承認し、その後変更が反映されます。エージェントは単独でmainに書き込むことはありません。マージリクエストを通じて、人間がその作業を受け入れるよう要求することしかできません。マージはあなたがリストしたリソースIDのみを転送することに注意してください。もしエージェントが出荷するつもりのないものに触れた場合、そのIDをマージから除外すれば、それは残されます。
これは、GitネイティブAPIワークフローが人間の貢献者をどのように扱うかを反映しています。ブランチ作成、提案、レビュー、マージ。AIブランチは、非人間的な貢献者（最もメインブランチに直接書き込みたくない相手）にも同じ規律を適用します。
マージ済みおよび放棄されたブランチのクリーンアップ
マージ済みまたは放棄されたAIブランチは、ブランチリストを読みやすく保つために速やかにアーカイブすべきです。ブランチがマージされた後、または不要と判断した場合は、まずアーカイブしてから削除します。
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
推奨されるサイクルは、タスクごとに1つのAIブランチです。ブランチはエージェント作業の単一の単位に対応し、レビューされ、マージまたは破棄され、その後アーカイブされます。これにより、隔離が意味のあるものに保たれます。あなたは、関連性のない3つの編集セッションが蓄積されたブランチをレビューすることはありません。
ブランチ周辺の安全なエージェントの衛生管理
AIブランチは隔離を扱いますが、エージェントがそもそも到達できる範囲を制限するいくつかの習慣の中で最も効果を発揮します。
- 最小特権のアクセストークンを使用する。
apidog login --with-tokenに渡すトークンは、エージェントができることの範囲を決定します。オートメーション用トークンには、必要なプロジェクトへのアクセス権のみを与え、それ以上は与えないでください。利便性のために、個人的なオーナー権限のトークンをエージェントに渡さないでください。トークンが漏洩したり、エージェントが誤動作したりした場合に、損害をトークンの範囲に限定したいはずです。 - メインブランチを保護する。 これは、「マージ前のレビュー」を提案からルールに変える唯一の設定です。
mainが保護されている場合、直接マージパスは閉じられ、すべてのエージェントの変更はmerge-request createを経由する必要があります。この保護が、マージリクエストを必須にする要因です。 - 毎回、マージ前にレビューする。 隔離は、人間が実際に差分を読んだ場合にのみあなたを保護します。レビューをスキップできないように、ワークフローに組み込んでください。1週間信頼できたエージェントでも、8日目にはプロンプトを誤読することがあります。
- 委任し、その後検証する。 これが全体をまとめるパターンです。あなたは範囲を限定したタスクをエージェントに委任し、隔離されたブランチで実行させ、マージする前に結果を検証します。エージェントが作業を行い、あなたが承認を担当します。エージェントがテストを実行する際も同じ分担が見られます。エージェントがスイートを実行し、あなたがテストハーネスの結果と終了コードを確認してから信頼します。実行は委任し、判断は自分で保持してください。
これらすべてに加えてGitでAPI仕様をバージョン管理している場合、OpenAPIバージョン管理ワークフローは、何かがおかしいと感じたときに比較するための履歴の第2レイヤーを提供します。
エンドツーエンドのフロー（順序立てて）
エージェントに指示したり、自分で実行したりできる一連のフロー全体を以下に示します。
mainからapidog branch create --type aiを実行します。ブランチは空で、mainは変更されません。- エージェントが必要とする特定のエンドポイントとスキーマを
apidog branch pick-toで選択します。それ以外のものは何も取り込まれません。 - エージェントにブランチ内で編集させます。すべての書き込みは隔離されます。
- CLIまたはクライアントから差分をレビューします。これが人間のゲートです。
- 保護された
mainに対してapidog merge-request createを実行します。チームメイトが承認します。エージェントは直接mainに書き込むことはありません。 - マージまたは放棄されたら
apidog branch archiveを実行します。
どの時点においても、エージェントがmain上の稼働中のエンドポイントを上書きしたり削除したりする経路はありません。最悪の場合、一時的なコピーに不適切な変更を加えることですが、それもあなたがマージを拒否することで対処できます。
エージェントに鍵を渡さずに作業の余地を与える
エージェントは、尋ねることなく行動するからこそ有用です。それがまた、無制限の書き込みアクセスを危険にする理由でもあります。解決策はエージェントの速度を落とすことではなく、その迅速でためらわない書き込みを安全な場所に着地させることです。隔離されたAIブランチ、保護されたメイン、最小特権トークン、そして必須のレビューがあれば、「エージェントが私たちのAPIを破壊した」という事態は、あなたがざっと見て拒否する差分へと変わります。
Apidogはこれを組み込んでいるため、個別のツールから組み立てる必要はありません。Apidog CLIを入手し、AIブランチを作成して、エージェントに本物ではなくコピーに対して編集させましょう。ApidogをダウンロードしてAIブランチフローを試すか、本番ワークフローに組み込む前に、AIブランチのドキュメントで完全なコマンドリファレンスを参照してください。