AI Branch（ベータ）

AI Branch は、Sprint Branch の特殊な種類です。

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

AI Branch は、Apidog プロジェクト内で AI Agents に分離された編集ブランチを提供するために設計されています。AI Branch を使用すると、AI はメインブランチや標準のスプリントブランチを直接変更することなく、プロジェクトリソースを作成および更新できます。変更が完了した後、ユーザーはクライアントまたは CLI で差分を確認し、その結果を直接、またはマージリクエストを通じてターゲットブランチにマージできます。

AI Branch が必要な理由

AI によって開始される編集は予測できない場合があり、一方で Apidog CLI は幅広い編集機能を提供します。AI Branch は、このような比較的リスクの高い AI 起点の編集操作向けに設計されており、AI Agents が制御された範囲内でプロジェクトリソースを編集できるようにします。

また、Apidog 2.8.31 以降にアップグレードし、必要に応じて Project Settings -> Feature Settings -> External AI Edit Permissions で、メインブランチ、標準のスプリントブランチ、および一般ブランチに対する直接編集権限を有効にすることもできます。有効にすると、これらの権限により、通常は AI Branch を必要とする直接編集の制限がバイパスされます。

AI Branch とは

AI Branch は、特殊なスプリントブランチです。標準のスプリントブランチと同様に、プロジェクトリソースへの変更を保存します。ただし、デフォルトでは CLI ベースの編集など、外部 AI 操作を目的としており、変更がマージされる前に人による確認ステップを保持します。

AI Branch の主な特徴は次のとおりです。

分離された編集: CLI から API、ドキュメント、データモデル、テストシナリオなどのリソースに加えられた変更は AI Branch に保存され、メインブランチやソースブランチには直接影響しません。

明確なソース: AI Branch は Apidog クライアントで直接作成することはできません。CLI または MCP ソースから作成する必要があります。AI Branch はソースブランチを記録し、通常はそのソースブランチへマージされるため、AI によって生成された変更のコンテキストを理解しやすくなります。

人による確認: AI Branch 内の変更は、マージ前にユーザーによって確認される必要があります。ユーザーは差分を確認し、リソース範囲を選択し、直接マージするかマージリクエストを作成するかを選択できます。

数量制限なし: 現時点では、作成できる AI Branch の数に有効な制限はありません。AI Agents は、業務ドメイン、イテレーション、または機能ごとにデータを処理するために AI Branch を使用できます。

自動アーカイブ: プロジェクトコラボレーション中に AI Branch が制御不能に増加することを防ぐため、各 AI Branch はソースブランチと 24 時間ごとに比較されます。差分が見つからない場合、自動的にアーカイブされます。アーカイブされた AI Branch は Apidog でいつでも復元できます。また、Apidog CLI から新しい AI Branch を制限なく再作成できます。

TIP

AI Branch は、外部 AI または CLI 操作による書き込み結果を保存するために使用されます。通常のクライアント内編集、マージ、およびユーザーによるレビューは、引き続きプロジェクトメンバー権限とブランチ保護ルールに従います。

ユースケース

AI Branch は、ブランチの分離と人による確認を維持しながら、AI がプロジェクトリソースのメンテナンスに参加する必要がある場合に適しています。

シナリオ	説明
コードから API ドラフトを生成する	コードを読み取った後、AI は AI Branch 内で HTTP API エンドポイントを作成または更新します。ユーザーはマージ前に変更を確認します。
API リソースを一括整理する	AI は、現在のコラボレーションブランチに直接影響を与えることなく、API ディレクトリの調整、説明の追加、データモデルやレスポンスコンポーネントの更新を行えます。
自動テストのドラフトを生成する	AI は、テスターによる後続の確認のために、AI Branch 内でテストシナリオ、テストケース、またはテストデータを作成できます。
API ドキュメントの不足を補完する	AI は、バグレポート、API 実装、または OpenAPI ファイルに基づいて不足しているフィールドを補完できます。
CI/CD で一括書き込みする	自動化ワークフローは、生成された結果を AI Branch に書き込み、マージ前にユーザーレビューを待機できます。

基本ワークフロー

一般的な AI Branch のワークフローは次のとおりです。

AI Branch を作成し、その基準となるソースブランチを指定します。

編集が必要なリソースを AI Branch にインポートするか、AI Branch 内で新しいリソースを作成します。

AI Agent、CLI、または自動化スクリプトが AI Branch 内のリソースを変更します。

ユーザーは AI Branch とソースブランチの差分を確認し、マージするリソース範囲を確認します。

ターゲットブランチの保護ルールに応じて、直接マージするか、マージリクエストを作成します。

AI Branch を作成する

AI Branch を作成するには、branch create --type ai を使用します。従来の sprint-branch および sb エントリポイントも引き続き互換性がありますが、統一された branch エントリポイントの使用を推奨します。

