Beads 소개
Beads는 스티브 예기(Steve Yegge)가 공개한 AI 코딩 에이전트를 위한 경량 그래프 기반 이슈 트래커입니다. 이 프로젝트는 단순히 버그나 할 일 목록을 관리하는 도구가 아니라, AI 에이전트가 긴 작업 흐름 속에서 장기 기억(Long-term Memory) 을 유지하고 복잡한 작업을 체계적으로 수행할 수 있도록 돕는 시스템입니다.
현재의 LLM 기반 코딩 에이전트(Claude, Cursor 등)들은 뛰어난 코딩 능력을 갖췄지만, 컨텍스트 윈도우의 제한이나 세션 초기화로 인해 이전의 계획을 잊어버리는 기억 상실(Amnesia) 문제를 겪습니다. Beads는 에이전트가 직접 이슈를 생성, 조회, 수정하고 의존성을 관리할 수 있는 전용 인터페이스를 제공함으로써 이 문제를 해결합니다.
기술적으로 Beads는 별도의 중앙 서버 없이 Git을 백엔드 데이터베이스로 활용합니다. 모든 데이터는 JSONL 포맷으로 저장되어 소스 코드와 함께 버전 관리되며, 로컬에서는 SQLite를 캐시로 사용하여 빠른 성능을 보장합니다. 이는 개발자가 서버 구축 없이 git pull/push 명령어만으로 여러 에이전트나 팀원과 작업 상태를 공유할 수 있게 하는 GitOps 철학의 확장이라고 볼 수 있습니다.
Beads vs. 기존 이슈 관리 도구들(Jira, Linear)
Jira, Linear, GitHub Issues와 같은 기존 도구들은 사람이 웹 인터페이스를 클릭하여 관리하는 것을 전제로 설계되었습니다. 반면 Beads는 AI 에이전트가 CLI 명령어를 통해 프로그램적으로 제어하는 것에 최적화되어 있습니다. 몇 가지 항목으로 비교해보면 다음과 같습니다:
| 항목 | Beads | Jira / Linear / GitHub Issues |
|---|---|---|
| 주 사용 주체 | AI Agent 중심 (CLI/JSON) | Human 중심 (GUI/Web) |
| 데이터 저장소 | Git + JSONL (로컬/분산형) | 중앙 서버 (클라우드 DB) |
| 동기화 방식 | Git push/pull + Agent Mail | REST API / Websocket |
| 설치 및 비용 | 오픈소스 (무료, 로컬 설치) | SaaS (계정, API 토큰 필요) |
| 주요 특징 | 자동 이슈 생성, 의존성 그래프, 오프라인 지원 | 시각적 대시보드, 팀 관리 기능 |
Beads는 AI가 이해하기 쉬운 구조화된 데이터(JSON)를 입출력으로 사용하며, 네트워크 지연 없이 로컬에서 즉시 쿼리가 가능하므로 에이전트의 사고 과정(CoT, Chain of Thought)에 부담을 주지 않습니다.
Beads의 주요 기능
Git 기반의 분산 데이터베이스 (Git as a Database)
Beads의 아키텍처에서 가장 독창적인 점은 Git을 유일무이한 원본(Source of Truth) 으로 사용한다는 것입니다. 즉, 모든 이슈를 .beads/issues.jsonl 파일에 텍스트 형태로 저장하고 관리하는 방식으로 사용합니다.
먼저, 사용자가 bd create 명령을 실행하면 변경 사항들을 로컬의 SQLite 캐시와 JSONL 파일에 즉시 반영합니다. 이후 사용자가 git push 명령을 통해 JSONL 파일을 원격 저장소로 전송하고, 다른 머신에서 git pull을 하면 Beads가 변경된 JSONL을 감지하여 로컬 SQLite를 자동으로 업데이트합니다.
이렇게 Git을 통해 원본 파일을 관리하는 방식을 사용하여 별도의 DB 서버 구축이나 계정 관리가 필요 없으며, 프로젝트의 히스토리와 이슈의 히스토리가 완벽하게 동기화됩니다.
충돌 방지를 위한 해시 ID (Hash-based IDs)
초기 버전의 순차적 ID(예: bd-1)는 분산 환경에서 여러 에이전트가 동시에 작업을 생성할 때 ID 충돌을 일으켰습니다. 이를 해결하기 위해 최신 버전(v0.20.1+)의 Beads는 해시 기반 ID를 도입하여 ID 충돌 문제를 해결했습니다.
Beads의 해시 ID는 Git의 커밋 해시(Commit Hash)처럼 bd-a1b2, bd-f14c와 같은 짧은 해시를 사용합니다. 각 해시값은 기본적으로 4자리로 시작하여, 이슈가 500개를 넘으면 5자리, 1,500개를 넘으면 6자리로 자동 확장됩니다. 이후, 동일한 해시값이 발견되는 등, 충돌이 감지되면 곧바로 해시 ID의 길이를 7~8자리로 늘려 유일성을 보장합니다.
| Hash Length | Total Space | 50% Collision at N Issues | 1% Collision at N Issues |
|---|---|---|---|
| 4 chars | 65,536 | ~304 issues | ~38 issues |
| 5 chars | 1,048,576 | ~1,217 issues | ~153 issues |
| 6 chars | 16,777,216 | ~4,869 issues | ~612 issues |
이러한 해시 ID 길이를 증가시키는 방식은 생일 역설(Birthday Paradox)을 기반으로 설계되어, 분산 환경에서의 충돌 확률을 1% 미만으로 유지할 수 있습니다.
그래프 기반 의존성 관리와 '할 일' 자동 감지
Beads는 이슈를 단순 리스트가 아닌 그래프(Graph) 형태로 관리합니다. 이 때, 에이전트는 4가지 관계 유형을 사용하여 작업의 논리적 흐름을 정의합니다:
- blocks: "이 버그를 고치기 전에는 배포할 수 없음"
- related: "이 작업은 UI 개편과 관련이 있음"
- parent-child: "대규모 리팩토링(부모) -> 모듈 A 분리(자식)"
- discovered-from: "테스트 중 발견된 새로운 버그"
이러한 그래프 구조 덕분에 에이전트는 현재 차단(Block)되지 않아 바로 시작할 수 있는 작업을 자동으로 감지(bd ready)할 수 있습니다. 이는 에이전트가 "다음에 무엇을 해야 하나요?"라고 묻지 않고 스스로 작업을 주도하게 만듭니다.
에이전트 메일 (Agent Mail) 및 초고속 동기화
Git을 통한 동기화는 약 2~5초 가량이 소요되어 실시간 협업에 사용하기에는 다소 느릴 수 있습니다. Beads는 이를 보완하기 위해 Agent Mail 기능을 제공합니다. 이는 동일한 프로젝트 내에서 작동하는 멀티 에이전트 간에 100ms 미만의 지연 시간으로 데이터를 동기화하며, Git 트래픽을 98.5%까지 줄여줍니다. 이를 통해 여러 에이전트가 동시에 작업하더라도 실시간으로 서로의 진행 상황을 파악할 수 있습니다.
기억 압축 (Compaction)
장기 프로젝트 진행 시 수천 개의 이슈가 쌓이면 에이전트의 Context Window에 부담이 됩니다. Beads는 압축(Compaction) 기능을 통해 완료된 오래된 이슈들을 요약하고 정리합니다. 예를 들어, 다음과 같은 방식으로 수행할 수 있습니다:
# LLM을 사용하여 완료된 이슈 분석 및 요약 생성
bd compact --analyze --json
# 요약 내용을 데이터베이스에 적용하여 DB 크기 최적화
bd compact --apply --id bd-42 --summary summary.txt
이러한 과정은 인간의 기억이 시간이 지남에 따라 핵심 내용만 남기고 세부 사항을 잊는 기억 감쇠(Memory Decay) 과정을 모방한 것입니다.
스텔스 모드 (Stealth Mode)
스텔스 모드는 팀 프로젝트에 Beads를 공식 도입하지 않았더라도, 개발자 개인이(혹은 개인 에이전트가) 혼자 사용하고 싶을 때 유용합니다. 이러한 스텔스 모드는 다음과 같은 방식으로 초기화하여 사용할 수 있습니다:
bd init --stealth
이 명령은 Beads가 관리하는 .beads/ 디렉터리와 관련 설정 파일들을 전역 .gitignore 및 .gitattributes에 등록하여, Git 커밋에 포함되지 않도록 처리합니다. 즉, 팀 저장소에 Beads 관련한 파일들을 추가하지 않으면서, 나만의 AI 에이전트용 기억 저장소를 구축할 수 있습니다.
설치 및 시작하기
Beads는 Go 언어로 작성되었으며, 다음과 같은 방식으로 별도의 의존성 없이 설치 가능합니다:
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
Windows (PowerShell)
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
Node.js 환경 (npm)
npm install -g @beads/bd
에이전트 온보딩
설치 후 프로젝트 루트에서 초기화한 뒤, 에이전트 설정 파일(예: AGENTS.md)에 다음 내용을 추가하여 에이전트가 스스로 Beads를 사용하도록 안내합니다.
bd init
echo "BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instructions" >> AGENTS.md
Beads 사용 예시
Beads GitHub 저장소의 examples/ 디렉토리에는 Beads를 AI 에이전트와 실제 개발 워크플로우에 통합하는 방법에 대한 예시들을 제공하고 있습니다. Beads는 단순한 CLI 도구가 아니라, AI 코딩 에이전트의 기억 시스템(memory system) 으로 설계되었기 때문에, 다양한 언어·환경·프로젝트 구조에 맞춰 유연하게 통합할 수 있습니다.
여기서 제공하는 예제들은 Beads의 핵심 개념인 자동 이슈 생성, 종속성 관리, 분산 데이터베이스 동기화 등을 실제 코드로 구현한 샘플입니다. Python, Bash, Git Hooks, Claude 통합 등 여러 접근법을 통해 Beads를 에이전트 워크플로우에 어떻게 삽입할 수 있는지 배울 수 있습니다.
이 중 Python과 Bash에서 Beads를 어떻게 사용하는지를 보여주는 에이전트 통합 예시는 아래와 같습니다. Beads 저장소에서 제공하는 전체 예시 목록은 examples/README.md 문서를 참고해주세요.
에이전트 통합 예시: Python Agent
Beads의 핵심적인 CLI 명령어들(bd ready, bd update, bd close)을 Python 코드에서 호출하는 간단한 예시입니다. 이 에이전트는 다음과 같은 기본 로직을 수행합니다:
bd ready --json으로 현재 수행 가능한 작업을 조회- 가장 높은 우선순위 작업을 선택
- 해당 작업을 in_progress로 변경
- 가상의 “작업 수행” 후, 상태를 done으로 갱신
- 새롭게 발견된 문제를 자동으로 bd create 명령을 통해 등록
예를 들어, AGENT_MAIL_EXAMPLE.md 예제에서는 Agent Mail 시스템을 활용한 멀티 에이전트 협업 패턴을 보여줍니다. 이 예제에서는 서로 다른 에이전트가 메시지 큐 형태로 작업 상태를 교환하며 병렬적으로 진행할 수 있도록 설계되어 있습니다.
에이전트 통합 예시: Bash Agent
단일 Bash 스크립트로 구성된 Beads 워크플로우 예시로, 이 에이전트는 쉘 명령어를 통해 다음과 같은 과정을 자동으로 수행합니다:
# 준비된 작업 찾기
bd ready --json | jq '.[0].id' > current_task.txt
# 작업 시작
bd update $(cat current_task.txt) --status in_progress
# 새로운 이슈 발견 시
bd create "Discovered bug" --json
# 완료 후 상태 변경
bd close $(cat current_task.txt) --reason "Done"
이러한 Bash Agent 예제는 단순하지만, LLM 기반 코드 어시스턴트가 CLI를 호출하여 자기 주도적 이슈 관리를 하는 기본 패턴을 사용자가 명확히 이해할 수 있도록 돕습니다.
빠른 시작 (Quick Start)
Beads의 예시들은 다음과 같은 방식으로 직접 실행하여 작동 방식을 이해할 수 있습니다:
# Python Agent 예시 실행
cd examples/python-agent
python agent.py
# Bash Agent 예시 실행
cd examples/bash-agent
./agent.sh
# Git Hooks 설치 예시 실행
cd examples/git-hooks
./install.sh
라이선스
Beads 프로젝트는 MIT 라이선스로 공개 및 배포 되고 있습니다. 상업적 이용 및 수정이 자유롭습니다.
Beads 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 