TL;DR

Shepherd는 에이전트 실행을 내구성 있는 실행 추적으로 저장하고 보류 출력을 사용해 생성물을 격리함으로써 에이전트 실행을 검토·포크·재생·되돌림 가능하게 만든 Python 런타임이다. 이 시스템은 태스크 시그니처를 권한 표면으로 사용해 ReadOnly/ReadWrite 바인딩을 선언하고 macOS Seatbelt와 Linux Landlock에서 syscall 수준으로 강제해 안전한 실행을 보장한다. 내부적으로는 카피온라이트 포크와 높은 KV 캐시 재사용을 통해 반복 재생 비용을 낮추며 README에는 docker commit 대비 약 5배 빠른 포크 성능과 재생 시 약 95%의 캐시 재사용률이 보고되어 있다. 결과적으로 Shepherd는 메타 에이전트가 다른 에이전트를 감독하거나 실험을 반복하는 연구·개발 워크플로에서 가시성·안전성·재현성을 동시에 확보한다. 단점으로는 현재 알파 단계이고 API가 변할 수 있으며 Windows 네이티브 권한 강제가 제한적이라는 점이 있다.

주요 기능

• 에이전트 실행을 불변형 실행 추적으로 기록해 실행 결과와 명령 기록을 영구적으로 보관하고 검증 가능하게 만든다. 기록된 추적은 식별자 기반으로 조회와 재생이 가능하며 보류 출력은 선택적으로 적용하거나 폐기할 수 있다. 이 접근은 변경의 출처를 추적하고 재현 가능한 실험을 제공한다.
• 보류 출력 메커니즘을 통해 에이전트가 생성한 코드나 파일을 워크스페이스에 즉시 반영하지 않고 분리된 위치에 유지해 사용자가 검토한 뒤 적용·선택·폐기하도록 한다. 보류 출력은 실행 결과를 안전하게 격리하며 적용 전에도 실행·검증이 가능하므로 실수로 인한 덮어쓰기를 방지한다. 이로 인해 자동화된 워크플로와 수동 검토를 병행할 수 있다.
• 카피온라이트 포크 방식을 이용해 에이전트와 환경을 분기하며 포크 생성과 재생에서 전체 복사가 아니라 변경된 블록만 기록해 비용을 줄인다. README에 따르면 docker commit 대비 약 5배 빠른 포크 성능을 달성한다는 수치가 제시되며 재생 시 약 95%의 KV 캐시 재사용률을 보인다. 이러한 최적화는 대규모 메타 에이전트 실험에서 저장소와 시간 비용을 낮춘다.

어떻게 동작하는가

Shepherd는 에이전트의 각 실행을 durable한 실행 추적으로 기록하고 보류 출력(retained output)과 결합해 변경을 격리한다. 에이전트가 선언한 시그니처는 권한 표면(permission surface)으로 작동해 ReadOnly/ReadWrite 바인딩을 syscall 수준의 감옥에서 강제하며 macOS에서는 Seatbelt, Linux에서는 Landlock을 사용해 쓰기 권한을 봉인한다. 내부적으로는 카피온라이트 포크를 사용해 포크 생성과 재생을 빠르게 처리하고 재생 시 KV 캐시 재사용을 통해 중복 작업을 줄인다.

해결 문제

Shepherd는 에이전트 실행을 추적·검토·재생·되돌리는 능력이 없어서 발생하는 가시성 부족과 위험을 해결한다. 에이전트가 워크스페이스를 임의로 변경해 버리는 상황을 방지하기 위해 실행 결과를 보류 출력으로 분리하고 사용자가 승인한 경우에만 병합하게 한다. 또한 메타 에이전트가 다른 에이전트를 관찰·포크·최적화·재학습할 수 있도록 재현 가능한 실행 기록과 효율적인 포크 메커니즘을 제공한다.

지금 주목받는 이유

프로젝트는 가역적 실행과 메타 에이전트 감독이라는 현재 관심사와 직결되며 arXiv에 연계된 페이퍼와 함께 공개되어 학술적 근거를 갖추고 있다. 레포지토리가 알파 단계임에도 활발히 개발 중이며 companion 실험 저장소를 통해 결과 재현을 강조해 연구자와 실무자 모두에서 주목을 받았다. 또한 GitHub 스타와 예제·데모가 있어 초기 채택자들이 실험해보기 쉬운 진입점을 제공한다.

