Logo
Published on

Beads (bd) 프로젝트 분석 리포트 / AI 에이전트를 위한 분산 그래프 이슈 트래커

Authors

This article is mostly written by Claude Code

Beads (bd) 프로젝트 분석 리포트

분석일: 2026-04-13 (초판: 2026-03-29) 리포지토리: https://github.com/steveyegge/beads 최신 버전: v1.0.0 (2026-04-02)


목차

  1. 프로젝트 개요
  2. 기술 스택
  3. 프로젝트 구조
  4. 아키텍처
  5. 데이터 모델
  6. 의존성 & 그래프 시스템
  7. 메모리 컴팩션 (Semantic Compaction)
  8. 동기화 시스템
  9. Wisps & Molecules
  10. v1.0.0 신규 기능
  11. 프로젝트 개발 히스토리
  12. 핵심 파일 레퍼런스
  13. 주요 설계 결정 요약
  14. USE CASE: Epic 분해

1. 프로젝트 개요

**Beads (bd)**는 AI 에이전트를 위한 분산 그래프 이슈 트래커입니다. Dolt(버전 관리 SQL 데이터베이스)를 기반으로 코딩 에이전트가 구조화된 메모리를 유지하고, 복잡한 의존성을 관리하며, 장기 태스크(long-horizon task)를 수행할 수 있도록 설계되었습니다.

v1.0.0에서 프로덕션 안정성 마일스톤에 도달했으며, 빠른 반복(rapid iteration) 단계에서 안정적 운영 단계로 전환되었습니다.

핵심 철학

  • 마크다운 플랜 대체: 비구조적인 마크다운 계획을 의존성 인식 그래프로 대체
  • Zero Framework Cognition (ZFC): 코드는 단순한 오케스트레이션, 지능은 AI 모델에 위임
  • 분산 우선: 중앙 조정 없이 다중 에이전트/브랜치에서 동시 작업 가능
  • 에이전트 최적화: 모든 커맨드가 --json 출력 지원, 프로그래밍 방식 사용에 최적화

주요 기능

기능설명
Dolt 기반 스토리지버전 관리 SQL, 셀 단위 머지, 네이티브 브랜치
임베디드 Dolt (기본)외부 서버 없이 인프로세스로 동작 (v1.0.0~)
해시 기반 IDbd-a1b2 형식으로 머지 충돌 방지
의존성 그래프19+ 관계 타입, 자동 준비 상태 감지
시맨틱 컴팩션AI로 오래된 이슈를 요약하여 컨텍스트 윈도우 절약
FederationP2P 동기화, 암호화된 자격 증명
Molecules/Wisps템플릿 기반 워크플로우 + 로컬 전용 실행 트레이스
원자적 배치 처리bd batch로 다중 작업을 단일 트랜잭션으로 실행 (v1.0.0~)
그래프 기반 생성bd create --graph로 전체 의존성 트리를 한 번에 생성 (v1.0.0~)

2. 기술 스택

항목기술
언어Go 1.25.8 (CGO 필수 — 임베디드 모드)
CLI 프레임워크Cobra (github.com/spf13/cobra)
데이터베이스Dolt (임베디드) via github.com/dolthub/driver v1.84.1
AI APIAnthropic SDK (github.com/anthropics/anthropic-sdk-go v1.34.0)
ObservabilityOpenTelemetry (go.opentelemetry.io/otel)
TUICharm Huh, Glamour, Lipgloss v2
테스트testcontainers-go, rsc.io/script (scripttest)
외부 연동GitHub, GitLab, Linear, Jira, Azure DevOps, Notion API
빌드Makefile + GoReleaser + Zig cross-compilation
플랫폼macOS, Linux, Windows, FreeBSD

3. 프로젝트 구조