コマンド	説明	例
`branch create --type ai`	AI Branch を作成します。	`apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main`
`branch list --type ai`	プロジェクト内の AI Branch を表示します。	`apidog branch list --project <projectId> --type ai`
`branch list --type all`	プロジェクト内のすべてのブランチタイプを表示します。	`apidog branch list --project <projectId> --type all`
`branch get --type ai`	指定した AI Branch の詳細（ブランチタイプやソース情報を含む）を表示します。	`apidog branch get <branchName> --project <projectId> --type ai`

例: ユーザー登録 API 用の AI Branch を作成する

TIP

AI Branch の命名形式は ai/YYYYMMDD-from-sourceBranch-featureOrModule を推奨します。例: ai/20260312-from-main-userRegister。明確な名前により、チームはブランチのソース、目的、作成時刻を理解しやすくなります。

AI Branch 内でリソースを編集する

CLI がプロジェクトリソースを書き込む際、ブランチパラメータを使用して、それらのリソースを AI Branch に書き込むことができます。パラメータはリソースコマンドによって若干異なります。使用前に、対応するコマンドヘルプと JSON Schema を確認してください。

リソースタイプ	一般的なコマンド	例
HTTP API エンドポイント	`endpoint create`, `endpoint update`	`apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json`
データモデル	`schema create`, `schema update`	`apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json`
Markdown ドキュメント	`doc create`, `doc update`	`apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json`
テストシナリオ	`test-scenario create`, `test-scenario update`	`apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json`
テストスイート	`test-suite create`, `test-suite update`	`apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json`
テストデータ	`test-data create`, `test-data update`	`apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json`

複雑なリソースを作成または更新する場合は、まず cli-schema を使用してデータ構造を確認および検証することを推奨します。

ソースブランチからリソースをインポートする

AI Branch が既存リソースを変更する必要がある場合は、まず branch pick-to を使用して、ソースブランチから AI Branch にリソースをインポートします。インポート後、AI は AI Branch 内でそれらのリソースの編集を続行できます。

コマンド	説明	例
`branch pick-to`	ソースブランチからターゲット AI Branch にリソースをインポートします。	`apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids>`

例: エンドポイントをインポートし、AI に変更させる

TIP

pick-to は、コマンドで明示的に指定されたリソースのみをインポートします。ディレクトリ、データモデル、レスポンスコンポーネント、またはその他の関連リソースが必要な場合は、インポート前にリソース範囲を確認してください。

AI Branch の変更を表示する

マージ前に、AI Branch とターゲットブランチ間の候補変更をプレビューすることを推奨します。CLI では merge-request preview を使用して、現在サポートされているリソースタイプをスキャンできます。クライアントでは、より完全なブランチ差分を表示することもできます。

コマンド	説明	例
`merge-request preview`	マージ前にリソース範囲を確認するため、候補変更をスキャンします。	`apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName>`
`branch get --type ai`	AI Branch の基本情報を表示します。	`apidog branch get <aiBranchName> --project <projectId> --type ai`

例: マージ前に候補変更をプレビューする

TIP

merge-request preview は、CLI が現在サポートしているリソースタイプについて候補差分をスキャンします。これは完全なリソース差分ではありません。最終マージ前には、重要なリソース内容をクライアントで確認することを引き続き推奨します。

AI Branch をマージする

AI Branch の変更が完了したら、それらをソースブランチまたは別のターゲットブランチにマージできます。保護されていないターゲットブランチの場合は、branch merge を使用して直接マージします。保護されたメインブランチの場合は、merge-request create を使用してマージリクエストを作成し、レビュー手順を経ます。

