DEV Community

Cover image for AIエージェントによる稼働中APIの停止を防ぐ方法
Akira
Akira

Posted on • Originally published at apidog.com

AIエージェントによる稼働中APIの停止を防ぐ方法

AIエージェントにAPIプロジェクトへの書き込み権限を与えると、意図せず本番に影響する変更を作る可能性があります。悪意がなくても、「ユーザーエンドポイントを整理して」という指示で稼働中のルートを削除したり、「スキーマを更新して」という指示で他のエンドポイントが依存するフィールドを上書きしたりすることがあります。エージェントは本番の利用状況を理解しているわけではなく、アクセスを許可されたリソースを操作するだけです。

今すぐApidogを試す

問題は、エージェントを使わないことではありません。エージェントが変更できる場所を隔離し、人間のレビューなしにmainへ到達できないようにすることです。ApidogのAIブランチでは、エージェントの編集を専用ブランチに閉じ込め、差分を確認してからマージできます。本記事では、CLIを使った作成・編集・レビュー・マージ・クリーンアップの手順を解説します。設計の背景はAIブランチとより安全なエージェント駆動の変更も参照してください。

デフォルトの書き込みアクセスが危険な理由

多くのツールでは、エージェントに「プロジェクトへアクセスできる」という単一の権限を与えます。しかし、エンドポイントを作成できる権限は、通常は削除や更新にも使えます。

つまり、次の2つの間に安全境界がありません。

  • エージェントが変更を提案する
  • 変更が信頼できるソース、たとえばmainに反映される

実務では、主に次の失敗が発生します。

  • 上書き: 部分的な理解をもとにスキーマを再生成し、他のエンドポイントが必要とするフィールドを削除する。
  • 削除: エンドポイントを「統合」する過程で、既存クライアントが利用しているルートを削除する。
  • サイレントドリフト: 1セッション中に多数の小さな変更を行い、個別では問題に見えなくても、合計すると意図したAPI仕様から逸脱する。

対策は「エージェントに慎重に作業させること」ではありません。そもそもエージェントがmainを直接編集できない構造にします。

AIブランチを作成する

AIブランチは、外部AIやCLIベースの自動化作業向けの隔離ブランチです。エージェントによる書き込みはAIブランチ内に保存され、レビューとマージを行うまでソースブランチやmainには反映されません。

まず、Apidog CLIをインストールして認証します。

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

次に、mainを起点にAIブランチを作成します。

apidog branch create --type ai \
  --name "ai/20260708-from-main-user-register" \
  --from main \
  --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

ブランチ名には、少なくとも次の情報を含めると管理しやすくなります。

  • 作成日
  • 元のブランチ名
  • タスク名

例:

ai/20260708-from-main-user-register
Enter fullscreen mode Exit fullscreen mode

この操作には2つの重要な性質があります。

  1. --from mainを指定しても、main自体は変更されません。
  2. AIブランチは空の状態で開始します。

AIブランチには、プロジェクト全体が自動コピーされるわけではありません。エージェントが編集できるのは、あとから明示的に取り込んだリソースだけです。これにより、エージェントの影響範囲をタスクに必要なAPI要素に限定できます。

利用可能なオプションは-hで確認できます。

apidog branch create -h
Enter fullscreen mode Exit fullscreen mode

必要なリソースだけをAIブランチへ取り込む

AIブランチは空なので、編集対象のエンドポイントやスキーマを明示的にインポートします。

たとえば、エンドポイント1と2、データスキーマ3だけを取り込む場合は次のように実行します。

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>
Enter fullscreen mode Exit fullscreen mode

この時点で、AIブランチには次だけが存在します。

  • main上のエンドポイント1と2のコピー
  • main上のデータスキーマ3のコピー

エージェントがAIブランチ内でエンドポイントを削除しても、削除されるのはコピーです。main上の元リソースや稼働中のAPIルートには影響しません。

この「必要なリソースだけを渡す」手順を省略しないでください。エージェントのタスク範囲をプロンプトだけで制限するのではなく、操作可能なリソースそのものを制限できます。

コーディングエージェントからCLIを実行する場合も、同じフローを使えます。Apidog CLIはagentHints.nextStepsを含む構造化JSONを返すため、エージェントはコマンド結果を読み取りながら次の操作を判断できます。エディタへの組み込み例はCursorにおけるapidog-cliを参照してください。

エージェントに編集させる

必要なリソースを取り込んだら、エージェントにAIブランチ内で作業させます。

エージェントが実行できる操作の例:

  • エンドポイントの作成・更新・削除
  • リクエスト／レスポンススキーマの更新
  • APIドキュメントの修正
  • テストシナリオの追加・変更

この段階の書き込みはすべてAIブランチに隔離されます。重要なのは、エージェントにmainを操作するコマンドや権限を渡さないことです。

エージェントへの指示は、対象と完了条件を具体的に指定します。

AIブランチ内のエンドポイント 1 と 2 のみを更新してください。
データスキーマ 3 に email フィールドを追加してください。
既存フィールドの削除は行わないでください。
作業後、変更内容と影響を受けるエンドポイントを報告してください。
Enter fullscreen mode Exit fullscreen mode

ただし、プロンプトの制約だけを信頼してはいけません。AIブランチとリソースの選択インポートによって、誤った操作が起きても影響を隔離します。

マージ前に差分をレビューする

エージェントの作業が完了したら、必ず差分を確認します。

