# Agent Branch (エージェント・ブランチ) *実行ごとに、コピーオンライトのブランチで作業します。メインに届くのは、レビューを経たマージだけです。* > **Agent Branch** は、実行ごとにコピーオンライトのブランチで作業させる仕組みです。変更が保護されたメインラインに届くのは、レビューを経たマージ（Agent PR）だけで、チェックポイントを作って、いつでも元に戻せます。 **AN-02** · 準拠レベル: L0 Files · グループ: 作業 ## 解決する課題 エージェントは機械の速さで間違えますが、共有データには「試して、差分を見て、レビューして、元に戻す」手段がありません。並行して動くエージェント同士が、互いの作業を踏みつけることもあります。 2026 年 4 月の事故では、あるエージェントが権限の広すぎるトークンを使い、本番のボリュームと、同じボリュームにあったバックアップを 9 秒で削除しました。書き込めるのがブランチだけで、削除がソフトで、スナップショットがその権限の外にあれば、被害ははるかに小さく済んだはずです。 ## 仕組み - **ブランチは安価です**（エンジンによりますが、理想的には O(1) に近いコスト）。リースが許すのは、**ブランチの中への** 書き込みと、ターゲットへの `propose` です。 - **保護ツリー。** メインラインはマージでしか更新できません。認証情報が漏れても、そこへ直接は書き込めません。 - **Agent PR。** 差分、意図、出どころ（読み取りマニフェストの要約）、チェック結果、ラベルの要約を伴います。チェックに通り、ポリシーが許せば自動でマージされ、そうでなければ [Human Gate](https://agentnas.com/ja/concepts/human-gate/) に回ります。 - **ソフト削除。** 保護ツリーでの削除は回収エリアに移り、既定で 7 日間保持されます。スナップショットは所有者のもので、**どのリースの権限も及びません**。 - **チェックポイント。** 名前つきのスナップショット。`restore` でファイルをチェックポイントまで戻せます。 - **マージ。** テキストは 3 方向マージ、それ以外のファイルはファイル単位でマージします。競合したら止まり、**黙って上書きすることはありません**。構造化データには、登録されたマージャーか、人間が必要です。 - **TTL とクォータ。** ブランチの爆発を防ぎます。 - **並行の試行。** 1 つのタスクに N 本のブランチを開き、最良のものをマージして、残りは回収します。 ## 小さく始める - Git のブランチと worktree に、Forgejo、Gitea、GitHub の **保護されたメイン** を組み合わせます。 - 大きなディレクトリには btrfs や ZFS のスナップショットとクローン、オブジェクトストレージには Tigris や lakeFS のフォークを使います。 - まず「削除は回収エリアへ」と「スナップショットは所有者のもの」を正しく実現します。最も安く済み、最も多くの被害を防げます。 ## インターフェースのスケッチ 説明用の例です。フィールド名は仕様 v0.3 までに変わる可能性があります。 *nas cli* ```bash nas branch create cleo/release-notes --from main --ttl 48h nas checkpoint create before-refactor nas propose --into main --checks links,schema nas restore before-refactor nas trash list # recycle area, kept 7 days by default nas trash restore ``` ## 仕様が求めること - 保護ツリーは、マージによってのみ更新できなければならない。どの認証情報も、直接書き込んではならない。 - マージは、出どころ（実行、リース、プリンシパル）を持つコミットを生成しなければならない。 - スナップショットやバックアップの削除を許すリースがあってはならない。 - 保護ツリーでの削除はソフトでなければならず、設定された期間（既定では 7 日間）内なら復元できなければならない。 - 競合を黙って解決してはならない。マージは止まって報告しなければならない。 - ブランチには TTL とクォータがなければならない。 ## 借りたものと、新しいもの 以下はすべて確立された慣行です。**新しいのは、** ブランチを **実行とリース** に結びつけることで、ブランチが認可の単位、マージがレビューの単位になる点です。ブランチやスナップショットそのものは新しくありません。 - [Git worktree](https://git-scm.com/docs/git-worktree) - [lakeFS for agents](https://lakefs.io/agentic-ai/) - [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/) - [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) ## 正直な限界 - ブランチが守るのは NAS の内側のデータだけです。**外部への副作用は元に戻せません**。すでに送ったメールや、すでに呼び出した API などです。 - 大きなバイナリファイルやデータベースファイルは、マージが困難です。 - レビュー疲れは起こりえます。そのため、低リスクのパスは自動でマージしてよいことにして、承認率を計測します。 ## 未解決の問い - セマンティックなマージャーは、どう登録し、どう信頼するのか。 - バイナリの競合に対するやり取りは、どうあるべきか。 ## よくある質問 ### Git のブランチと何が違うのですか？ 仕組みの上では魔法ではなく、Git の上に作れます。違いは、ブランチを 1 回の実行と 1 つのリースに結びつけることで、「自分のブランチにしか書けない」が認可のルールになり、マージが唯一のレビュー地点になることです。 ### ブランチがあれば、事故はすべて防げますか？ 防げません。守るのは NAS の内側のデータだけです。送信済みのメールや呼び出し済みの外部 API は、ブランチを戻しても元に戻りません。そうした操作は、リースの `egress` と Human Gate を通すべきです。 ### マージのたびに、人間の承認が必要ですか？ 必要ではありません。チェックに通り、その実行が外部コンテンツを読んでおらず、削除や共有を含まないマージは、自動で通せます。人間が必要なのはごく一部の場合だけです。[Human Gate](https://agentnas.com/ja/concepts/human-gate/) を参照してください。 ## 関連するコンセプト - [Human Gate (ヒューマン・ゲート)](https://agentnas.com/ja/concepts/human-gate/): 元に戻せない、外へ出る、権限を広げる操作の前にだけ現れ、実際の差分を見せます。 - [Agent Home (エージェント・ホーム)](https://agentnas.com/ja/concepts/agent-home/): ロールごとのディレクトリ。履歴つきで、普通のファイルのまま持ち出せます。 - [Flight Recorder (フライトレコーダー)](https://agentnas.com/ja/concepts/flight-recorder/): 実行ごとに、ハッシュでつながれた記録を残します。実行が何を読んだかも含みます。 --- 正規 URL: https://agentnas.com/ja/concepts/agent-branch/ 更新日: 2026-11-11 · 仕様ドラフト v0.2 · CC BY 4.0