コマンド	説明	例
`branch merge`	指定したリソースを AI Branch から直接マージします。	`apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`merge-request create`	マージリクエストを作成します。	`apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids>`
`merge-request approve`	マージリクエストを承認します。	`apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json`
`merge-request reject`	マージリクエストを却下します。	`apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName>`

例: エンドポイントの変更を直接マージする

例: マージリクエストを作成する

TIP

直接マージとマージリクエストのいずれも、明示的に指定されたリソースリストのみをマージします。参照されているリソースやディレクトリリソースは自動的には含まれません。マージ範囲を定義する際は、エンドポイント、ディレクトリ、データモデル、レスポンスコンポーネント、テストリソース間の依存関係を確認してください。

AI Branch をアーカイブおよび削除する

AI Branch がマージされた後、または不要になった後は、まずアーカイブしてから削除できます。削除前に、ブランチ内の変更がマージ済みであるか、不要になっていることを確認してください。

コマンド	説明	例
`branch archive --type ai`	AI Branch をアーカイブします。	`apidog branch archive <aiBranchName> --project <projectId> --type ai`
`branch delete --type ai`	アーカイブ済みの AI Branch を削除します。	`apidog branch delete <aiBranchName> --project <projectId> --type ai`

外部 AI 編集権限

デフォルトでは、CLI は AI Branch を通じてプロジェクトリソースを書き込むことを推奨します。これにより、AI が生成した変更はまず分離されたブランチに入り、ユーザー確認後にのみマージされます。

外部 AI または CLI 操作で、メインブランチ、標準のスプリントブランチ、または一般ブランチを直接編集したい場合は、クライアントで対応する権限を有効にします。

Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions

これらのスイッチは、プロジェクトブランチ全体における外部 AI、CLI、または自動化呼び出しの直接書き込み範囲を制御します。有効にする前に、チームのコラボレーションルールとプロジェクトデータのセキュリティ要件を確認してください。

権限	説明
メインブランチ直接編集権限	外部 AI または CLI 操作がメインブランチに直接書き込むことを許可します。
標準スプリントブランチ直接編集権限	外部 AI または CLI 操作が標準のスプリントブランチに直接書き込むことを許可します。
一般ブランチ直接編集権限	外部 AI または CLI 操作が一般ブランチに直接書き込むことを許可します。
AI Branch 直接編集権限	外部 AI または CLI 操作が、AI によって作成および管理される AI Branch に書き込むことを許可します。通常、これは有効のままにします。

TIP

プロジェクトリソースを保護するため、外部 AI または CLI 操作はまず AI Branch に書き込み、ユーザー確認後にのみマージすることを推奨します。直接編集権限は、自動化ワークフローがターゲットブランチを直接変更する必要が明確な場合にのみ有効にしてください。

ベストプラクティス

タスクごとに 1 つの AI Branch を作成する: 各 AI Branch は、ユーザー登録 API の完成、注文モジュールドキュメントの整理、支払いテストシナリオの生成など、明確なタスクに対応する必要があります。

編集前にインポートする: 既存リソースを変更する場合は、まず pick-to を使用してインポートし、その後 AI Branch 内で更新することで、ソースに関する混乱を避けます。

マージ前に差分をプレビューする: merge-request preview またはクライアントの差分ビューを使用して、リソース内容と依存関係を確認します。

マージ範囲を明示的に選択する: マージコマンドは、指定されたリソースリストのみを処理します。API ディレクトリ、データモデル、レスポンスコンポーネント、テストケースなどの関連リソースについては、まとめて確認してください。

人によるレビューを維持する: AI が生成した API 定義、テストスクリプト、データモデルは、マージ前にプロジェクトメンバーがレビューする必要があります。

ブランチを速やかにアーカイブする: マージ済みまたは放棄された AI Branch は、ブランチ一覧を明確に保つために速やかにアーカイブしてください。

FAQ

AI Branch と標準のスプリントブランチの違いは何ですか？

AI Branch は、主に外部 AI、CLI 操作、または自動化スクリプトによる書き込み結果を保存するために使用される特殊なスプリントブランチです。ソースブランチを記録し、マージ前に差分を確認することをユーザーに促します。標準のスプリントブランチは通常、チームメンバー間の日常的なコラボレーションに使用されます。

AI Branch はメインブランチに直接影響しますか？

いいえ。AI Branch 内の変更は、まずその AI Branch に保存されます。関連リソースは、ユーザーが直接マージを実行するか、マージリクエストを作成して承認した後にのみ、ターゲットブランチに入ります。

CLI はどのように AI Branch をスキップしてプロジェクトデータを直接編集できますか？

Apidog プロジェクトで、Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions に移動し、必要に応じてメインブランチ、標準のスプリントブランチ、または一般ブランチの直接編集権限を有効にします。これらの権限が有効になると、外部 AI または CLI 操作は対応するブランチ範囲内に直接書き込むことができます。

AI Branch をマージする際、参照されているリソースは自動的に含まれますか？

いいえ。branch merge と merge-request create はいずれも、明示的に指定されたリソースリストに従って実行されます。エンドポイントがデータモデル、レスポンスコンポーネント、ディレクトリ、またはテストリソースを参照している場合は、マージ前に対応するリソース範囲を確認して追加してください。

変更が完了した後、AI Branch は必ず削除する必要がありますか？

いいえ。削除は必須ではありません。変更がマージ済みであるか不要になっていることを確認した後にブランチをアーカイブし、履歴ブランチの長期的な蓄積を避けるため、チームの規約に従って削除するかどうかを決定することを推奨します。

AI Branch（ベータ）

AI Branch が必要な理由#

AI Branch とは#

ユースケース#

基本ワークフロー#

AI Branch を作成する#

AI Branch 内でリソースを編集する#

ソースブランチからリソースをインポートする#

AI Branch の変更を表示する#

AI Branch をマージする#

AI Branch をアーカイブおよび削除する#

外部 AI 編集権限#

ベストプラクティス#

FAQ#