beads/
├── cmd/bd/                  # CLI 커맨드 레이어 (402+ 파일, 100+ 서브커맨드)
│   ├── main.go              # 진입점 (36,000+)
│   ├── create.go            # 이슈 생성 (--parent, --graph 포함)
│   ├── ready.go             # 준비된 작업 조회 (auto-ready)
│   ├── dep.go               # 의존성 관리
│   ├── graph.go             # 그래프 로딩/시각화
│   ├── graph_apply.go       # 원자적 그래프 생성 (v1.0.0~)
│   ├── batch.go             # 원자적 배치 처리 (v1.0.0~)
│   ├── rules.go             # 규칙 감사/컴팩트 (v1.0.0~)
│   ├── ado.go               # Azure DevOps 연동 (v1.0.0~)
│   ├── context_cmd.go       # 백엔드 컨텍스트 진단 (v1.0.0~)
│   ├── compact.go           # 시맨틱 컴팩션
│   └── testdata/*.txt       # 스크립트 기반 테스트
├── internal/
│   ├── storage/
│   │   ├── storage.go       # 스토리지 인터페이스 정의
│   │   ├── hook_decorator.go # 스토리지 훅 데코레이터 (v1.0.0~)
│   │   ├── dolt/            # Dolt 구현체
│   │   │   ├── schema.go    # DB 스키마 (v11, was v9)
│   │   │   ├── store.go     # DoltStore 구조체
│   │   │   ├── issues.go    # 이슈 CRUD
│   │   │   ├── dependencies.go  # 의존성 CRUD
│   │   │   └── queries.go   # computeBlockedIDs 등 핵심 쿼리
│   │   ├── schema/          # 통합 스키마 패키지 (SSOT, v1.0.0~)
│   │   ├── embeddeddolt/    # 임베디드 Dolt (VC, 동기화, Federation)
│   │   └── issueops/        # 공용 이슈 연산 (blocked, cycles, compaction, child_id)
│   │
│   ├── types/               # 핵심 도메인 타입 (Issue, Dependency, Status 등)
│   │   ├── types.go         # 데이터 구조체 정의
│   │   └── id_generator.go  # 해시 기반 ID 생성
│   │
│   ├── beads/               # 핵심 도메인 로직 (DB 탐색, 부트스트랩)
│   ├── compact/             # 시맨틱 컴팩션 (compactor.go, haiku.go)
│   ├── config/              # 설정 시스템
│   ├── hooks/               # Git hooks 통합
│   ├── molecules/           # Molecule 워크플로우
│   ├── formula/             # 규칙 엔진
│   ├── query/               # 쿼리 DSL
│   ├── git/                 # Git 연산
│   ├── telemetry/           # OpenTelemetry 계측 (풀 메트릭 추가)
│   ├── {github,gitlab,linear,jira,ado,notion}/  # 외부 서비스 연동
│   └── testutil/            # 테스트 유틸리티
├── docs/                    # 55+ 마크다운 문서
├── examples/                # 14개 예제 프로젝트
├── scripts/                 # 25개+ 유틸리티 스크립트 (bump-version.sh, release.sh 등)
├── website/                 # 문서 웹사이트
├── beads.go                 # 공개 API
├── beads_cgo.go             # CGO 빌드: 임베디드 + 서버 모드 (v1.0.0~)
├── beads_nocgo.go           # Non-CGO 빌드: 서버 모드만 (v1.0.0~)
├── AGENT_INSTRUCTIONS.md    # 에이전트 운영 지침 (v1.0.0~)
├── Makefile                 # 빌드 시스템
├── .goreleaser.yml          # 릴리스 설정
└── .github/workflows/       # CI/CD (9개+ 워크플로우)

4. 아키텍처

4.1 3계층 설계 (v1.0.0 업데이트)

┌─────────────────────────────────────────────────────────┐
CLI Layer (cmd/bd/)Cobra 커맨드 → --json 지원 → 직접 DB 접근               │
└────────────────────────┬────────────────────────────────┘
                         v
┌─────────────────────────────────────────────────────────┐
Hook Decorator Layer (v1.0.0~)HookFiringStore: 모든 뮤테이션에 훅 자동 발화            │
│  on_create, on_update, on_close 등 이벤트 전파            │
└────────────────────────┬────────────────────────────────┘
                         v
┌─────────────────────────────────────────────────────────┐
Dolt Database Layer│  버전 관리 SQL │ 셀 단위 머지 │ 자동 커밋               │
.beads/embeddeddolt/ (임베디드, 기본)│  또는 dolt sql-server (서버 모드)└────────────────────────┬────────────────────────────────┘
                    Dolt push/pull
                   (또는 Federation)
                         v
┌─────────────────────────────────────────────────────────┐
Remote (DoltHub, S3, GCS, Git)│  셀 단위 머지로 충돌 자동 해결                            │
└─────────────────────────────────────────────────────────┘

4.2 Write Path (쓰기 경로)

bd create "New feature"
CLI 파싱 (Cobra)
HookFiringStore.CreateIssue() [hook_decorator.go — 훅 발화]
DoltStore.CreateIssue() [internal/storage/dolt/issues.go]
  → issueops.CreateIssueInTx() [SQL INSERT]
Wisp 여부 확인
    ├─ ephemeral/no_history → wisps 테이블 (DOLT_COMMIT 생략)
    └─ 일반 이슈 →
         CALL DOLT_ADD('issues', 'events')
         CALL DOLT_COMMIT('-m', 'bd: create bd-xyz', '--author', ...)
         캐시 무효화
         on_create 훅 발화 (트랜잭션 커밋 후)

핵심: 모든 쓰기 작업이 자동으로 Dolt 커밋을 생성합니다. 트랜잭션은 withRetryTx()로 처리되며, 변경된 테이블만 선택적으로 스테이징합니다. v1.0.0부터 HookFiringStore 데코레이터가 CLI가 아닌 스토리지 계층에서 훅을 발화하여, 모든 뮤테이션 경로에서 훅이 일관되게 실행됩니다.

4.3 Read Path (읽기 경로)

bd ready → SQL SELECT from ready_issues view → 로컬 Dolt DB 직접 쿼리

네트워크 없이 로컬 DB를 직접 조회합니다. ready_issuesblocked_issues 뷰가 사전 정의되어 있습니다.

4.4 Embedded vs Server 모드

항목Embedded 모드 (v1.0.0 기본)Server 모드
연결인프로세스 Dolt 엔진TCP MySQL 프로토콜 (dolt sql-server)
동시성단일 writer (배타적 파일 잠금)다중 writer
데이터 위치.beads/embeddeddolt/.beads/dolt/
서버 프로세스없음PID: .beads/dolt-server.pid
용도단독 개발자, CI/CD (권장)오케스트레이터, 팀
빌드 요구CGO 활성화 (beads_cgo.go)CGO 불필요 (beads_nocgo.go)

v1.0.0부터 macOS에서 네이티브 CGO 빌드로 임베디드 모드가 기본 활성화됩니다. Non-CGO 빌드에서는 서버 모드만 사용 가능하며 명확한 에러 메시지가 제공됩니다.

설정 우선순위: 환경변수 > metadata.json > config.yaml > 기본값

4.5 스토리지 추상화

// 핵심 인터페이스 (internal/storage/storage.go)
type Storage interface {
    CreateIssue(ctx, issue, actor)
    GetIssue(ctx, id)
    UpdateIssue(ctx, id, updates, actor)
    GetReadyWork(ctx, filter)
    GetBlockedIssues(ctx, filter)
    AddDependency(ctx, dep, actor)
    RunInTransaction(ctx, commitMsg, fn)
    // v1.0.0 추가
    SlotSet(ctx, issueID, key, value)     // per-issue 메타데이터
    SlotGet(ctx, issueID, key)
    SlotClear(ctx, issueID, key)
    ListWisps(ctx, filter)                // 임시 wisp 목록
    ReopenIssue(ctx, id, actor)           // 이슈 재개
    UpdateIssueType(ctx, id, newType)     // 타입 변경
    // ...
}

type DoltStorage interface {
    Storage
    VersionControl    // Branch, checkout, commit history
    HistoryViewer     // AS OF, dolt_history_* tables
    RemoteStore       // Push, pull, remote management
    SyncStore         // High-level peer sync
    FederationStore   // Multi-repo support
    CompactionStore   // History compaction
    // ...
}

// v1.0.0 신규: Hook Decorator
type HookFiringStore struct {
    inner DoltStorage
}
// CreateIssue → inner.CreateIssue + on_create 훅 발화
// UpdateIssue → inner.UpdateIssue + on_update 훅 발화
// 트랜잭션 내에서는 커밋 후에만 훅 발화, 롤백 시 발화하지 않음

구현체 DoltStore*sql.DB (MySQL 프로토콜 연결), 캐시 (blockedIDs, customStatus 등), 회로 차단기(circuit breaker — host:port 기반 키)를 포함합니다.

4.6 공개 API (v1.0.0~)

// beads.go — 외부 통합을 위한 공개 API
func OpenBestAvailable() (Storage, Unlocker, error)  // 리소스 정리 지원
func PrettyIssue(issue *Issue) string                 // format 패키지 노출
func CompactIssue(issue *Issue) string
func LongIssue(issue *Issue) string

5. 데이터 모델

5.1 스키마 개요 (v11)

-- 핵심 5개 테이블
issues           -- 이슈/태스크 (30+ 컬럼)
dependencies     -- 관계 엣지 (19+ 타입)
labels           -- 태그 시스템
comments         -- 스레드 토론
events           -- 완전한 감사 추적

-- 지원 테이블
config                 -- 전역 key-value 설정
metadata               -- 프레임워크 레벨 상태 (스키마 버전 등)
child_counters         -- 계층적 ID 생성 (parent.N)
issue_snapshots        -- 컴팩션 스냅샷
compaction_snapshots   -- 컴팩션 상태 관리
repo_mtimes            -- 다중 리포 변경 감지
routes                 -- prefix-to-path 라우팅
issue_counter          -- 순차 ID 모드 (GH#2002)
interactions           -- 에이전트 감사 로그
federation_peers       -- P2P 동기화 자격 증명

-- v1.0.0 신규 (스키마 v10~v11)
custom_statuses        -- 정규화된 커스텀 상태 (name, category)
custom_types           -- 정규화된 커스텀 타입 (name)

스키마 변경 (v9 → v11):

  • v10: custom_statusescustom_types 테이블 추가 — 쉼표 구분 config 값에서 정규화된 테이블로 이전
  • v11: ready_issues/blocked_issues 뷰가 테이블 기반 서브쿼리로 변경 (동적 IN 절 대체)
  • 마이그레이션은 자동·멱등적으로 수행됨

5.2 issues 테이블 (핵심)

CREATE TABLE issues (
    -- 핵심 식별
    id VARCHAR(255) PRIMARY KEY,          -- 해시 기반 ID (bd-a1b2)
    content_hash VARCHAR(64),             -- SHA256 중복 방지용

    -- 이슈 콘텐츠
    title VARCHAR(500) NOT NULL,
    description TEXT NOT NULL,
    design TEXT NOT NULL,
    acceptance_criteria TEXT NOT NULL,
    notes TEXT NOT NULL,

    -- 워크플로우
    status VARCHAR(32) DEFAULT 'open',    -- open, in_progress, blocked, deferred, closed, pinned, hooked
    priority INT DEFAULT 2,               -- 0=critical ~ 4=backlog
    issue_type VARCHAR(32) DEFAULT 'task', -- bug, feature, task, epic, chore, message,
                                          --   molecule, gate, spike, story, milestone (v1.0.0~)

    -- 할당
    assignee VARCHAR(255),
    owner VARCHAR(255),
    estimated_minutes INT,

    -- 타임스탬프
    created_at DATETIME, updated_at DATETIME, closed_at DATETIME,

    -- 컴팩션 메타데이터
    compaction_level INT DEFAULT 0,       -- 0: 없음, 1: Tier 1, 2: Tier 2
    compacted_at DATETIME,
    original_size INT,

    -- 메시징
    sender VARCHAR(255),
    ephemeral TINYINT(1) DEFAULT 0,       -- true면 동기화되지 않음
    no_history TINYINT(1) DEFAULT 0,      -- wisps 테이블 저장, GC 대상 아님

    -- Gate (비동기 조율)
    await_type VARCHAR(32),               -- gh:run, gh:pr, timer, human, mail
    await_id VARCHAR(255),
    timeout_ns BIGINT,

    -- 스케줄링
    due_at DATETIME,
    defer_until DATETIME,

    -- 확장
    metadata JSON DEFAULT (JSON_OBJECT()),
    -- + 인덱스: status, priority, issue_type, assignee, created_at, spec_id, external_ref
);

5.3 dependencies 테이블 (엣지 스키마)

CREATE TABLE dependencies (
    issue_id VARCHAR(255) NOT NULL,       -- 종속 이슈
    depends_on_id VARCHAR(255) NOT NULL,  -- 차단하는 이슈 (FK 없음 - 외부 참조 허용)
    type VARCHAR(32) DEFAULT 'blocks',    -- 19+ 관계 타입
    created_at DATETIME,
    created_by VARCHAR(255),
    metadata JSON DEFAULT (JSON_OBJECT()), -- WaitsForMeta, AttestsMeta 등
    thread_id VARCHAR(255),               -- 대화 스레드 그룹핑
    PRIMARY KEY (issue_id, depends_on_id)
);

설계 결정 004 (Edge Schema Consolidation): 모든 관계 (replies-to, relates-to, duplicates 등)를 dependencies 테이블의 엣지로 통합. 스키마 변경 없이 유연한 엣지 타입을 추가할 수 있습니다.

5.4 해시 기반 ID 시스템

ID 형식: prefix-{hash}
예시:    bd-a1b2, bd-a1b2cd, bd-af78.1 (자식)

생성 과정:

  1. Title + Description + Timestamp + Workspace ID로 SHA256 해시 생성
  2. 6자로 시작, 충돌 시 점진적 확장 (7자 → 8자)
  3. 1,000개 이슈 기준 97%가 6자로 유지

계층적 ID:

bd-af78e9      → 루트 (에픽)
bd-af78e9.1자식 (태스크)
bd-af78e9.1.2손자 (서브태스크)
최대 깊이: 3레벨, 폭 제한 없음 (347+ 자식 테스트됨)

자식 ID 생성 과정 (v1.0.0 상세):

// child_counters 테이블에서 원자적으로 다음 번호 할당
func GetNextChildIDTx(ctx, tx, parentID) (string, error) {
    // 1. child_counters에서 last_child 조회
    // 2. issues 테이블 스캔으로 기존 자식 확인 (JSONL 임포트 대응)
    // 3. max(counter, existing) + 1로 새 번호 결정
    // 4. UPSERT로 카운터 갱신
    return fmt.Sprintf("%s.%d", parentID, nextChild), nil
}

분산 환경에서의 의미:

  • Branch A: bd create "Feature X"bd-a1b2 (해시 기반)
  • Branch B: bd create "Feature Y"bd-f14c (다른 해시)
  • Dolt 머지 시 두 이슈 모두 충돌 없이 머지됨

5.5 Content Hash

func (i *Issue) ComputeContentHash() string {
    // SHA256(title + description + design + acceptance_criteria + notes +
    //        spec_id + status + priority + issue_type + assignee + ...)
    // 제외: ID, 타임스탬프, 컴팩션 메타데이터
}

동일 콘텐츠 = 동일 해시 → 중복 감지 및 변경 추적에 사용됩니다.

5.6 Status 흐름

open ──→ in_progress ──→ closed
  ↓                         ↑
  └─────── reopen ──────────┘

특수 상태:
  blocked   : 차단됨 (블로커 해결 대기)
  deferred  : 의도적 일시 중지
  pinned    : 영구 컨텍스트 마커 (작업 항목이 아님)
  hooked    : 워커가 활성 클레임 중
  tombstone : 소프트 삭제

커스텀 상태: custom_statuses 테이블로 관리 (카테고리: active, wip, done, frozen)

5.7 이슈 타입 (v1.0.0 업데이트)

기본 타입:  bug, feature, task, epic, chore, message, molecule, gate
v1.0.0 추가: spike     — 불확실성 해소를 위한 타임박스 조사
             story     — 사용자 관점의 기능 설명
             milestone — 관련 이슈 완료 표시 (자체 작업 없음)
커스텀 타입: custom_types 테이블로 관리, 50자 이하 비어있지 않은 문자열

5.8 뷰 (View)

ready_issues — 작업 가능한 이슈:

  • status = 'open' (또는 custom_statuses 테이블의 active 카테고리)
  • 어떤 active blocks 의존성에도 차단되지 않음
  • 부모-자식 계층 내 전이적 차단 아님
  • defer_until 스케줄링 반영
  • ephemeral 이슈 제외
  • v1.0.0: 테이블 기반 서브쿼리로 성능 개선

blocked_issues — 차단된 이슈 + blocked_by_count 컬럼


6. 의존성 & 그래프 시스템

6.1 관계 타입 (19+)

워크플로우 타입 (Blocking — bd ready에 영향)

타입의미동작
blocksA가 닫혀야 B 시작 가능기본 차단
parent-child에픽/서브태스크 계층부모 차단 시 자식도 차단
conditional-blocksA 실패 시에만 B 실행조건부 차단
waits-for팬아웃 게이트all-children 또는 any-children

정보성 타입 (Non-Blocking)

타입의미
related느슨한 참고 링크
discovered-from다른 이슈 작업 중 발견
relates-to양방향 지식 그래프 엣지
replies-to대화 스레딩
duplicates중복 링크
supersedes버전 체인/대체

엔티티 관계 타입 (HOP Foundation)

타입의미
authored-by생성자 관계
assigned-to할당 관계
approved-by승인 관계
attests스킬 증명

기타

타입의미
tracks크로스 프로젝트 추적 (비차단)
caused-by근본 원인 링크
validates검증/승인 관계
until대상 닫힐 때까지 활성
delegated-from작업 위임 체인

커스텀 타입도 허용: 50자 이하의 비어있지 않은 문자열이면 유효.

6.2 Auto-Ready 감지 (bd ready)

computeBlockedIDs()가 차단 상태의 단일 진실 소스(SSOT):

1. 활성 이슈 조회 (closed, pinned 제외)
2. 차단 의존성 조회 (blocks, conditional-blocks)
3. 양쪽 모두 활성인 것만 필터링
4. waits-for 처리:
   - all-children: 자식 중 하나라도 활성이면 차단
   - any-children: 첫 자식이 닫힐 때까지 차단
5. 결과를 blockedIDsCacheMap에 저장 (O(1) 조회)

캐시는 DoltStore 수명 동안 유효하며, 의존성 변경 시 무효화됩니다.

v1.0.0 추가:

  • bd ready --explain — 왜 특정 이슈가 ready/not-ready인지 의존성 기반 설명
  • bd ready --parent <epic-id> — 특정 에픽의 자식만 필터링

6.3 사이클 방지

쓰기 시점: AddDependency() → 재귀 CTE SQL로 사이클 탐지 → 거부 읽기 시점: DetectCycles() → DFS 기반 전체 그래프 분석 CLI: bd dep cycles → 모든 사이클 경로 출력 (A → B → C → A) v1.0.0: bd graph check — 확장된 사이클 감지를 포함한 그래프 무결성 검증

6.4 그래프 시각화

레이아웃 계산 (computeLayout()):

  1. blocks 의존성만으로 의존 맵 구축
  2. longest-path 알고리즘으로 레이어 할당 (Layer 0 = 의존성 없음)
  3. parent-child 자식을 부모 레이어로 리프트
  4. 레이어 내 ID 기준 정렬

출력 형식:

형식설명
Terminal DAG박스 드로잉 문자, 상태 아이콘 (○ ◐ ● ✓ ❄)
DOT (Graphviz)bd graph --dot ID | dot -Tsvg > graph.svg
HTML (D3.js)인터랙티브 (드래그, 줌, 클릭, 범례)
Compact/Tree한 줄씩 트리 커넥터 (├── └──)

6.5 원자적 그래프 생성 (bd create --graph)

JSON 플랜으로 전체 의존성 그래프를 한 번에 생성:

{
  "commit_message": "Bootstrap auth epic",
  "nodes": [
    {"key": "epic", "title": "Auth System", "type": "epic", "priority": 1},
    {"key": "design", "title": "Design API", "type": "task", "parent_key": "epic"},
    {"key": "impl", "title": "Implement API", "type": "task", "parent_key": "epic"},
    {"key": "tests", "title": "Write tests", "type": "task", "parent_key": "epic"}
  ],
  "edges": [
    {"from_key": "impl", "to_key": "design", "type": "blocks"},
    {"from_key": "tests", "to_key": "impl", "type": "blocks"}
  ]
}

특징:

  • 심볼릭 key → 실제 ID 매핑을 반환
  • parent_key로 부모-자식 계층 자동 생성
  • metadata_refs로 이슈 간 메타데이터 참조 (모든 ID 할당 후 해결)
  • 단일 트랜잭션 — 하나라도 실패하면 전체 롤백
  • 검증: 고유 키, 존재하는 참조, 유효한 의존성 타입

7. 메모리 컴팩션 (Semantic Compaction)

7.1 개념

오래된 닫힌 이슈를 AI로 요약하여 DB 크기와 LLM 컨텍스트 윈도우를 절약하는 기능입니다.

7.2 2단계 전략

단계조건압축률 목표방법
Tier 1닫힌 지 30일+ (compact_tier1_days 설정 가능)~70%Claude Haiku로 요약
Tier 2Tier 1 후 90일+ (compact_tier2_days 설정 가능)~95%추가 초압축

7.3 AI 요약 형식

Input:  Title, Description, Design, Acceptance Criteria, Notes
Output:
  **Summary:** 2-3문장 (무엇을 했고,)
  **Key Decisions:** 핵심 기술 결정 요점
  **Resolution:** 최종 결과 1문장
  • AI 모델: Claude Haiku (경량, 비용 효율적)
  • 재시도: 최대 3회, 지수 백오프 (1s, 2s, 4s)
  • API 키: ANTHROPIC_API_KEY 환경변수 또는 ai.api_key 설정값

7.4 적격성 조건

// Tier 1 적격:
status == CLOSED
&& closed_at <= (now - 30)
&& compaction_level == 0

// Tier 2 적격:
status == CLOSED
&& compaction_level == 1
&& closed_at <= (now - 90)

7.5 3가지 운영 모드

모드설명API 필요?
Analyze (--analyze)적격 후보 목록 내보내기불필요
Apply (--apply --id <ID> --summary <file>)사람이 제공한 요약 적용불필요
Auto (--auto --all)AI 자동 요약 (레거시)필요

배치 처리: 설정 가능한 동시성 (기본 5 워커), 세마포어 패턴

7.6 저장 구조

-- issues 테이블 내 메타데이터:
compaction_level INT   -- 0(없음), 1(Tier 1), 2(Tier 2)
compacted_at DATETIME  -- 컴팩션 시점
compacted_at_commit VARCHAR(64)  -- Dolt 커밋 해시
original_size INT      -- 원본 크기 (바이트)

-- 별도 스냅샷 테이블:
compaction_snapshots (issue_id, compaction_level, snapshot_json, created_at)

7.7 Dolt 히스토리 컴팩션 (별도)

이슈 컴팩션과 별개로, auto-commit으로 쌓인 Dolt 커밋 이력을 스쿼시하는 기능:

bd compact --dolt --dry-run        # 미리보기
bd compact --dolt --days 7 --force # 7일 이전 히스토리 스쿼시
  1. --days 임계값 이전 커밋 식별
  2. 스쿼시된 베이스 커밋 생성
  3. 최근 커밋을 cherry-pick
  4. Dolt GC로 디스크 공간 회수

8. 동기화 시스템

8.1 Dolt 네이티브 Push/Pull

bd dolt push    # origin 리모트로 푸시
bd dolt pull    # origin에서 풀 + 셀 단위 자동 머지
bd dolt commit -m "msg"  # 변경사항 커밋

3방향 라우팅 로직:

  • Git 프로토콜 리모트 → CLI dolt push (MySQL 타임아웃 방지)
  • Hosted Dolt + SQL 인증 → SQL CALL DOLT_PUSH('--user', ...)
  • 기타 → SQL CALL DOLT_PUSH(remote, branch)

지원 리모트 타입:

  • DoltHub: dolthub://org/repo
  • Direct SQL: host:port/database
  • File: file:///path/to/repo
  • Git 변환: https://...git+https://...
  • Azure Blob: az://container/path (v1.0.0~)

8.2 Federation (P2P 동기화)

# 피어 추가
bd federation add-peer team-beta dolthub://acme/team-beta-beads
bd federation add-peer partner https://partner.example.com/beads --sovereignty T3

# 동기화
bd federation sync --peer team-beta --strategy ours
bd federation status

동기화 워크플로우 (5단계):

  1. Fetch: CALL DOLT_FETCH(peer_name)
  2. Merge: CALL DOLT_MERGE('--author', author, peer/branch)
  3. 충돌 감지: dolt_conflicts 테이블 조회
  4. 충돌 해결: --ours (로컬 우선) / --theirs (리모트 우선) / 수동
  5. Push: CALL DOLT_PUSH(peer_name, branch)

자격 증명 관리:

  • AES-256-GCM 암호화 (랜덤 키)
  • federation_peers 테이블에 저장
  • 동기화 시 자동 복호화
  • v1.0.0: ~/.config/beads/credentials 파일 지원, Unix 퍼미션 체크

8.3 충돌 해결

Dolt의 셀 단위 머지가 핵심:

  • 같은 테이블의 다른 행/컬럼 수정 → 자동 머지
  • 같은 셀 충돌 → dolt_conflicts 테이블에 기록
  • 해결 전략: --ours (DOLT_CONFLICTS_RESOLVE --ours) / --theirs / 수동

8.4 Git 연동

// URL 자동 변환
gitURLToDoltRemote("https://github.com/org/repo.git")
"git+https://github.com/org/repo.git"

gitURLToDoltRemote("git@github.com:org/repo.git")
"git+ssh://git@github.com/org/repo.git"

8.5 백업

bd backup init /path/to/backup   # 백업 대상 설정
bd backup sync                    # 동기화
bd backup restore --force /path   # 복원

Dolt 네이티브 백업 사용 → 전체 커밋 히스토리 보존.


9. Wisps & Molecules

9.1 개념

Molecules: 구조화된 워크플로우를 정의하는 템플릿 작업 항목 Wisps: Molecule에서 생성된 로컬 전용 임시 이슈 (실행 트레이스)

9.2 Wisp 생명주기

bd mol wisp (템플릿에서 생성)
Wisp Issues (로컬 전용 작업)
  → bd mol squash (영구 다이제스트로 압축)

9.3 Molecule 계층적 로딩

1. 내장 분자 (바이너리에 포함)
2. Town-level: $GT_ROOT/.beads/molecules.jsonl (오케스트레이터)
3. User-level: ~/.beads/molecules.jsonl
4. Project-level: .beads/molecules.jsonl

각 레벨이 상위 레벨을 오버라이드할 수 있습니다.

9.4 왜 Wisps는 동기화되지 않는가?

특성일반 이슈Wisps
리모트 동기화OX
삭제 시 TombstoneOX (하드 삭제)
부활 가능OX (동기화된 적 없음)
삭제 방식CreateTombstone()DeleteIssue()

장점:

  • 동기화 오버헤드 없는 빠른 로컬 반복
  • 다이제스트(결과)만 git에 들어가 깔끔한 히스토리
  • 에이전트 간 실행 트레이스 격리
  • 클론 간 wisp 축적 방지

10. v1.0.0 신규 기능

10.1 bd batch — 원자적 배치 처리

# stdin에서 다중 작업 실행
echo "close bd-a1b2 done
update bd-c3d4 status=in_progress
create task 1 New authentication module
dep add bd-e5f6 bd-c3d4 blocks" | bd batch

# 파일에서 실행
bd batch -f operations.txt

# 드라이런
bd batch --dry-run -f operations.txt

지원 연산:

연산구문설명
closeclose <id> [reason...]이슈 닫기
updateupdate <id> <key>=<value>status, priority, title, assignee 갱신
createcreate <type> <priority> <title>새 이슈 생성
dep adddep add <from> <to> [type]의존성 추가
dep removedep remove <from> <to>의존성 제거

핵심 가치: N개의 순차적 bd 호출을 하나의 Dolt 커밋으로 통합하여 쓰기 증폭(write amplification) 제거.

10.2 bd rules audit — 규칙 감사

bd rules audit              # .claude/rules/*.md 모순 검사
bd rules compact            # 중복 규칙 병합 제안
  • Do/Don't 지시문 추출
  • 반의어 쌍 감지 (block↔proceed, verbose↔minimize 등)
  • 범위 점수로 모순 규칙 식별
  • 중복 후보 병합 제안

10.3 신규 이슈 타입: Spike, Story, Milestone

타입의미사용 예
spike타임박스 조사"Redis vs DynamoDB 성능 비교, 2일 이내"
story사용자 스토리"사용자로서 비밀번호를 재설정할 수 있다"
milestone완료 표시자"Alpha 릴리스 준비 완료" (자체 작업 없음)

10.4 스토리지 훅 데코레이터 (HookFiringStore)

CLI → Storage 계층으로 훅 발화 로직 이전:

// 데코레이트된 메서드들:
CreateIssue  → on_create 훅 발화
UpdateIssue  → on_update 훅 발화
ReopenIssue  → on_update 훅 발화
CloseIssue   → on_close 훅 발화
// ...모든 뮤테이션 메서드

// 트랜잭션 안전: 커밋 후에만 발화, 롤백 시 미발화
// UnwrapStore(): 옵셔널 인터페이스 타입 어서션용

장점: 향후 추가되는 모든 커맨드에서도 자동으로 훅이 일관되게 실행됩니다.

10.5 Slot API — Per-Issue 메타데이터

bd slot set bd-a1b2 delegation_state "waiting_review"
bd slot get bd-a1b2 delegation_state
bd slot clear bd-a1b2 delegation_state

이슈 필드를 오염시키지 않고 외부 도구가 위임 상태, 훅 상태 등을 저장할 수 있습니다.

10.6 bd config set-many — 배치 설정

bd config set-many ado.state_map.open=New ado.state_map.closed=Closed gitlab.project=myproject

YAML, git config, database config 키를 단일 커맨드로 원자적 갱신.

10.7 bd context — 백엔드 진단

bd context --json
# {
#   "beads_dir": ".beads",
#   "backend": "embedded",
#   "dolt_mode": "embedded",
#   "bd_version": "1.0.0",
#   "project_id": "my-project",
#   ...
# }

DB 없이도 동작하여 열화 상태에서 진단에 유용합니다.

10.8 CLI 개선

  • Top-level 별칭: bd comment, bd assign, bd tag, bd link, bd priority
  • 쉼표 구분 필터: bd list --status open,in_progress
  • 차단 아이콘: bd list에서 의존성 차단 이슈에 표시
  • bd ready --explain: 이슈의 ready/blocked 이유 설명
  • Bootstrap 개선: --non-interactive / --yes 플래그 (CI/자동화용), 서버 DB 존재 검증

10.9 외부 연동 강화

Azure DevOps (ADO) — 완전 새 연동:

bd ado sync          # ADO ↔ Beads 동기화
bd ado status        # 동기화 상태 확인
bd ado projects      # ADO 프로젝트 목록
  • 단축 참조: ado:NNNNN 인식, 동기화 시 중복 방지
  • 푸시 필터: --types, --states, --no-create

GitLab Sync 개선:

  • Epic → Milestone 매핑
  • GraphQL 기반 태스크 계층
  • 내부 타입 자동 필터링
  • 동적 작업 항목 타입 ID 쿼리 (세션 캐시)

공통 강화:

  • 모든 트래커 HTTP 클라이언트에 jitter 포함 재시도 로직
  • Linear/Jira 페이지네이션 가드
  • 응답 크기 제한
  • 터미널 안전 콘텐츠 새니타이징

10.10 연결 풀 & 안정성

  • 커넥션 풀 수명 설정 가능 (더 긴 기본값)
  • BEADS_DOLT_READY_TIMEOUT 환경변수로 waitForReady 타임아웃 오버라이드
  • 회로 차단기(circuit breaker) host:port 기반 키 (크로스 호스트 차단 방지)
  • btrfs 워커 스래싱 방지 (FS_NOCOW_FL 플래그)
  • dolt-server.log 시작 시 로테이션

10.11 빌드 & 배포 개선

  • CGO/Non-CGO 분리: beads_cgo.go (임베디드+서버) / beads_nocgo.go (서버 전용)
  • CI 개편: 테스트 샤딩, 사전 컴파일 바이너리, 공유 Go 모듈 캐시
  • 크로스 버전 스모크 테스트: 마이그레이션 안전성 검증 워크플로우
  • 설치 시 체크섬 검증: SHA256 검증 후 추출
  • ICU/CGO 폴백 처리: ICU 라이브러리 없는 시스템 대응

11. 프로젝트 개발 히스토리

11.1 바이브 코딩으로 탄생

Beads는 Steve YeggeClaude로 6일 만에 초기 버전을 구축한 프로젝트입니다.

항목수치
전체 커밋 수~8,365개+
Claude 공동 저작 커밋~2,927개+ (35%+)
GitHub Copilot 공동 저작~13개
핵심 개발자Steve Yegge (4,475+ 커밋)
AI 에이전트 크루emma (379), refinery (307), george, dennis, dave, jane, lizzy
외부 기여자coffeegoddd/DoltHub (147), matt wilkie, osamu2001 등

11.2 개발 방법론

  • ZFC (Zero Framework Cognition): "지능은 AI 모델에, 코드는 단순한 오케스트레이션"
  • 자체 독푸딩: beads 프로젝트 자체가 bd를 사용하여 이슈를 추적
  • 멀티 에이전트 오케스트레이션: "Beads Crew" 시스템 — emma, george, dennis 등 이름을 가진 AI 에이전트 크루가 독립적으로 개발 참여
  • 커밋 형식: Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

11.3 AI 에이전트 친화적 설계

프로젝트 자체가 AI 에이전트를 위해, AI 에이전트에 의해 만들어졌다:

  • AGENTS.md: 에이전트 워크플로우 완전 가이드 (인터랙티브 bd edit 사용 금지 등)
  • AGENT_INSTRUCTIONS.md (v1.0.0~): 상세 운영 지침 — Go 1.24+, 테스트 워크플로우, "Push to Main, Never PR", Landing the Plane 프로토콜
  • CLAUDE.md: Claude Code 작업 시 가이드 (프로젝트 로컬 설정 기본)
  • .claude/settings.json: 문제 패턴 차단 훅 (gh watch 폴링 등)
  • bd prime: 컨텍스트 주입 커맨드 (~1-2k 토큰)
  • bd setup claude: 프로젝트 로컬 .claude/settings.json 자동 생성 (v1.0.0~)
  • MCP 서버 지원

11.4 Steve Yegge 관련 글

  1. "Introducing Beads: A Coding Agent Memory System" — 원래 문제 정의
  2. "The Beads Revolution" — 6일간 Claude로 구축한 경험
  3. "Beads Blows Up" — 3주 후기, "land the plane" 프로토콜
  4. "From Beads to Tasks" — Anthropic의 에이전트 메모리에 대한 영향

11.5 주요 진화 타임라인

버전변경
v0.20+해시 기반 ID 도입
v0.50.3통합 트래커 동기화 (SyncEngine)
v0.51.0bd sync 제거 → bd dolt push/pull, SQLite 백엔드 제거
v0.53.0JSONL 동기화 파이프라인 제거 (~11,000줄)
v0.55.0+멀티 에이전트 오케스트레이션 (Gas Town)
v0.60+UUID 마이그레이션, Federation 충돌 해결
v0.61.0+Prime SSOT, 회로 차단기 패턴
v0.62.0임베디드 Dolt 모드, 커스텀 상태 카테고리
v1.0.0프로덕션 안정성 마일스톤: 임베디드 기본, bd batch, 그래프 생성, ADO 연동, 스토리지 훅 데코레이터, Slot API, 규칙 감사, 스키마 v11, 신규 이슈 타입 (spike/story/milestone), 빌드 분리 (CGO/Non-CGO)

12. 핵심 파일 레퍼런스

아키텍처 & 설계

파일역할
docs/ARCHITECTURE.md아키텍처 문서
docs/INTERNALS.md내부 구현 상세 (FlushManager, Blocked Cache)
docs/CLI_REFERENCE.md전체 CLI 레퍼런스 (32KB+)
docs/COLLISION_MATH.md해시 충돌 확률 수학
AGENTS.md에이전트 워크플로우 가이드
AGENT_INSTRUCTIONS.md에이전트 상세 운영 지침 (v1.0.0~)

핵심 소스 코드

파일역할
cmd/bd/main.go진입점, 글로벌 상태, 신호 처리
internal/types/types.goIssue, Dependency, Status 등 도메인 타입
internal/types/id_generator.go해시 기반 ID 생성, 계층적 ID 파싱
internal/storage/storage.goStorage 인터페이스 (Slot API 포함)
internal/storage/hook_decorator.goHookFiringStore (v1.0.0~)
internal/storage/dolt/schema.goDB 스키마 (v11)
internal/storage/dolt/store.goDoltStore 구현체
internal/storage/dolt/issues.go이슈 CRUD (Write Path)
internal/storage/dolt/dependencies.go의존성 CRUD
internal/storage/dolt/queries.gocomputeBlockedIDs, GetReadyWork
internal/storage/schema/schema.go통합 스키마 SSOT (v1.0.0~)
internal/storage/issueops/blocked.goComputeBlockedIDsInTx (공용)
internal/storage/issueops/cycles.go사이클 탐지 (DFS)
internal/storage/issueops/compaction.go컴팩션 적격성/티어 로직
internal/storage/issueops/child_id.go자식 ID 생성, 카운터 조정
beads_cgo.goCGO 빌드: 임베디드+서버 (v1.0.0~)
beads_nocgo.goNon-CGO 빌드: 서버 전용 (v1.0.0~)

CLI 커맨드 (주요)

파일역할
cmd/bd/create.go이슈 생성 (--parent, --graph 포함)
cmd/bd/ready.go준비된 작업 조회 + 차단된 이슈 (--explain)
cmd/bd/dep.go의존성 관리
cmd/bd/graph.go그래프 로딩/커맨드 디스패치
cmd/bd/graph_visual.go터미널 DAG 렌더링
cmd/bd/graph_export.goDOT/HTML 내보내기
cmd/bd/graph_apply.goJSON에서 원자적 그래프 생성
cmd/bd/batch.go원자적 배치 처리 (v1.0.0~)
cmd/bd/rules.go규칙 감사/컴팩트 (v1.0.0~)
cmd/bd/ado.goAzure DevOps 연동 (v1.0.0~)
cmd/bd/context_cmd.go백엔드 컨텍스트 진단 (v1.0.0~)
cmd/bd/compact.go시맨틱 컴팩션 CLI
cmd/bd/dolt.goDolt 동기화 커맨드
cmd/bd/federation.goFederation P2P 동기화
cmd/bd/relate.go양방향 relates-to 링크

컴팩션 & AI

파일역할
internal/compact/compactor.go컴팩터 오케스트레이션
internal/compact/haiku.goClaude Haiku AI 통합

13. 주요 설계 결정 요약

결정내용이유
Dolt 사용SQLite/PostgreSQL 대신 Dolt버전 관리, 셀 단위 머지, 네이티브 분산
해시 기반 ID순차 ID 대신 해시중앙 조정 없는 분산 생성, 머지 충돌 방지
Edge Schema 통합별도 테이블 대신 dependencies에 모든 관계스키마 변경 없는 유연성
4가지 차단 타입만19+ 타입 중 4개만 ready에 영향명확한 워크플로우 의미론
자동 Dolt 커밋매 쓰기마다 자동 커밋완전한 감사 추적, 데이터 손실 방지
Wisps 비동기화로컬 전용 임시 이슈빠른 반복, 깔끔한 히스토리
Claude Haiku 컴팩션경량 AI로 이슈 요약비용 효율적, LLM 컨텍스트 윈도우 최적화
ZFC 원칙코드는 오케스트레이션, 지능은 AI코드 복잡도 최소화, AI 모델 활용 극대화
임베디드 기본 (v1.0.0)외부 서버 없이 인프로세스설치 복잡도 제거, macOS 네이티브 지원
훅 데코레이터 (v1.0.0)CLI가 아닌 스토리지 계층에서 훅 발화모든 뮤테이션 경로에서 일관된 훅 실행
배치 처리 (v1.0.0)N개 작업을 1 커밋으로 통합쓰기 증폭 제거, 셸 스크립트 최적화

14. USE CASE: Epic 분해

14.1 시나리오

"사용자 인증 시스템"이라는 대형 에픽을 설계 → 구현 → 테스트 순서로 분해하고, AI 에이전트가 의존성 순서대로 작업을 수행하는 전체 과정입니다.

14.2 방법 A: 개별 생성 (bd create --parent)

# ===== 1단계: 에픽 생성 =====
bd create "사용자 인증 시스템" -t epic -p 1 \
  -d "OAuth 2.0 + MFA 지원" --json
# → {"id": "bd-a3f8e9", "title": "사용자 인증 시스템", ...}

# ===== 2단계: 자식 태스크 생성 =====
bd create "OAuth 플로우 설계" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.1"}  ← 자동 계층 ID

bd create "OAuth 프로바이더 구현" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.2"}

bd create "MFA 지원 추가" --parent bd-a3f8e9 -p 2 --json
# → {"id": "bd-a3f8e9.3"}

bd create "통합 테스트 작성" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.4"}

bd create "보안 문서화" --parent bd-a3f8e9 -p 2 --json
# → {"id": "bd-a3f8e9.5"}

# ===== 3단계: 실행 순서 의존성 추가 =====
bd dep add bd-a3f8e9.2 bd-a3f8e9.1 --type blocks   # 구현은 설계 후
bd dep add bd-a3f8e9.3 bd-a3f8e9.2 --type blocks   # MFA는 OAuth 구현 후
bd dep add bd-a3f8e9.4 bd-a3f8e9.2 --type blocks   # 테스트는 구현 후
bd dep add bd-a3f8e9.5 bd-a3f8e9.4 --type blocks   # 문서는 테스트 후

14.3 방법 B: 원자적 그래프 생성 (bd create --graph)

모든 이슈와 의존성을 단일 트랜잭션으로 한 번에 생성:

cat > auth-epic.json <<'EOF'
{
  "commit_message": "Bootstrap 사용자 인증 시스템 에픽",
  "nodes": [
    {
      "key": "epic",
      "title": "사용자 인증 시스템",
      "type": "epic",
      "priority": 1,
      "description": "OAuth 2.0 + MFA 지원"
    },
    {
      "key": "design",
      "title": "OAuth 플로우 설계",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "oauth-impl",
      "title": "OAuth 프로바이더 구현",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "mfa",
      "title": "MFA 지원 추가",
      "type": "task",
      "priority": 2,
      "parent_key": "epic"
    },
    {
      "key": "tests",
      "title": "통합 테스트 작성",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "docs",
      "title": "보안 문서화",
      "type": "task",
      "priority": 2,
      "parent_key": "epic"
    }
  ],
  "edges": [
    {"from_key": "oauth-impl", "to_key": "design", "type": "blocks"},
    {"from_key": "mfa", "to_key": "oauth-impl", "type": "blocks"},
    {"from_key": "tests", "to_key": "oauth-impl", "type": "blocks"},
    {"from_key": "docs", "to_key": "tests", "type": "blocks"}
  ]
}
EOF

bd create --graph auth-epic.json --json
# → {
#     "ids": {
#       "epic": "bd-a3f8e9",
#       "design": "bd-a3f8e9.1",
#       "oauth-impl": "bd-a3f8e9.2",
#       "mfa": "bd-a3f8e9.3",
#       "tests": "bd-a3f8e9.4",
#       "docs": "bd-a3f8e9.5"
#     }
#   }

14.4 방법 C: 배치 처리 (bd batch)

기존 이슈에 대한 대량 변경 시 유용:

cat > epic-ops.txt <<'EOF'
create task 1 OAuth 플로우 설계
create task 1 OAuth 프로바이더 구현
create task 2 MFA 지원 추가
create task 1 통합 테스트 작성
create task 2 보안 문서화
EOF

bd batch -f epic-ops.txt --message "에픽 자식 태스크 일괄 생성"

14.5 에이전트의 작업 실행 흐름

# ===== 에이전트가 준비된 작업 조회 =====
bd ready --parent bd-a3f8e9 --json
# 결과: [{"id": "bd-a3f8e9.1", "title": "OAuth 플로우 설계"}]
# → 의존성이 없는 "설계"만 ready 상태

# ===== 설계 완료 → 구현 해제 =====
bd update bd-a3f8e9.1 --status in_progress
# ... 작업 수행 ...
bd close bd-a3f8e9.1 --reason "OAuth 설계 문서 승인"

bd ready --parent bd-a3f8e9 --json
# 결과: [{"id": "bd-a3f8e9.2", "title": "OAuth 프로바이더 구현"}]
# → "설계" 완료로 "구현"이 해제됨

# ===== 구현 완료 → MFA + 테스트 동시 해제 =====
bd update bd-a3f8e9.2 --status in_progress
# ... 작업 수행 ...
bd close bd-a3f8e9.2 --reason "OAuth 프로바이더 통합"

bd ready --parent bd-a3f8e9 --json
# 결과: [
#   {"id": "bd-a3f8e9.3", "title": "MFA 지원 추가"},
#   {"id": "bd-a3f8e9.4", "title": "통합 테스트 작성"}
# ]
# → "구현" 완료로 "MFA"와 "테스트"가 동시에 해제됨 (병렬 작업 가능!)

# ===== 병렬 작업 → 순차 완료 =====
bd close bd-a3f8e9.3 --reason "MFA 구현 완료"
bd close bd-a3f8e9.4 --reason "전체 테스트 통과"

bd ready --parent bd-a3f8e9 --json
# 결과: [{"id": "bd-a3f8e9.5", "title": "보안 문서화"}]

bd close bd-a3f8e9.5 --reason "API 문서 및 보안 가이드 작성 완료"

14.6 에픽 상태 확인 & 자동 닫기

# 진행 중 상태 확인
bd show bd-a3f8e9
# ┌──────────────────────────────────────┐
# │  bd-a3f8e9: 사용자 인증 시스템       │
# │  Type: epic  Status: open  P1        │
# │  Children: 5 total (2 closed, 3 open)│
# │  Progress: ██████░░░░░░░ 40%         │
# └──────────────────────────────────────┘

# 그래프 시각화
bd graph bd-a3f8e9
# Layer 0:  [○ bd-a3f8e9.1 설계]
#              │
# Layer 1:  [◐ bd-a3f8e9.2 구현]
#            ┌──┤
# Layer 2:  [○ bd-a3f8e9.3 MFA]  [○ bd-a3f8e9.4 테스트]
#                                    │
# Layer 3:                        [○ bd-a3f8e9.5 문서]

# 마지막 자식 닫기 → 에픽 자동 닫기
bd close bd-a3f8e9.5 --reason "완료"
bd show bd-a3f8e9
# Status: closed ← 모든 자식 완료로 자동 전환

14.7 의존성 그래프 (시각 요약)

                    bd-a3f8e9 (에픽: 사용자 인증 시스템)
                    ├── .1 OAuth 플로우 설계
                    │     ↓ blocks
                    ├── .2 OAuth 프로바이더 구현
                    │     ├── ↓ blocks
                    │     └── ↓ blocks
                    ├── .3 MFA 지원 추가 ←──────┘
                    ├── .4 통합 테스트 작성 ←────┘
                    │     ↓ blocks
                    └── .5 보안 문서화

실행 순서:  .1.2  (.3 + .4 병렬).5

14.8 핵심 메커니즘 요약

메커니즘설명
계층적 ID--parent.N 접미사 자동 생성, 최대 3단계 깊이
parent-child 의존성자식 생성 시 자동으로 parent-child 엣지 추가
blocks 의존성실행 순서 제어 — A 닫혀야 B가 bd ready에 등장
bd ready --parent특정 에픽 자식 중 작업 가능한 것만 필터링
에픽 자동 닫기모든 자식이 closed되면 에픽도 자동 closed
그래프 생성bd create --graph로 전체 구조를 원자적으로 생성
배치 처리bd batch로 다중 변경을 단일 커밋으로 통합
Molecule 시드bd mol seed <template>로 반복 가능한 에픽 패턴 재사용

14.9 waits-for: 동적 팬아웃 패턴

에픽 내에서 자식 수가 런타임에 결정되는 경우:

# 맵리듀스 패턴: reduce는 모든 map 파티션이 끝날 때까지 대기
bd create "Data Pipeline" -t epic -p 1
# → bd-b2c3

bd create "Map Partition 1" --parent bd-b2c3
bd create "Map Partition 2" --parent bd-b2c3
# ... 런타임에 더 추가 가능

bd create "Reduce & Aggregate" -t task -p 1
bd dep add reduce-id bd-b2c3 --type waits-for
# → "Reduce"는 bd-b2c3의 모든 자식이 닫힐 때까지 차단
# → 작업 도중 새 파티션이 추가되어도 자동으로 감지됨

이 리포트는 beads v1.0.0 (2026-04-02) 기준 소스 코드, 문서, git 히스토리를 분석하여 작성되었습니다. 이전 버전 (v0.62.0) 대비 주요 변경사항은 10. v1.0.0 신규 기능 섹션을 참조.