Beads - AI 에이전트를 위한 영구 작업 메모리은(는) 무엇을 하나요?
대화 압축에서도 유지되는 그래프 기반 이슈 트래커입니다. 복잡한 의존성이 있는 다중 세션 작업에 영구 메모리를 제공합니다.
개요
bd (beads) 는 markdown 작업 목록을 git에 저장된 의존성 인식 그래프로 대체합니다. TodoWrite(세션 범위)와 달리, bd는 압축을 견디고 복잡한 의존성을 추적합니다.
핵심 차이점:
- bd: 다중 세션 작업, 의존성, 압축 생존, git 지원
- TodoWrite: 단일 세션 작업, 선형 실행, 대화 범위
핵심 기능:
- 📊 의존성 그래프: 무엇이 무엇을 차단하는지 추적 (blocks, parent-child, discovered-from, related)
- 💾 압축 생존: 대화 기록이 압축될 때 작업이 유지됨
- 🐙 Git 통합:
.beads/issues.jsonl에 버전 관리된 이슈,bd sync로 동기화 - 🔍 스마트 발견: 준비된 작업(
bd ready) 및 차단된 작업(bd blocked) 자동 발견 - 📝 감사 추적: 상태 변경, 메모, 결정의 전체 기록
- 🏷️ 풍부한 메타데이터: 우선순위(P0-P4), 유형(bug/feature/task/epic), 레이블, 담당자
bd vs TodoWrite 사용 시기:
- ❓ "2주 후에도 이 컨텍스트가 필요할까?" → 예 = bd
- ❓ "대화 기록이 압축될 가능성이 있나?" → 예 = bd
- ❓ "차단기/의존성이 있나?" → 예 = bd
- ❓ "모호하거나 탐색적인 작업인가?" → 예 = bd
- ❓ "이 세션 안에 끝날 작업인가?" → 예 = TodoWrite
- ❓ "지금 당장의 작업 목록인가?" → 예 = TodoWrite
결정 규칙: bd 없이 2주 후에 재개하기 어려울 것 같다면 bd를 사용하세요.
전제 조건
필수:
- bd CLI: 버전 0.34.0 이상이 설치되어 PATH에 있어야 함
- Git 저장소: 현재 디렉토리는 git 저장소여야 함
- 초기화:
bd init이 한 번 실행되어야 함 (사람이 실행, 에이전트는 실행하지 않음)
설치 확인:
bd --version # 0.34.0 이상이 반환되어야 함
최초 설정 (사람이 한 번 실행):
cd /path/to/your/repo
bd init # 데이터베이스가 있는 .beads/ 디렉토리 생성
선택 사항:
- 대체 데이터베이스 위치를 위한 BEADS_DIR 환경 변수
- 백그라운드 동기화를 위한 데몬:
bd daemon --start
지침
세션 시작 프로토콜
모든 세션은 여기서 시작하세요:
1단계: 준비된 작업 확인
bd ready
열린 차단기가 없는 작업을 우선순위(P0 → P4) 순으로 표시합니다.
표시 내용:
- 작업 ID (예:
myproject-abc) - 제목
- 우선순위 수준
- 이슈 유형 (bug, feature, task, epic)
출력 예시:
claude-code-plugins-abc [P1] [task] open
사용자 인증 구현
claude-code-plugins-xyz [P0] [epic] in_progress
데이터베이스 계층 리팩토링
2단계: 최우선순위 작업 선택
준비된 작업 중 가장 높은 우선순위(P0 > P1 > P2 > P3 > P4) 작업을 선택합니다.
3단계: 전체 컨텍스트 확인
bd show <task-id>
표시 내용:
- 전체 작업 설명
- 의존성 그래프 (이 작업을 차단하는 것, 이 작업이 차단하는 것)
- 감사 추적 (모든 상태 변경, 메모)
- 메타데이터 (생성일, 업데이트일, 담당자, 레이블)
4단계: 작업 시작
bd update <task-id> --status in_progress
작업이 현재 진행 중임을 표시합니다.
5단계: 작업 중 메모 추가
bd update <task-id> --notes "완료: X. 진행 중: Y. 차단됨: Z"
압축 생존에 중요: 대화 컨텍스트가 전혀 없는 미래의 에이전트에게 설명하는 것처럼 메모를 작성하세요.
메모 형식 (모범 사례):
완료: 구체적인 결과물 (예: "JWT 리프레시 엔드포인트 + 속도 제한 구현")
진행 중: 현재 상태 + 다음 즉시 단계
차단기: 진행을 막는 것들
주요 결정: 중요한 컨텍스트 또는 사용자 지침
작업 생성 워크플로우
작업 생성 시기
다음과 같은 경우 bd 작업을 생성하세요:
- 사용자가 세션 간 작업 추적을 언급할 때
- 사용자가 "X를 수정/구축/추가해야 해"라고 말할 때
- 작업에 의존성이나 차단기가 있을 때
- 경계가 모호한 탐색/연구 작업일 때
기본 작업 생성
bd create "작업 제목" -p 1 --type task
인수:
- 제목: 간단한 설명 (필수)
- 우선순위: 0-4 (0=치명적, 1=높음, 2=중간, 3=낮음, 4=백로그, 기본값: 2)
- 유형: bug, feature, task, epic, chore (기본값: task)
예시:
bd create "인증 버그 수정" -p 0 --type bug
설명과 함께 생성
bd create "OAuth 구현" -p 1 --description "Google, GitHub, Microsoft용 OAuth2 지원 추가. passport.js 라이브러리 사용."
하위 항목이 있는 Epic
# 상위 epic 생성
bd create "Epic: OAuth 구현" -p 0 --type epic
# 반환: myproject-abc
# 하위 작업 생성
bd create "OAuth 공급자 조사" -p 1 --parent myproject-abc
bd create "인증 엔드포인트 구현" -p 1 --parent myproject-abc
bd create "프론트엔드 로그인 UI 추가" -p 2 --parent myproject-abc
업데이트 및 진행 워크플로우
상태 변경
bd update <task-id> --status <새-상태>
상태 값:
open- 시작되지 않음in_progress- 진행 중blocked- 막힘, 무언가를 기다리는 중closed- 완료됨
예시:
bd update myproject-abc --status blocked
진행 메모 추가
bd update <task-id> --notes "진행 상황 업데이트"
기존 notes 필드에 추가됩니다 (대체하지 않음).
우선순위 변경
bd update <task-id> -p 0 # 치명적으로 에스컬레이션
레이블 추가
bd label add <task-id> backend
bd label add <task-id> security
레이블은 상태/유형을 넘어 교차 분류를 제공합니다.
의존성 관리
의존성 추가
bd dep add <자식-id> <부모-id>
의미: <부모-id>가 <자식-id>를 차단합니다 (부모가 먼저 완료되어야 함).
의존성 유형:
- blocks: 부모가 닫혀야 자식이 준비됨
- parent-child: 계층적 관계 (epic 및 하위 작업)
- discovered-from: 작업 A로 인해 작업 B 발견
- related: 작업이 관련되어 있지만 차단하지는 않음
예시:
# 배포가 테스트 통과에 의해 차단됨
bd dep add deploy-task test-task # test-task가 deploy-task를 차단함
의존성 보기
bd dep list <task-id>
표시:
- 이 작업이 차단하는 것 (의존 작업)
- 이 작업을 차단하는 것 (차단기)
순환 의존성 방지
bd는 자동으로 순환 의존성을 방지합니다. 순환을 생성하려고 하면 명령이 실패합니다.
완료 워크플로우
작업 닫기
bd close <task-id> --reason "완료 요약"
모범 사례: 항상 수행한 작업을 설명하는 이유를 포함하세요.
예시:
bd close myproject-abc --reason "완료: Google, GitHub 공급자로 OAuth 엔드포인트 구현. 테스트 통과."
새로 차단 해제된 작업 확인
작업을 닫은 후 다음을 실행하세요:
bd ready
작업을 닫으면 의존 작업의 차단이 해제되어 새로 준비될 수 있습니다.
하위 항목이 완료되면 Epic 닫기
bd epic close-eligible
모든 하위 작업이 닫힌 epic을 자동으로 닫습니다.
Git 동기화 워크플로우
올인원 동기화
bd sync
수행 작업:
- 데이터베이스를
.beads/issues.jsonl로 내보내기 - 변경 사항을 git에 커밋
- 원격에서 가져오기 (필요시 병합)
- 업데이트된 JSONL을 데이터베이스로 가져오기
- 로컬 커밋을 원격으로 푸시
사용 시기: 세션 종료 시, 동료에게 인계하기 전, 주요 진행 후.
내보내기만
bd export -o backup.jsonl
git 작업 없이 JSONL 백업을 생성합니다.
가져오기만
bd import -i backup.jsonl
JSONL 파일을 데이터베이스로 가져옵니다.
백그라운드 데몬
bd daemon --start # 백그라운드에서 자동 동기화
bd daemon --status # 데몬 상태 확인
bd daemon --stop # 자동 동기화 중지
데몬은 데이터베이스 변경 사항을 감시하고 자동으로 JSONL로 내보냅니다.
찾기 및 검색 명령
준비된 작업 찾기
bd ready
열린 차단기가 없는 작업을 표시합니다.
모든 작업 나열
bd list --status open # 열린 작업만
bd list --priority 0 # P0 (치명적)만
bd list --type bug # 버그만
bd list --label backend # "backend" 레이블이 있는 것만
bd list --assignee alice # alice에게 할당된 것만
작업 세부 정보 표시
bd show <task-id>
전체 세부 정보: 설명, 의존성, 감사 추적, 메타데이터.
텍스트 검색
bd search "authentication" # 제목과 설명 검색
bd search login --status open # 필터와 결합
차단된 작업 찾기
bd blocked
작업을 진행하지 못하게 하는 열린 차단기가 있는 모든 작업을 표시합니다.
프로젝트 통계
bd stats
표시:
- 상태별 총 이슈 수 (open, in_progress, blocked, closed)
- 우선순위별 이슈 수 (P0-P4)
- 유형별 이슈 수 (bug, feature, task, epic, chore)
- 완료율
전체 명령 참조
| 명령 | 사용 시기 | 예시 |
|---|---|---|
| 찾기 명령 | ||
bd ready | 차단되지 않은 작업 찾기 | 사용자가 "무엇을 해야 하나요?"라고 물을 때 |
bd list | 모든 작업 보기 (필터 포함) | "열린 버그를 보여줘" |
bd show <id> | 작업 세부 정보 가져오기 | "bd-42 작업을 보여줘" |
bd search <query> | 작업 전체 텍스트 검색 | "인증 관련 작업 찾기" |
bd blocked | 막힌 작업 찾기 | "우리를 막는 것은?" |
bd stats | 프로젝트 메트릭스 | "열린 작업은 몇 개인가?" |
| 생성 명령 | ||
bd create | 새 작업 추적 | "이 버그에 대한 작업 생성" |
bd template create | 이슈 템플릿 사용 | "버그 템플릿에서 작업 생성" |
bd init | beads 초기화 | "이 저장소에 beads 설정" (사람만) |
| 업데이트 명령 | ||
bd update <id> | 상태/우선순위/메모 변경 | "진행 중으로 표시" |
bd dep add | 의존성 연결 | "이것이 저것을 차단함" |
bd label add | 레이블로 태그 | "backend로 레이블 지정" |
bd comments add | 댓글 추가 | "작업에 댓글 추가" |
bd reopen <id> | 닫힌 작업 다시 열기 | "bd-42 다시 열기, 회귀 발견" |
bd rename-prefix | 이슈 접두사 이름 변경 | "접두사를 bd-에서 proj-로 변경" |
bd epic status | Epic 진행 상황 확인 | "Epic 완료율 표시" |
| 완료 명령 | ||
bd close <id> | 작업 완료 표시 | "이 작업 닫기, 완료됨" |
bd epic close-eligible | 완전한 Epic 자동 닫기 | "모든 하위 항목이 완료된 Epic 닫기" |
| 동기화 명령 | ||
bd sync | Git 동기화 (올인원) | "작업을 git에 동기화" |
bd export | JSONL로 내보내기 | "모든 작업 백업" |
bd import | JSONL에서 가져오기 | "백업에서 복원" |
bd daemon | 백그라운드 동기화 관리자 | "자동 동기화 데몬 시작" |
| 정리 명령 | ||
bd delete <id> | 이슈 삭제 | "테스트 작업 삭제" (--force 필요) |
bd compact | 오래된 닫힌 작업 보관 | "데이터베이스 압축" |
| 보고 명령 | ||
bd stats | 프로젝트 메트릭스 | "프로젝트 상태 표시" |
bd audit record | 상호 작용 기록 | "이 LLM 호출 기록" |
bd workflow | 워크플로 가이드 표시 | "beads를 어떻게 사용하나?" |
| 고급 명령 | ||
bd prime | AI 컨텍스트 새로고침 | "bd 워크플로 규칙 로드" |
bd quickstart | 대화형 튜토리얼 | "beads 기초 배우기" |
bd daemons | 다중 저장소 데몬 관리 | "모든 beads 데몬 관리" |
bd version | 버전 확인 | "bd 버전 확인" |
bd restore <id> | 압축된 이슈 복원 | "git에서 전체 기록 가져오기" |
출력
이 스킬은 다음을 생성합니다:
작업 ID: 형식 <접두사>-<해시> (예: claude-code-plugins-abc, myproject-xyz)
상태 요약:
5 open, 2 in_progress, 1 blocked, 47 closed
의존성 그래프 (시각적 트리):
myproject-abc: 프로덕션에 배포 [P0] [blocked]
차단됨:
↳ myproject-def: 통합 테스트 실행 [P1] [in_progress]
↳ myproject-ghi: 실패하는 테스트 수정 [P1] [open]
감사 추적 (전체 기록):
2025-12-22 10:00 - alice가 생성함 (P2, task)
2025-12-22 10:15 - 우선순위 변경됨: P2 → P0
2025-12-22 10:30 - 상태 변경됨: open → in_progress
2025-12-22 11:00 - 메모 추가됨: "JWT 인증 구현..."
2025-12-22 14:00 - 상태 변경됨: in_progress → blocked
2025-12-22 14:01 - 메모 추가됨: "차단됨: API 엔드포인트가 503 반환"
오류 처리
일반적인 오류
1. bd: command not found
원인: bd CLI가 설치되지 않았거나 PATH에 없음 해결 방법: https://github.com/steveyegge/beads 에서 설치
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# npm을 통해
npm install -g @beads/bd
# Homebrew를 통해
brew install steveyegge/beads/bd
2. No .beads database found
원인: 이 저장소에 beads가 초기화되지 않음
해결 방법: bd init 실행 (사람이 한 번 실행, 에이전트는 실행하지 않음)
bd init # .beads/ 디렉토리 생성
3. Task not found: <id>
원인: 잘못된 작업 ID 또는 작업이 존재하지 않음
해결 방법: bd list를 사용하여 모든 작업을 보고 ID 형식 확인
bd list # 모든 작업 보기
bd search <부분-제목> # 제목으로 작업 찾기
4. Circular dependency detected
원인: 순환 의존성 생성 시도 (A가 B를 차단, B가 A를 차단) 해결 방법: bd가 자동으로 순환 의존성을 방지합니다. 의존성 그래프를 재구성하세요.
bd dep list <id> # 현재 의존성 보기
5. .beads/issues.jsonl에서 Git 병합 충돌
원인: 여러 사용자가 동일한 이슈를 수정함 해결 방법: bd sync가 JSONL 충돌을 자동으로 처리합니다. 수동 개입이 필요한 경우:
# 충돌 보기
git status
# bd는 충돌 해결 도구를 제공합니다
bd sync --merge # 자동 해결 시도
6. Database is locked
원인: 데몬 또는 다른 프로세스가 독점 잠금을 보유함 해결 방법: 데몬을 다시 시작하거나 잠금이 해제될 때까지 기다림
bd daemon --stop
bd daemon --start
7. 동기화 실패
원인: 네트워크 문제, 인증 실패 또는 git 구성 해결 방법: git 원격 액세스 및 자격 증명 확인
git fetch # 연결 테스트
git status # 저장소 상태 확인
예시
…
[번역을 위해 잘림]