これは、APIテストおよびAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをApidogがどのように開発したかを共有する10部構成のシリーズです。順番に読むことも、興味のある投稿に直接ジャンプすることもできます。
| タイトル | 焦点 | |
|---|---|---|
| 1 | 私たちは126のMCPツールを構築しました。しかし、それはAgentにとって最高のソリューションではありません | 問題発見 |
| 2 | なぜApidog CLIをゼロから開発したのか | アーキテクチャ開発 |
| 3 | 黄金律：CLIが事実を生成し、モデルが事実に基づいて行動する | コア哲学 |
| 4 | agentHints：CLIにAgentとの対話を教える |
構造化された出力 |
| 5 | SKILL：運用経験をコードとして出荷する | 運用経験 |
| 6 | 数字は嘘をつかない：ツール呼び出し30%減、トークン25%減 | 定量的な結果 |
| 7 | PRDからテストループまで：Apidog CLIによる完全なAgentワークフロー | 実践チュートリアル |
| 8 | AgentツールにとってCI/CD互換性が不可欠である理由 | DevOpsの視点 |
| 9 | AIブランチ：AI Agentによる安全なプロジェクト変更 | セキュリティ層 |
| 10 | Spec-Firstは昨日。Skill-Firstへようこそ。 | ビジョンと未来 |
Agentがプロジェクトリソースを変更する場合、安全性とレビュー可能性が重要です。AIブランチは分離された編集環境を提供し、人間が確認した後でのみ変更をターゲットブランチに取り込みます。
セキュリティの課題
AI AgentがAPI開発やテストに参加すると、CLIコマンド経由でプロジェクトリソースを作成、更新、削除できます。
これは強力ですが、同時にリスクもあります。
| リスク | 起こりうる事態 |
|---|---|
| 予測不能な出力 | Agentが予期しないコンテンツを書き込む |
| フィールドエラー | 誤ったアサーション、不足しているパラメータ |
| スコープクリープ | Agentがタスク範囲を超えてリソースを変更する |
| レビュー履歴なし | 変更が直接メインブランチに反映される |
| チームの混乱 | 共有コラボレーションブランチが突然変更される |
必要なのは、Agentに実プロジェクトで作業させつつ、メインブランチを直接危険にさらさない仕組みです。
AIブランチ：安全層
AIブランチは、外部AIおよびCLI操作のために設計された特殊なスプリントブランチです。
重要な前提は次のとおりです。
Apidog CLIから開始されるすべての編集操作は、デフォルトでAI / AI Agentによって開始されたものとして扱われます。
AIブランチは、AI Agentに分離された編集ブランチを提供します。変更は、人間がレビューしてマージするまでAIブランチに残ります。
AgentがCLI経由で変更を行う
↓
変更はAIブランチに保存される
↓
ユーザーが差分をレビューする
↓
ユーザーがリソースのスコープを確認する
↓
ターゲットブランチにマージする
承認されるまで、メインブランチは変更されません。
AIブランチが必要な理由
Apidog CLIは、エンドポイント、スキーマ、テストシナリオ、テストスイートなどを編集できます。AIがこれらを操作する場合、予測不能な変更や意図しないリソース更新を避けるための境界が必要です。
| AIブランチなし | AIブランチあり |
|---|---|
| Agentが直接メインに書き込む | Agentが分離されたブランチに書き込む |
| 変更がすぐに反映される | 変更はレビューを待つ |
| セーフティネットなし | 人間の確認が必要 |
| 意図しない変更のリスク | スコープを特定のリソースに限定できる |
AIブランチとは？
AIブランチは、特定の制約を持つ特別なスプリントブランチです。
| 特性 | 説明 |
|---|---|
| 分離された編集 | 変更はAIブランチに保存され、メインブランチやソースブランチには影響しない |
| 明確なソース | クライアントで作成できず、CLI/MCPから作成され、ソースブランチを記録する |
| 人間の確認 | 変更はマージ前に確認される |
| 数量制限なし | タスクごとに必要なだけAIブランチを作成できる |
| 自動アーカイブ | 差分がないブランチは24時間ごとに自動的にアーカイブされる |
操作の流れ
| 操作 | 発生場所 |
|---|---|
| AIがエンドポイントを作成する | AIブランチ内 |
| AIがテストシナリオを更新する | AIブランチ内 |
| チームが変更をレビューする | クライアントまたはCLIプレビュー内 |
| ユーザーがマージを承認する | ユーザーの操作 |
| 変更がターゲットブランチに入る | 確認後 |
通常のクライアント内編集は、引き続きプロジェクトメンバーの権限とブランチ保護ルールに従います。
ユースケース
AIブランチは、AIにプロジェクト保守を任せたいが、ブランチ分離と人間の確認は維持したい場合に有効です。
| シナリオ | AIブランチが役立つ点 |
|---|---|
| コードからAPIドラフトを生成する | AIがAIブランチでエンドポイントを作成し、ユーザーがマージ前に確認する |
| APIリソースを一括で整理する | AIがコラボレーションブランチに影響を与えずに、フォルダ、説明、モデルを調整する |
| 自動テストドラフトを生成する | AIがAIブランチでテストシナリオ/ケースを作成し、テスターがレビューする |
| APIドキュメントのギャップを埋める | AIがバグレポートや実装に基づいて不足フィールドを補完する |
| CI/CDでバッチ書き込みを行う | 自動化ワークフローがAIブランチに書き込み、ユーザーのマージを待つ |
基本ワークフロー
典型的なAIブランチ運用は次の5ステップです。
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がリソースを変更する
--branch パラメータでAIブランチを指定する
4. ユーザーが差分をレビューする
apidog merge-request preview
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
よく使うコマンドは次のとおりです。
| コマンド | 目的 |
|---|---|
branch create --type ai |
AIブランチを作成する |
branch list --type ai |
プロジェクト内のAIブランチを表示する |
branch list --type all |
すべてのブランチタイプを表示する |
branch get --type ai |
AIブランチの詳細を表示する |
AIブランチでリソースを編集する
CLIがプロジェクトリソースを書き込む場合は、--branchでAIブランチを指定します。
| リソース | コマンド例 |
|---|---|
| HTTPエンドポイント | apidog endpoint create --project <id> --branch <aiBranchName> --file ./endpoint.json |
| データモデル | apidog schema update <schemaId> --project <id> --branch <aiBranchName> --file ./schema.json |
| テストシナリオ | apidog test-scenario update <scenarioId> --project <id> --branch <aiBranchName> --file ./scenario.json |
| テストスイート | apidog test-suite create --project <id> --branch <aiBranchName> --file ./suite.json |
推奨フローは、スキーマ取得 → 検証 → 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
既存リソースをインポートする
既存のリソースを変更する場合は、まずソースブランチからAIブランチにインポートします。
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クライアントで完全な差分を確認します。
| コマンド | 目的 |
|---|---|
merge-request preview |
候補となる変更をスキャンする |
branch get --type ai |
AIブランチ情報を表示する |
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
| コマンド | 目的 |
|---|---|
branch merge |
保護されていないブランチに直接マージする |
merge-request create |
レビュー用のマージリクエストを作成する |
merge-request approve |
マージリクエストを承認する |
merge-request reject |
マージリクエストを拒否する |
重要：マージコマンドは、明示的に指定されたリソースリストのみを処理します。マージ前に、ディレクトリ、モデル、レスポンスコンポーネント、テストなどの依存関係を確認してください。
アーカイブと削除
変更がマージされた後、または不要になった場合は、AIブランチをアーカイブまたは削除します。
# アーカイブ
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編集権限
| 権限 | 許可されること |
|---|---|
| メインブランチ直接編集 | CLIがメインに直接書き込む（AIブランチをバイパス） |
| 標準スプリントブランチ直接編集 | CLIがスプリントブランチに直接書き込む |
| 一般ブランチ直接編集 | CLIが一般ブランチに直接書き込む |
| AIブランチ直接編集 | CLIがAIブランチに書き込む |
推奨：AIブランチの分離は有効にしておきます。自動化ワークフロー上どうしても必要な場合にのみ、直接編集を有効にしてください。
ベストプラクティス
| プラクティス | 理由 |
|---|---|
| タスクごとに1つのAIブランチ | ユーザー登録API、注文モジュール文書、支払いテストなど、スコープを明確にできる |
| 編集前にインポート | 既存リソースにはpick-toを使い、ソースの混乱を避ける |
| 書き込み前に検証 |
cli-schema validateでAIブランチに書き込む前にエラーを捕捉する |
| マージ前にプレビュー |
merge-request previewまたはクライアントの差分ビューで確認する |
| 明確なマージスコープ | エンドポイント、モデル、ディレクトリ、テストをまとめて確認する |
| 人間のレビューを維持 | API定義やテストスクリプトはマージ前にレビューする |
| 迅速にアーカイブ | マージまたは破棄後、ブランチリストを整理する |
CLI + SKILLワークフローにおけるAIブランチ
AIブランチはCLI + SKILLワークフローと自然に統合できます。
| ステージ | CLI + SKILL + AIブランチ |
|---|---|
| 読み取り | 任意のブランチからendpoint get
|
| 生成 | AgentがJSONを作成する |
| 検証 | ローカルでcli-schema validate
|
| 書き込み | AIブランチにendpoint create --branch <aiBranchName>
|
| レビュー | merge-request preview |
| マージ | ユーザー確認後、branch merge
|
| 検証 | マージされたリソースに対してapidog run
|
ポイントはシンプルです。
すべての書き込み
→ AIブランチ
→ 人間によるレビュー
→ マージ
セキュリティの概要
| 層 | 保護 |
|---|---|
cli-schema validate |
書き込み前に構造上のエラーを捕捉する |
agentHints |
Agentを安全な次のステップに導く |
| 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の詳細をご覧ください。
Top comments (0)