レビューで確認する項目:

  • 意図しないエンドポイントが追加・削除されていないか
  • 既存スキーマの必須フィールドが消えていないか
  • 変更後のリクエスト／レスポンス形式に互換性があるか
  • テストシナリオが変更内容をカバーしているか
  • マージ対象に含めるリソースIDが正しいか

このレビューはAIブランチ運用の必須ステップです。隔離されたブランチがあっても、確認せずにマージすれば保護効果は失われます。

エージェントが意図しない変更をしていた場合、まずmainをロールバックする必要はありません。AIブランチを破棄するか、必要な部分だけを修正すれば済みます。

保護されたmainにはマージリクエストを使う

マージ方法は、ターゲットブランチが保護されているかどうかで変わります。

mainが保護されていない場合は、対象リソースを指定して直接マージできます。

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>
Enter fullscreen mode Exit fullscreen mode

ただし、運用上はmainを保護し、直接マージを許可しない構成を推奨します。

保護された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>
Enter fullscreen mode Exit fullscreen mode

マージリクエストを使うと、エージェントが生成した変更も人間の開発者と同じレビュー経路を通ります。

特に重要なのは、マージ時にリソースIDを明示する点です。

--endpoint-ids 1,2
--data-schema-ids 3
Enter fullscreen mode Exit fullscreen mode

エージェントがAIブランチ内で追加の変更をしていても、マージ対象のIDに含めなければmainへ移行されません。

この運用は、GitネイティブAPIワークフローと同じ考え方です。

  1. ブランチを作成する
  2. 変更を提案する
  3. 人間がレビューする
  4. 承認後にマージする

AIブランチは、この規律をAIエージェントにも適用します。

作業後のAIブランチをアーカイブする

マージ済みまたは不要になったAIブランチは、速やかにアーカイブします。

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

おすすめの運用単位は、1タスクにつき1つのAIブランチです。

  • ユーザー登録APIの変更: 1ブランチ
  • 決済APIのスキーマ変更: 別ブランチ
  • テストシナリオの追加: 別ブランチ

複数の無関係な作業を1つのAIブランチに蓄積すると、レビュー範囲が広がり、隔離の意味が薄れます。タスクごとに作成し、マージまたは破棄したらアーカイブしてください。

ブランチ以外で実施する安全対策

AIブランチだけでなく、エージェントに渡す権限と運用ルールも制限します。

最小権限のアクセストークンを使う

apidog login --with-tokenに渡すアクセストークンは、エージェントが実行できる操作の範囲を決めます。

自動化用トークンには、次だけを許可してください。

  • 必要なプロジェクトへのアクセス
  • 必要なブランチ操作
  • 必要なリソースの読み取り・書き込み

個人用のオーナー権限トークンをそのままエージェントに渡すのは避けてください。トークン漏洩やエージェントの誤動作が起きても、影響範囲を限定できます。

mainを保護する

mainの保護は、「レビュー推奨」を「レビュー必須」に変える設定です。

mainが保護されていれば、エージェントは直接マージできません。必ずマージリクエストを作成し、レビュアーの承認を経由する必要があります。

毎回レビューする

エージェントが過去に正しい変更を出していたとしても、次のタスクで正しく動く保証はありません。

レビューを必須化し、少なくとも次を確認してください。

  • 差分がタスク要求と一致しているか
  • 破壊的変更が含まれていないか
  • マージ対象のリソースIDが最小範囲か
  • テスト結果と終了コードに問題がないか

エージェントにテストを実行させる場合も、実行結果をそのまま信頼せず、テストハーネスの結果と終了コードを確認してから判断してください。

API仕様をGitでも管理する

API仕様をGitでバージョン管理している場合、AIブランチのレビューに加えて履歴ベースの比較もできます。

OpenAPIバージョン管理を併用すると、意図しない変更が混入したときに、仕様の履歴を別レイヤーで確認できます。

エンドツーエンドの運用フロー

実際の手順をまとめると、次の6ステップです。

  1. mainからAIブランチを作成する。 
   apidog branch create --type ai \
     --name "ai/20260708-from-main-user-register" \
     --from main \
     --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode
  1. 必要なエンドポイントとスキーマだけをAIブランチへ取り込む。 
   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>
Enter fullscreen mode Exit fullscreen mode

  1. エージェントにAIブランチ内で編集させる。

  2. 差分をレビューし、マージ対象のリソースIDを決める。

  3. 保護された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>
Enter fullscreen mode Exit fullscreen mode
  1. マージ後、または変更を破棄すると決めた後にAIブランチをアーカイブする。 
   apidog branch archive "ai/20260708-from-main-user-register" \
     --type ai \
     --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

このフローでは、エージェントがmain上の稼働中エンドポイントを直接削除・上書きする経路を持ちません。最悪でも一時的なコピーに不適切な変更を加えるだけであり、人間がマージを拒否すれば本番への影響を防げます。

エージェントには作業場所を渡し、鍵は渡さない

AIエージェントの価値は、細かな確認を待たずに作業を進められる点にあります。一方で、その速度と自律性が、無制限の書き込みアクセスを危険にします。

安全な構成は次のとおりです。

  • 隔離されたAIブランチ
  • 必要なリソースだけの選択インポート
  • 最小権限のアクセストークン
  • 保護されたmain
  • 必須の人間レビュー
  • タスク完了後のブランチアーカイブ

Apidogでは、このワークフローをCLIとブランチ機能で実装できます。Apidog CLIを導入し、まずは小さなタスクをAIブランチで実行してみてください。Apidogをダウンロードするか、実運用へ組み込む前にAIブランチのドキュメントでコマンドリファレンスを確認しましょう。

Top comments (0)