차별점

• 시그니처 기반의 권한 선언을 권한 표면으로 사용해 태스크 수준에서 읽기·쓰기 권한을 명시하고 이를 네이티브 syscall jail로 강제한다. 이 방식은 단순 권한 태그를 넘어서 바인딩된 경로에 대한 전사적 제어를 제공하므로 실행 중의 불법적 쓰기가 시스템 콜 단계에서 차단된다. 결과적으로 에이전트 작업의 안전성과 감사 가능성이 높아진다.
• 카피온라이트 포크와 높은 KV 캐시 재사용을 결합해 포크 생성과 재생 비용을 억제한다. README에 기술된 대로 docker commit 대비 약 5배 빠른 포크 성능과 재생 시 약 95%의 캐시 재사용률이 보고되어 반복적 실험에서 시간과 저장 비용을 절감한다. 이 차별점은 많은 포크와 재생을 요구하는 메타 에이전트 워크로드에서 특히 유리하다.
• 보류 출력과 실행 추적을 결합해 실행 결과를 검토 가능한 제안(proposal)으로 다루며 사용자가 수동으로 선택하거나 병합할 수 있도록 워크플로를 분리한다. 이 구조는 자동 생성 코드의 잠재적 위험을 줄이고 인간 검증을 통합한 안전한 자동화 루프를 만든다. 또한 보류 상태에서도 결과를 실행해 검증할 수 있어 실험 반복과 디버깅이 수월하다.

사용 사례

• 자동화된 코드 생성 에이전트가 생성한 변경을 안전하게 검토하고 승인한 뒤에만 실제 저장소에 반영하는 워크플로에서 사용된다. 에이전트가 만든 파일을 보류 출력으로 유지하고 리뷰 후 apply 또는 discard하는 흐름을 통해 실무에서의 실수나 오용을 줄일 수 있다. 재생 기능을 통해 동일한 요청을 반복 검증하거나 다른 파라미터로 비교 테스트를 수행할 수 있다.
• 메타 에이전트가 여러 하위 에이전트의 행동을 관찰하고 정책이나 보상 구조를 최적화하는 연구 환경에서 활용된다. 실행 추적을 통해 하위 에이전트의 의사결정 경로를 캡처하고 포크 및 재생으로 다양한 시나리오를 비교해 실험 결과를 체계적으로 수집할 수 있다. 이로 인해 에이전트 설계의 반복적 개선과 신뢰성 평가가 가능해진다.
• 보안이 중요한 환경에서 권한 선언으로 태스크의 쓰기 범위를 syscall 수준에서 제한해 미리 정의된 바인딩 외의 경로에 대한 변경을 원천 차단하는 데 쓰인다. macOS의 Seatbelt와 Linux의 Landlock을 이용한 네이티브 감옥이 적용되어 런타임에서 강력한 권한 격리가 가능하다. 이는 민감한 리포지토리나 빌드 환경에서 안전한 자동화를 구현할 때 유용하다.

시작하기

Shepherd 설치는 pip install shepherd-ai 한 줄로 가능하며 로컬 개발 시에는 가상환경을 만들고 requirements-dev.txt로 개발 의존성을 설치하는 방식이 권장된다. 워크스페이스 초기화는 shepherd init으로 수행하고 Claude 등 외부 CLI를 쓰는 데모는 shepherd doctor 명령으로 인증 상태를 점검하면 된다. 데모 스크립트를 생성해 shepherd demo write로 받아 실행하고 shepherd run 명령으로 보류 출력과 실행 기록을 조회해 기본 워크플로를 따라 해볼 수 있다.

요구사항

• Python 3.11 이상이 필수 런타임이며 해당 버전 미만에서는 지원하지 않는다.
• 네이티브 권한 강제를 위해 macOS에서는 Seatbelt가 필요하고 Linux에서는 Landlock이 권장되며 이들 감옥은 실행 중 syscall 수준에서 쓰기 권한을 봉인한다.
• Windows는 네이티브 권한 강제가 advisory 수준에 그치므로 공식적으로 지원하지 않으며 필요시 WSL을 사용해야 한다.

벤치마크