Agent Branch 에이전트 브랜치

해결하려는 문제 #

에이전트는 기계의 속도로 실수하는데, 공유 데이터에는 “해 보고, diff를 보고, 검토하고, 되돌리는” 방법이 없습니다. 병렬로 도는 에이전트끼리 서로의 작업을 밟기도 합니다.

2026년 4월의 사고에서는 한 에이전트가 권한이 지나치게 넓은 토큰으로 9초 만에 프로덕션 볼륨과 같은 볼륨의 백업을 삭제했습니다. 브랜치에만 쓸 수 있었더라면, 삭제가 소프트 삭제였더라면, 스냅샷이 에이전트의 권한 밖에 있었더라면 피해는 훨씬 작았을 것입니다.

동작 방식 #

• 브랜치는 쌉니다(엔진에 따라 이상적으로는 O(1)에 가깝게). 리스는 브랜치 안에서의 쓰기와 대상을 향한 propose를 허용합니다.
• 보호된 트리. 메인 라인은 병합으로만 갱신할 수 있습니다. 유출된 자격 증명으로도 직접 쓸 수 없습니다.
• Agent PR. diff, 의도, 출처(읽기 매니페스트 요약), 검사 결과, 라벨 요약. 검사를 통과하고 정책이 허용하면 자동으로 병합되고, 그렇지 않으면 Human Gate로 갑니다.
• 소프트 삭제. 보호된 트리에서의 삭제는 회수 영역으로 가며 기본적으로 7일간 보관됩니다. 스냅샷은 소유자의 것이며 어떤 리스의 권한도 미치지 않습니다.
• 체크포인트. 이름을 붙인 스냅샷. restore는 파일을 체크포인트로 되돌립니다.
• 병합. 텍스트는 3방향 병합을 쓰고, 그 밖의 파일은 파일 단위로 병합합니다. 충돌하면 멈추며 조용히 덮어쓰지 않습니다. 구조화된 데이터에는 등록된 병합기나 사람이 필요합니다.
• TTL과 쿼터. 브랜치 폭탄을 막기 위한 것입니다.
• 병렬 시도. 하나의 작업에 N개의 브랜치를 열고, 가장 좋은 것을 병합하고 나머지는 회수합니다.

작게 시작하기 #

• Git 브랜치와 worktree, 그리고 Forgejo, Gitea, GitHub의 보호된 main.
• 큰 디렉터리에는 btrfs나 ZFS 스냅샷과 클론을, 오브젝트 스토리지에는 Tigris나 lakeFS 포크를 씁니다.
• “삭제는 회수 영역으로 간다”와 “스냅샷은 소유자의 것이다”를 먼저 제대로 해 두세요. 가장 싸고, 가장 많은 피해를 막아 줍니다.

인터페이스 스케치 #

설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다.

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 <path>

명세가 요구하는 것 #

• 보호된 트리는 병합으로만 갱신할 수 있어야 하며, 어떤 자격 증명으로도 직접 쓸 수 없어야 합니다.
• 병합은 출처(실행, 리스, 주체)를 담은 커밋을 만들어야 합니다.
• 어떤 리스도 스냅샷이나 백업의 삭제를 허용해서는 안 됩니다.
• 보호된 트리에서의 삭제는 소프트 삭제여야 하며, 설정된 기간(기본 7일) 안에는 복구할 수 있어야 합니다.
• 충돌을 조용히 해결해서는 안 됩니다. 병합은 멈추고 보고해야 합니다.
• 브랜치에는 TTL과 쿼터가 있어야 합니다.

빌려 온 것과 새로운 것 #

아래에 나오는 것은 모두 이미 자리 잡은 관행입니다. 새로운 것은 브랜치를 실행과 리스에 묶어서 브랜치가 인가의 단위, 병합이 검토의 단위가 되게 한 것입니다. 브랜치와 스냅샷 자체는 새롭지 않습니다.

• Git worktree
• lakeFS for agents
• Tigris Agent Kit
• Cloudflare Artifacts

솔직한 한계 #

• 브랜치는 NAS 안의 데이터만 보호합니다. 외부 부작용은 되돌리지 못합니다. 이미 보낸 이메일, 이미 호출한 API 같은 것입니다.
• 큰 바이너리 파일과 데이터베이스 파일은 병합하기 어렵습니다.
• 검토 피로는 여전히 생길 수 있으므로 위험이 낮은 경로는 자동으로 병합할 수 있게 하고 승인율을 측정합니다.

열린 질문 #

• 시맨틱 병합기는 어떻게 등록하고 신뢰하는가?
• 바이너리 충돌 시의 상호작용은 어떻게 이루어져야 하는가?

자주 묻는 질문 #

관련 개념 #

• Human Gate (사람 승인 게이트) 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다.
• Agent Home (에이전트 홈) 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일.
• Flight Recorder (플라이트 레코더) 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록.