AIエージェントでより安全なプロジェクト変更

これは、APIテストおよびAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをApidogがどのように開発したかを共有する10部構成のシリーズです。順番に読むことも、興味のある投稿に直接ジャンプすることもできます：

Agentがプロジェクトリソースを変更する場合、安全性とレビューの可能性が重要です。AIブランチは分離された編集環境を提供し、人間が確認した後でのみ変更がターゲットブランチに取り込まれます。

セキュリティの課題

AI AgentがAPI開発とテストに参加する場合、CLIコマンドを介してプロジェクトリソースを作成、更新、削除できます。

この力にはリスクが伴います。

メインブランチを危険にさらすことなく、Agentに実際のプロジェクトで作業させるにはどうすればよいでしょうか？

AIブランチ：安全層

AIブランチは、外部AIおよびCLI操作のために特別に設計された特殊な種類のスプリントブランチです。

重要なコンセプト：

Apidog CLIから開始されるすべての編集操作は、デフォルトでAI / AI Agentによって開始されたものとして扱われます。

AIブランチは、AI Agentに分離された編集ブランチを提供します。変更は、人間がレビューしてマージするまでAIブランチに残ります。

AgentがCLI経由で変更を行う
        ↓
変更はAIブランチに保存される（分離）
        ↓
ユーザーが差分をレビューする
        ↓
ユーザーがリソースのスコープを確認する
        ↓
ターゲットブランチにマージする（直接またはマージリクエスト）

承認されるまで、メインブランチは変更されません。

AIブランチが必要な理由

AIによって開始される編集は予測できない場合があります。Apidog CLIは、エンドポイント、スキーマ、テストシナリオ、テストスイートなど、幅広い編集機能を提供します。

AIブランチは、これらのリスクの高いAIが開始する編集操作のために設計されています。

AI Agentが制御された範囲内でプロジェクトリソースを編集できるようにします。

AIブランチとは？

AIブランチは、特定の特性を持つ特別なスプリントブランチです。

主な特性

仕組み

ユーザーによる通常のクライアント内編集は、引き続きプロジェクトメンバーの権限とブランチ保護ルールに従います。

ユースケース

AIブランチは、ブランチの分離と人間の確認を維持しながら、AIがプロジェクトの保守に参加する必要がある場合に適しています。

基本的なワークフロー

典型的なAIブランチのワークフロー：

┌─────────────────────────────────────────────────────────────────┐
│                     AIブランチワークフロー                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ステップ 1: AIブランチを作成する                                        │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  ステップ 2: リソースをインポートまたは作成する                              │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (既存をインポート)    │                  │
│  │ または                                         │                  │
│  │ apidog endpoint create (新規作成)        │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  ステップ 3: AIがリソースを変更する                                   │
│  ┌───────────────────────────────────────────┐                  │
│  │ AgentがCLIを使用してエンドポイント、       │                  │
│  │ スキーマ、テストシナリオなどを更新する。             │                  │
│  │ (--branch パラメータでAIブランチを指定)  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  ステップ 4: ユーザーが差分をレビューする                                │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ または                                         │                  │
│  │ Apidogクライアントで表示                     │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  ステップ 5: ターゲットブランチにマージする                                  │
│  ┌───────────────────────────────────────────┐                  │
│  │ 直接マージ（保護されていないブランチ）         │                  │
│  │ または                                         │                  │
│  │ マージリクエスト（保護されたブランチ）          │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

AIブランチの作成

branch create --type aiを使用します：

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

命名推奨： ai/YYYYMMDD-from-sourceBranch-featureOrModule

AIブランチでのリソースの編集

CLIがプロジェクトリソースを書き込む際、--branchパラメータを使用してAIブランチに書き込みます：

推奨ワークフロー：

# 1. スキーマを取得
apidog cli-schema get endpoint-create

# 2. 書き込み前に検証
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. AIブランチに書き込み (メインではない)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

既存のリソースのインポート

既存のリソースを変更するには、まずソースブランチからインポートします：

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

これにより、AIが正しい基本バージョンで作業することが保証されます。

マージ前の変更のレビュー

マージする前に、差分をプレビューします：

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

または、Apidogクライアントで完全な差分を表示します。

AIブランチのマージ

レビュー後、変更をマージします：

直接マージ（保護されていないブランチ）

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

マージリクエスト（保護されたブランチ）

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

重要：マージコマンドは、明示的に指定されたリソースリストのみを処理します。マージする前に、依存関係（ディレクトリ、モデル、レスポンスコンポーネント、テスト）を確認してください。

アーカイブと削除

変更がマージされた後、または不要になった場合：

# アーカイブ
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# 削除 (アーカイブ後)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

外部AIの編集権限

デフォルトでは、CLIはAIブランチに書き込みます。これにより、AIが生成した変更はユーザーの確認があるまで分離されたままになります。

メインブランチの直接編集を有効にするには：

プロジェクト設定 → 機能設定 → AI機能設定 → 外部AI編集権限

推奨：AIブランチの分離を有効にしておきます。自動化ワークフローが明確に必要とする場合にのみ、直接編集を有効にしてください。

ベストプラクティス

CLI + SKILLワークフローにおけるAIブランチ

AIブランチはCLI + SKILLと自然に統合されます：

すべての書き込みはAIブランチ → 人間によるレビュー → マージを経由します。

セキュリティの概要

これらの層が連携して、Agent主導のプロジェクト変更のためのより安全なループを形成します。

次は何？

AIブランチが安全層を提供することで、すべての要素が揃いました：

• ツール接続のためのMCP（パート1）
• ワークフロー実行のためのCLI + SKILL（パート2-5）
• 検証結果（パート6）
• 実践的なワークフロー（パート7）
• CI/CD基盤（パート8）
• 安全のためのAIブランチ（パート9）

次はビジョンの番です。

パート10「Spec-Firstは昨日。Skill-Firstへようこそ。」では、API開発がAI Agentと共にどのように進化するか、そしてチームが次に何をすべきかについて概説します。

主要なポイント

• AIブランチは、AI/CLI操作のために分離された編集環境を提供します
• 変更は、人間の確認があるまでメインブランチには影響しません
• branch create --type aiで作成し、--branchパラメータで書き込みます
• 編集前にbranch pick-toで既存のリソースをインポートします
• merge-request previewでプレビューし、その後マージまたはマージリクエストを作成します
• 直接編集権限はAIブランチをバイパスする可能性があります — 慎重に使用してください
• ベストプラクティス：タスクごとに1つのAIブランチ、書き込み前の検証、マージ前のレビュー

Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント化を行いましょう。コマンドラインAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細をご覧ください。