apidog-branch

ブランチ連携とAIによる書き込み

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのドメインスキルが矛盾する場合は、現在のCLIヘルプとこのスキルを正としてください。

正確な引数は、常に現在のCLIヘルプで確認してください。このスキルでは、誤用されやすいブランチのコンテキスト、AIブランチ、pick-to、書き込み権限、保護されたブランチ、マージ確認に関するルールを補足します。ブランチに書き込んだ後は、同じ --branch を指定して読み戻し、検証してください。デフォルトブランチの表示からリソースの有無を判断しないでください。

使用する場面

• ユーザーが --branch を指定する場合、またはブランチ上での操作を依頼する場合。
• ブランチの作成、表示、更新、アーカイブ、削除を行う場合。
• AIブランチを作成し、ソースブランチのリソースを変更する場合。
• ソースブランチのリソースをAIブランチに取り込む場合。
• ブランチをマージする場合、またはマージリクエストを作成・承認する場合。
• AIの書き込み権限に関する制限に遭遇した場合。

コマンドのエントリーポイント

• ブランチ管理：apidog branch --help
• マージリクエスト：apidog merge-request --help
• 通常、リソースコマンドは --branch <branchName> をサポートしています。クエリ、作成、更新、テスト実行では、同じブランチのコンテキストを維持してください。

まず変更戦略を決める

ブランチに書き込む前に、ユーザーが希望する戦略を確認してください。

• 対象ブランチを直接編集する：ユーザーが直接変更を明示的に許可しており、対象ブランチが保護されておらず、権限による制限もない場合に適しています。
• AIブランチ経由で編集する：AIが生成したAPI、テストケース、テストシナリオ、または設定の変更に適しています。また、対象ブランチが保護されている場合、外部AIによる直接書き込みが無効な場合、またはマージ前に変更を分離して検証したい場合にも適しています。

書き込みを開始する前に、以下を確認してください。

• プロジェクトID。
• ソースブランチと対象ブランチ。
• 変更するリソースの範囲。
• マージリクエストの作成または後でのマージが許可されているかどうか。

AIブランチのフロー

AIブランチを使うと、AIによる変更を分離し、ソースブランチへの不要な変更を防げます。

Confirm source branch and target change
  -> create AI branch
  -> pick-to existing resources
  -> modify on AI branch
  -> validate with get/run/report
  -> preview merge-request
  -> after user confirmation, create merge-request or merge

標準的な手順：

1. AIブランチの作成時に、--from <sourceBranchName> でソースを指定します。
2. ai/YYYYMMDD-from-source-feature のような、分かりやすい名前を付けます。例：ai/20260312-from-main-userRegister。
3. 既存のソースブランチのリソースを変更する前に、branch pick-to でそのリソースをAIブランチに取り込みます。新しいリソースの場合、pick-toは不要です。
4. AIブランチ上で変更、クエリ、検証を行う際は、必ず --branch <aiBranchName> を指定します。
5. get、run、ローカルレポート、クラウドレポートの確認など、リソースの種類に応じて検証します。
6. マージ前に merge-request preview を実行し、変更の影響をユーザーに確認してもらいます。
7. 確認後、マージリクエストを作成するか、マージします。保護されたmainブランチの場合は、マージリクエストを優先してください。

AIブランチに関する注意事項：

• AIブランチは空の状態で作成され、ソースブランチの全リソースが自動的にコピーされるわけではありません。
• branch get が type: SPRINT と isAiBranch: true を返す場合がありますが、これは操作時に --type sprint を使うべきという意味ではありません。AIブランチの操作では、引き続き現在のヘルプに従い、必要な場合は --type ai を使用してください。

ブランチパラメーターのルール

• ブランチ名を優先してください：--branch <branchName>。
• 数値のbranchIdも使用できる場合がありますが、ログや問題の診断ではブランチ名のほうが分かりやすくなります。
• 1つのタスク内では、クエリ、作成、更新、テスト実行に同じブランチのコンテキストを使い、誤ってmain／デフォルトブランチからリソースを探さないようにしてください。

Pick-Toのルール

• --type ai を必ず指定してください。
• mainまたは通常のsprintブランチからAIブランチへの取り込みのみサポートしています。
• mainへの取り込みはできません。
• AIブランチをソースブランチとして使用することはできません。
• エンドポイントと一緒にエンドポイントケースを取り込むには、--include-endpoint-cases を使用してください。

書き込み権限のルール

• main、sprint、regular ブランチでは、外部 AI の編集権限を有効にする必要がある場合があります。
• よくあるエラーには Automation caller branch required があります。
• AI ブランチの作成には成功しても、AI ブランチの編集が無効になっている場合、AI ブランチへのコンテンツの書き込みは失敗することがあります。
• 書き込みが制限されている場合、自動的に方針を切り替えないでください。直接編集権限を有効にするか、AI ブランチを使用するかをユーザーに確認してください。
• 対象の main ブランチが保護されている場合は、merge-request preview/create を優先してください。branch merge を直接実行しないでください。

違反してはならないルール

1. ユーザーの確認なしに AI ブランチを作成しないでください。
2. 既存のソースブランチのリソースを AI ブランチで変更する前に、必ず pick-to を使用してください。
3. ブランチ単位のタスクでは --branch <branchName> を省略しないでください。
4. ユーザーの確認なしに、マージ、マージリクエストの作成、またはマージリクエストの承認を行わないでください。
5. 明示的に依頼されない限り、ブランチを削除またはアーカイブしないでください。
6. Automation caller branch required が表示された場合は、処理を停止し、権限の方針をユーザーに選んでもらってください。AI ブランチを自動的に作成したり、切り替えたりしないでください。

よくある問題からの復旧

症状	対応
ブランチを指定せずに get を実行するとリソースが見つからない	--branch <branchName> を付けて再試行する
AI ブランチでソースリソースが見つからない	先に branch pick-to を使用する
ブランチの状態に件数が表示されるのに AI ブランチのページが空	リソースがインポートされたと思い込まないでください。AI ブランチでも pick-to が必要です
ブランチで Run config が 404 を返す	大文字・小文字、エンドポイント、環境、ブランチがすべて存在することを確認してから、apidog-cli-checkup に切り替える
保護されたブランチによってマージがブロックされる	代わりに merge-request を使用する