Beads

Dolt 기반 저장소

Dolt를 사용해 셀 단위 머지, 네이티브 브랜치, Dolt 리모트를 통한 동기화를 제공하는 버전 관리 SQL 데이터베이스를 사용합니다. 임베디드 모드와 외부 dolt sql-server에 연결하는 서버 모드 두 가지를 지원하며, 모드 간 백업과 마이그레이션은 `bd backup`, 공간 확보는 `bd prune`/`bd purge`로 수행합니다.

에이전트 친화 인터페이스

JSON 출력, 의존성 추적, 자동 ready 작업 감지를 제공해 코딩 에이전트의 후속 행동을 명확하게 안내합니다. 해시 기반 ID(`bd-a1b2` 등)는 다중 에이전트·다중 브랜치 환경에서 머지 충돌을 방지합니다.

컴팩션과 메시지

오래된 닫힌 작업을 의미적으로 요약해 컨텍스트 윈도우를 절약하는 ‘memory decay’ 기능을 제공합니다. 메시지 이슈 타입은 스레딩(`–thread`), 짧은 수명 주기, 메일 위임을 지원합니다.

그래프 링크와 계층

`relates-to`, `duplicates`, `supersedes`, `replies-to` 같은 그래프 링크로 지식 그래프를 구성하며, `bd-a3f8`, `bd-a3f8.1`, `bd-a3f8.1.1`처럼 상위 이슈 아래에 작업과 하위 작업을 두는 계층적 ID도 지원합니다.

설치와 기본 사용

Windows 환경에서는 PowerShell이나 명령 프롬프트를 열어 다음 Winget 명령으로 설치할 수 있습니다.

• winget install --id GasTownHall.Beads --exact

macOS/Linux에서는 Homebrew로 `brew install beads`를, Node.js 환경에서는 `npm install -g @beads/bd`를 사용할 수 있습니다. 그 외 플랫폼은 공식 문서의 설치 스크립트, go install, 소스 빌드, Arch AUR 등 안내를 따르면 됩니다.

설치 후 사용자의 프로젝트 디렉터리에서 `bd init`을 실행하면 임베디드 Dolt 데이터베이스가 초기화되며, 기본 동작으로 `AGENTS.md`가 생성·갱신되어 에이전트가 beads 워크플로를 인식할 수 있게 됩니다. `–skip-agents` 또는 `–stealth` 옵션으로 이 동작을 건너뛸 수 있으며, 지원되는 통합 목록은 `bd setup –list`로 확인합니다.

자주 사용하는 명령

• bd ready: 차단 작업이 없는 ready 상태 작업을 나열합니다.
• bd create "Title" -p 0: P0 우선순위 작업을 새로 생성합니다.
• bd update <id> --claim: 담당자와 in_progress 상태를 원자적으로 설정해 작업을 차지합니다.
• bd dep add <child> <parent>: 작업 간 의존성(blocks, related, parent-child)을 연결합니다.
• bd show <id>: 작업 상세와 감사 로그를 확인합니다.
• bd prime: 에이전트에 워크플로 컨텍스트와 영속 메모리를 출력합니다.
• bd remember "insight": 이후 bd prime이 주입할 프로젝트 메모리를 저장합니다.

저장 모드 선택

기본 임베디드 모드는 데이터가 `.beads/embeddeddolt/`에 저장되며 단일 작성자로 동작합니다. 동시 다중 작성자가 필요하면 bd init --server로 외부 dolt sql-server에 연결해 데이터를 `.beads/dolt/`에 둘 수 있습니다.

Git 없이 사용하기

Dolt 데이터베이스가 진실의 원천이므로 Git 없이도 동작합니다. BEADS_DIR=/path/to/your/project/.beads로 데이터베이스 위치를 지정하고 bd init --quiet --stealth를 실행하면 Git 훅 설치와 Git 연산을 비활성화한 채 모든 핵심 명령을 사용할 수 있어 비-Git VCS, 모노레포 하위 디렉터리, CI/CD, 일회성 평가 환경에 적합합니다.

활용 예시

에이전트가 bd create로 작업을 등록하고 bd dep add로 의존성을 연결하면, 이후 bd ready가 차단 작업이 없는 작업만 골라 다음 행동으로 제시합니다. 에이전트는 bd update <id> --claim로 작업을 차지해 bd close <id>로 완료 처리하며, 작업 흐름은 의존성 그래프로 자동 갱신됩니다. 다중 머신 환경에서는 bd dolt push/bd dolt pull로 refs/dolt/data 브랜치를 통해 변경 사항을 다른 머신과 에이전트에 공유할 수 있고, bd remember로 남긴 인사이트는 다음 세션의 bd prime을 통해 에이전트 컨텍스트에 다시 주입됩니다.

제한 및 확인 사항

스키마 보호를 위해 bd는 열기 시점에 데이터베이스 스키마 버전을 검사합니다. 더 새로운 바이너리가 스키마를 마이그레이션한 데이터베이스를 오래된 바이너리가 열면 ‘schema version mismatch’ 오류와 함께 종료되며, 이 경우 최신 릴리스 설치 또는 안내된 재빌드 절차가 요구됩니다. 만약 해당 마이그레이션이 추가적·안전하다고 판단되면 BD_IGNORE_SCHEMA_SKEW=1 또는 --ignore-schema-skew로 보호 장치를 우회할 수 있습니다. 또한 v1.2.2는 v1.2.0/v1.2.1에 포함됐던 일부 기능(워크 리스, 이벤트 저널, 동기화 페더레이션, HTTP API 서버, 출처 이벤트)을 포함하지 않으며, .beads/issues.jsonl은 뷰어와 호환을 위한 익스포트이지 진실의 원천이나 백업이 아닙니다.