# Agent Branch (에이전트 브랜치)

*실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다.*

> **Agent Branch**는 실행마다 쓰기 시 복사 브랜치에서 일하게 합니다. 변경은 검토를 거친 병합(Agent PR)을 통해서만 보호된 메인 라인에 닿으며, 언제든 체크포인트를 찍고 복원할 수 있습니다.

**AN-02** · 적합성 수준: L0 Files · 그룹: 작업

## 해결하려는 문제

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

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

## 동작 방식

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

## 작게 시작하기

- Git 브랜치와 worktree, 그리고 Forgejo, Gitea, GitHub의 **보호된 main**.
- 큰 디렉터리에는 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 <path>
```

## 명세가 요구하는 것

- 보호된 트리는 병합으로만 갱신할 수 있어야 하며, 어떤 자격 증명으로도 직접 쓸 수 없어야 합니다.
- 병합은 출처(실행, 리스, 주체)를 담은 커밋을 만들어야 합니다.
- 어떤 리스도 스냅샷이나 백업의 삭제를 허용해서는 안 됩니다.
- 보호된 트리에서의 삭제는 소프트 삭제여야 하며, 설정된 기간(기본 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 위에 만들 수 있습니다. 차이는 브랜치를 하나의 실행과 하나의 리스에 묶는다는 점입니다. 그러면 “자기 브랜치에만 쓸 수 있다”가 인가 규칙이 되고, 병합이 유일한 검토 지점이 됩니다.

### 브랜치가 모든 사고를 막아 주나요?

아닙니다. NAS 안의 데이터만 보호합니다. 이미 보낸 이메일이나 이미 호출한 외부 API는 브랜치를 롤백해도 되돌려지지 않습니다. 그런 동작은 리스의 `egress`와 Human Gate를 거쳐야 합니다.

### 병합마다 사람이 승인해야 하나요?

아닙니다. 검사를 통과하고, 실행이 외부 콘텐츠를 읽지 않았으며, 삭제나 공유가 걸려 있지 않은 병합은 자동으로 통과할 수 있습니다. 사람이 필요한 것은 몇몇 경우뿐입니다. [Human Gate](https://agentnas.com/ko/concepts/human-gate/)를 참고하세요.

## 관련 개념

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

---

표준 URL: https://agentnas.com/ko/concepts/agent-branch/
최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0