본문으로 건너뛰기
오픈소스 전체 목록

Beads (bd)

코딩 에이전트용 분산 그래프 이슈 트래커. 의존성 그래프로 긴 작업을 기억하고, Dolt로 버전 관리·동기화해요

원본:gastownhall/beads

요약

코딩 에이전트용 분산 그래프 이슈 트래커. 의존성 그래프로 긴 작업을 기억하고, Dolt로 버전 관리·동기화해요

설명

bd - Beads

Dolt 기반의 AI 에이전트용 분산 그래프 이슈 트래커.

지원 플랫폼: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI Ask DeepWiki

문서: https://beads.gascity.com/

Beads는 코딩 에이전트에게 지속적이고 구조화된 기억을 줍니다. 뒤죽박죽인 마크다운 계획서를 의존성을 아는 그래프로 바꿔, 에이전트가 긴 작업을 하면서도 맥락을 잃지 않게 합니다.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ 빠른 시작

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

참고: Beads는 한 번 설치해 어디서나 쓰는 CLI 도구입니다. 이 저장소를 내 프로젝트에 복제할 필요가 없습니다.

bd init은 기본적으로 AGENTS.md를 만들거나 고쳐서 에이전트가 beads 작업 흐름을 찾을 수 있게 하고, --skip-agents나 --stealth를 주지 않는 한 프로젝트용 Claude Code · Codex · Cursor 연동도 함께 설치합니다. 지원하는 연동 목록은 bd setup --list로 볼 수 있으며, bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor 등이 있습니다. 자세한 내용은 에이전트 · IDE 설정을 보세요.

직접 복사해 붙여 넣는 방법은 bd setup이 지원하지 않는 에이전트, bd init/bd setup을 다시 실행할 수 없는 기존 프로젝트, 직접 만든 지침 파일에만 필요합니다. 그럴 때는 bd onboard를 실행해 출력된 내용을 에이전트가 읽는 파일에 붙여 넣으세요.

에이전트가 bd setup으로 지원되지 않는다면, 최소한 아래 AGENTS.md 항목을 추가하세요.

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for durable project facts; keep per-operator preferences in your harness's own memory.
- Do not use markdown TODO lists for task tracking.

🛠 주요 기능

  • Dolt 기반: 셀 단위 병합, 네이티브 브랜치, Dolt 원격 저장소를 통한 내장 동기화를 갖춘 버전 관리 SQL 데이터베이스입니다.
  • 에이전트에 최적화: JSON 출력, 의존성 추적, 바로 할 수 있는 작업 자동 감지를 지원합니다.
  • 충돌 없음: 해시 기반 ID(bd-a1b2)로, 여러 에이전트 · 여러 브랜치에서 일할 때 병합 충돌을 막습니다.
  • 압축(Compaction): 의미 기반 "기억 감쇠"로 오래된 완료 작업을 요약해 컨텍스트 창을 아낍니다.
  • 메시징: 스레드(--thread), 일회성 수명, 메일 위임을 지원하는 메시지 이슈 유형이 있습니다.
  • 그래프 링크: relates-to, duplicates, supersedes, replies-to로 지식 그래프를 만듭니다.

📖 필수 명령

명령동작
bd 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는 에픽을 위한 계층형 ID를 지원합니다.

  • bd-a3f8 (에픽)
  • bd-a3f8.1 (작업)
  • bd-a3f8.1.1 (하위 작업)

스텔스 모드: bd init --stealth를 실행하면 메인 저장소에 파일을 커밋하지 않고 Beads를 로컬에서만 쓸 수 있습니다. 공유 프로젝트에서 혼자 쓰기에 알맞습니다. 아래 Git 없이 사용하기를 보세요.

기여자와 관리자: 오픈소스 프로젝트에서 작업할 때는 다음과 같이 합니다.

  • 기여자(포크한 저장소): bd init --contributor를 실행하면 계획용 이슈가 별도 저장소(예: ~/.beads-planning)로 갑니다. 실험적인 작업이 PR에 섞이지 않습니다.
  • 관리자(쓰기 권한이 있는 사람): Beads가 SSH 주소나 자격 증명이 있는 HTTPS로 관리자 역할을 자동으로 알아봅니다. 자격 증명 없이 GitHub HTTPS를 쓰면서 쓰기 권한이 있을 때만 git config beads.role maintainer가 필요합니다.

📦 설치

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

다른 방법: 설치 스크립트 | go install | 소스에서 빌드 | Windows | Arch AUR

요구 사항: macOS, Linux, Windows 또는 FreeBSD. 전체 설치 안내는 docs/getting-started/installation.md를 보세요.

업그레이드하나요? 바이너리를 바꾸는 것만으로 끝나지 않을 때가 있습니다. 요약하면 이렇습니다. 원격 저장소를 쓰는 데이터베이스는 지금 쓰는 bd로 먼저 동기화하고, bd export --all로 백업한 다음, 바이너리를 업그레이드하고, bd info --whats-new, bd hooks install, bd version을 차례로 실행합니다. 원격 저장소를 쓰는 데이터베이스에서 업그레이드가 스키마 마이그레이션을 넘어가면, 지정한 클론 딱 하나에서만 bd migrate schema와 bd dolt push를 실행하고, 나머지 클론은 새 바이너리를 설치한 뒤 bd bootstrap을 실행합니다. 전체 내용은 업그레이드 안내 또는 docs/getting-started/installation.md를 보세요.

보안과 검증

명령과 자격 증명 대상 설정은 .beads/.env가 아니라 셸 환경이나 사용자 설정에서 와야 합니다. .beads/.env는 명령이 아닌 BEADS_*·BD_* 변수와 Dolt 원격 자격 증명 변수 두 개(DOLT_REMOTE_USER, DOLT_REMOTE_PASSWORD)만 받아들입니다. 이 파일 안의 자격 증명 명령, 메일 위임, 편집기, 페이저, Dolt 실행 파일·호스트·자격 증명 파일·루트 경로 재정의, 그 밖의 Dolt 소유 DOLT_* 이름공간(DOLT_SSH_COMMAND, DOLT_PAGER 등), Beads가 아닌 프로세스 변수(GIT_*, SSH_*, LD_*, DYLD_* 등)는 Beads가 무시하고 항목마다 경고를 출력합니다. 명령이나 실행 파일로 이름 붙은 BEADS_*·BD_* 키(_COMMAND, _BIN, _BINARY로 끝나는 것)도 같은 방식으로 무시하며, http 백엔드의 베어러 토큰 BEADS_HTTP_TOKEN과 평문 허용 설정 BEADS_HTTP_ALLOW_INSECURE, bd serve가 베어러를 받는 토큰 파일(BEADS_SERVE_TOKEN_FILE), bd가 쓰는 파일(힙 프로파일과 MemStats 요약인 BEADS_MEM_PROFILE, BEADS_MEM_STATS, 프록시 Dolt 서버의 로그 BEADS_PROXIED_SERVER_LOG)도 무시합니다. .beads/.env의 값은 글자 그대로 받아들입니다. $VAR나 ${VAR}를 쓴 값은 환경에서 채워 넣지 않고 경고와 함께 무시하므로, 커밋된 파일이 내 환경의 비밀값을 작업 공간이 다른 곳으로 보내는 설정에 복사해 갈 수 없습니다. 값을 직접 쓰거나 셸에서 설정하세요. bd config set mail.delegate "gt mail"는 복제되는 데이터베이스가 아니라 사용자 전역 YAML에 씁니다. 작업 공간 설정 API는 mail.delegate를 거부합니다. 메일 위임도 프로젝트의 .beads/config.yaml을 무시하며, 셸 환경 변수와 사용자 전역 YAML만 위임 대상을 고를 수 있습니다.

내려받은 바이너리를 믿기 전에, 릴리스의 checksums.txt와 체크섬을 대조해 확인하세요.

설치 스크립트는 설치 전에 릴리스 체크섬을 검증합니다. 수동 설치라면 처음 실행하기 전에 직접 검증하세요.

macOS에서 scripts/install.sh는 기본적으로 내려받은 서명을 그대로 유지합니다. 로컬 임시(ad-hoc) 재서명은 BEADS_INSTALL_RESIGN_MACOS=1로 직접 켜야 합니다.

Windows 백신 오탐 안내와 검증 절차는 docs/reference/antivirus.md를 보세요.

💾 저장 방식

Beads는 데이터베이스로 Dolt를 씁니다. 방식은 두 가지입니다.

  • 임베디드(기본) — bd init. Dolt가 프로세스 안에서 돌고 데이터는 .beads/embeddeddolt/에 있으며, 쓰는 쪽은 하나뿐입니다. 대부분의 사용자에게 권장합니다.
  • 서버 — bd init --server. 여러 쓰기 주체가 동시에 쓸 수 있도록 외부 dolt sql-server에 연결합니다. 데이터는 .beads/dolt/에 있습니다.

기기 간 동기화는 git 원격 저장소의 refs/dolt/data에 대해 bd dolt push / bd dolt pull로 합니다. .beads/issues.jsonl은 뷰어와 데이터 교환을 위한 내보내기 파일이며, 원본도 백업도 아닙니다. 백업과 방식 간 이전은 bd backup으로, 공간 회수는 bd prune / bd purge로 합니다.

연결 플래그, 소켓, 유지 관리, 백업, 이전의 자세한 내용은 Dolt 백엔드 가이드에 있습니다.

스키마 버전 보호

bd는 데이터베이스를 열 때 스키마 버전을 확인합니다. 더 새로운 바이너리가 데이터베이스를 마이그레이션해 두었는데 오래된 바이너리가 그것을 열려고 하면, 알아보기 어려운 SQL 오류가 나는 질의를 보내는 대신 해결 방법이 담긴 오류와 함께 종료합니다.

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

언제 동작하나: 데이터베이스 스키마가 바이너리보다 앞서 있을 때만 동작합니다(더 새로운 바이너리가 데이터베이스를 마이그레이션했고, 이 바이너리는 그 마이그레이션을 모르는 경우). 바이너리가 데이터베이스를 앞으로 마이그레이션하는 평소의 업그레이드에는 영향이 없습니다. 이 검사는 저장소를 열 때마다 실행됩니다. 임베디드, 서버 모드, 프록시 서버 작업 공간, bd serve 시작 때 모두 해당합니다. 새로운 bd가 데이터베이스를 마이그레이션했을 때 이미 실행 중이던 bd serve는 재시작할 때까지 계속 서비스하며, 프록시 --dry-run/--inspect 미리 보기는 검사하지 않으므로, 더 새로운 bd로 마이그레이션한 뒤에는 오래 실행 중인 서버를 재시작하세요.

탈출구: BD_IGNORE_SCHEMA_SKEW=1(또는 --ignore-schema-skew)은 stderr에 경고를 내고 보호를 건너뜁니다. 앞으로 가는 마이그레이션이 추가만 하는 안전한 것이고 내 작업에 안전하다고 알 때만 쓰세요.

🔌 HTTP 백엔드 (실험적)

작업 공간은 로컬 Dolt 데이터베이스를 여는 대신 원격 bd serve와 HTTP로 통신할 수도 있습니다. 공유 서버에 붙는 얇은 클라이언트가 필요하거나, beads를 다른 프로그램에 라이브러리로 넣을 때 쓸모가 있습니다.

# Point this workspace at a server (verifies the server first; writes nothing on failure)
bd connect https://bd.example.com --expect-project-id my-project

# The everyday commands work the same way: create, show, list, update, close,
# dependencies (including `bd dep tree`), comments, ready/count queries, and
# batch apply all round-trip over the wire with the same semantics as a local
# database. So does `bd ready --claim`, except against an older server or while
# any issue holds an unsatisfied external ref: then it lists and claims in two
# steps rather than one transaction (ledger row L14, linked below).
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd close bd-a1b2 "Fixed"

# Loopback needs no TLS
bd connect http://127.0.0.1:8080

# Forget the server and restore this workspace's previous backend selection
bd connect --clear

그래도 HTTP 모드는 로컬 모드를 바이트 단위로 똑같이 흉내 내지는 않습니다. 일부 동작은 (통신 규격에 표현할 방법이 없어서) 의도적으로 거부되고, 일부는 읽는 데 오해를 주지 않는 다른 동작으로 바뀝니다(예: 범위를 정하지 않은 몇몇 목록 조회는 한 번의 질의로 얻는 스냅샷 격리를 잃고, 대신 서버를 쪽 단위로 훑습니다). 이런 차이는 모두 의도해서 시험하는 항목이며, 조용히 빠진 곳은 없습니다. 확인하지 않은 작업 흐름을 HTTP 기반 작업 공간에 맡기기 전에, 무엇이 왜 다른지 생성된 전체 목록인 engdocs/design/http-divergence-ledger.md를 보세요. 미리 알아 둘 거부 사례가 하나 있습니다. bd close --claim-next는 HTTP에서 아무것도 닫지 않습니다. 일괄 닫기가 맡기(claim)를 실어 보낼 수 없기 때문입니다. --claim 없이 닫은 다음 bd ready --claim을 실행하세요.

저장소 간 의존성 정책은 HTTP에서도 유지됩니다. 클라이언트가 각 external: 참조를 자기 external_projects 설정으로 해석합니다. bd dep tree는 그 참조를 잎 노드로 보여 주고, 충족되지 않은 동안 그 이슈는 bd ready와 bd ready --claim에서 빠지며, bd close는 --force 없이는 닫기를 거부합니다. 그 정책을 서버가 직접 적용한다고 알리는 서버는, 대신 그 서버를 믿습니다.

미리 알아 둘 CLI 수준의 차이가 세 가지 있습니다.

  • ID는 정확히 일치해야 합니다. 줄여 쓴 ID는 펼쳐지지 않으며(통신 규격에 부분 문자열 검색이 없어서), 없는 ID는 한 번 조회한 뒤 찾을 수 없다고 보고합니다.
  • bd update -s closed는 closed_by_session(--session 또는 CLAUDE_SESSION_ID에서 오는 값)을 기록하지 않습니다. 통신 규격의 update가 그것을 실을 수 없기 때문이며, 닫기 자체는 평소처럼 이루어집니다. bd close는 세션을 기록합니다. bd reopen의 이력에는 서버 자체의 라벨이 담깁니다.
  • 기여자 자동 라우팅(routing.* 설정)은 서버 설정이 아니라 로컬 config.yaml / 환경에서만 읽습니다. 그 대상이 로컬 경로이기 때문입니다.

bd connect는 성공하면 두 가지를 씁니다. .beads/metadata.json에 "backend": "http"가 들어가고, 사용자별이며 git이 추적하지 않는 보조 파일(.beads/http_target.json)에 서버 주소와 고정한 프로젝트 ID가 기록됩니다. 자격 증명은 디스크에 쓰지 않습니다. 서버가 베어러 자격 증명을 요구하면 BEADS_HTTP_TOKEN=host[:port]=<token>, 그다음 BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command>(토큰을 출력하는 도우미), 그다음 자격 증명 파일, 그다음 자격 증명 없음의 순서로 가져옵니다. 두 변수 모두 어느 서버용인지 이름을 지정해야 하며(포트가 없는 패턴은 모든 포트의 그 호스트와 맞습니다), 값만 있는 것은 거부합니다. 그러면 작업 공간의 http_target.json이 가리키는 아무 서버에나 보내질 수 있기 때문입니다. 비루프백 서버에 평문 http://로 연결하는 것은 기본적으로 거부됩니다(베어러 자격 증명이 암호화 없이 네트워크를 건너게 되므로). 무시하려면 --allow-plaintext를 주거나 https://를 쓰세요. 이미 다른 백엔드를 선택한 작업 공간을 바꾸려면 --force가 필요합니다.

각 읽기(GET 또는 POST 일괄 조회)는 첫 시도에서 요청을 보낸 시점부터 서버의 응답 헤더를 받을 때까지 15초를 줍니다(BEADS_HTTP_RESPONSE_HEADER_TIMEOUT: 30s 같은 기간, 초 단위 숫자, 또는 off). 헤더가 제때 오지 않거나 연결이 재설정된 읽기는 다른 연결로 한 번 재시도하며, 재시도마다 횟수와 함께 stderr에 기록합니다. 재시도에는 헤더 타이머가 없지만, 첫 시도를 보낸 때부터 센 요청 전체 60초 제한의 남은 시간 안에서 실행됩니다. 느리지만 건강한 읽기는 재시도의 헤더와 본문이 그 남은 시간 안에 들어가면 여전히 끝납니다(헤더 타임아웃 뒤에는 약 45초). 더 오래 걸리는 읽기는 이제 60초에 실패합니다. 헤더 타이머는 아직 스트리밍 중인 본문을 끊지 않으며, 60초 제한은 끊습니다. events:watch 스트림의 연결에는 헤더 타이머도 재시도도 없습니다. Windows에서는 재설정된 연결을 이른 EOF로 나타날 때만 재시도합니다. 이 검사가 Unix의 재설정 오류(ECONNRESET)와 맞추기 때문이며, Windows의 재설정(WSAECONNRESET)은 그것이 아닙니다. 쓰기에는 헤더 타이머가 없고(서버는 커밋한 뒤에야 쓰기에 응답하므로 큰 쓰기는 느려도 정상일 수 있습니다) 재시도도 하지 않습니다. 쓰기를 보낸 뒤 헤더가 오기 전에 60초 제한이 끝나면, 적용됐을 수도 아닐 수도 있으므로 서버 호스트 이름을 밝힌 오류와 함께 실패합니다. 100개를 넘는 항목의 일괄 적용(예: 큰 bd create --graph 계획)은 60초 대신 6분을 받습니다. bd serve가 그런 요청에 --large-apply-ceiling(기본 5분)을 주고 클라이언트가 포기한 뒤에도 끝내기 때문입니다. 상한을 약 5분 15초 넘게 올린 서버는 클라이언트보다 오래 걸릴 수 있습니다. 연결 시간 제한이나 TLS 시간 제한은 서버가 요청을 본 적이 없으므로 평범한 연결 오류로 남으며, 연결에 실패하면 어느 주소가 연결을 거부했는지(듣고 있는 것이 없음), 응답하지 않았는지(막힌 포트이거나 꺼진 호스트, 다이얼러의 30초 뒤), 어느 호스트 이름이 해석되지 않았는지를 알려 줍니다. off는 헤더 타이머만 끕니다. 재설정된 읽기는 여전히 재시도하고, 쓰기의 시간 초과도 위에서 설명한 대로 보고됩니다.

서버가 bd의 외부 의존성 정책을 직접 적용하는지(policy.external_dependencies 기능)는 서버 주소와 고정한 프로젝트마다 5분 동안 사용자 캐시 디렉터리의 beads/http-policy/에 기억해 둡니다. 그래서 bd ready가 목록을 조회할 때마다 그것을 알아보려고 서버 맥락을 가져오지 않습니다. BEADS_HTTP_POLICY_CACHE_TTL로 이 시간을 정합니다(1m 같은 기간, 초 단위 숫자, 또는 off). 다른 구성으로 재시작한 서버는 시간이 지나면 한 번 새로 확인됩니다. 맡기기와 닫기는 캐시된 답을 쓰지 않고 서버에 물어봅니다. 오래된 답이 외부에서 막힌 작업에 대한 클라이언트 쪽 거부를 건너뛰게 할 수 있기 때문입니다. 프로젝트를 고정하지 않고 연결한 작업 공간은 캐시되지 않습니다.

bd search, bd show --current, bd recompute-blocked도 HTTP에서 각자의 방식으로 동작합니다. bd search는 서버의 목록 조회에 검색어(q, issues.list.search 기능 뒤)를 실어 요청하며, 그 기능을 알리지 않는 서버에는 연결하기 전에 거부합니다. bd list --no-assignee, --title, --id도 마찬가지로 목록 조회의 no_assignee, title, 반복 가능한 id를 타며 각각 자기 기능(issues.list.noAssignee, issues.list.title, issues.list.ids) 뒤에 있습니다. bd list의 나머지 필터(--updated-*, --closed-*, --defer-*, --due-*, --priority*, 텍스트와 외부 참조 일치, --spec, --label-pattern/--label-regex, --exclude-type, --no-parent, --no-labels, --empty-description, --pinned/--no-pinned, --deferred, --overdue, --mol-type, --wisp-type)는 issues.list.filters라는 기능 하나 뒤에서 처리됩니다. 시간 범위는 로컬에서와 똑같이 클라이언트가 해석하고, --overdue는 서버의 시계와 비교합니다. 기본 --parent 트리 보기는 아직 이런 필터를 싣지 못하므로, 필터를 조용히 버리는 대신 거부합니다. --flat이나 --json은 필터를 그 부모의 직계 자식(하위 트리 전체가 아님)에 적용합니다. bd show --current는 서버의 불리언 질의로 그 담당자의 진행 중이거나 걸어 둔(hooked) 이슈를 찾습니다. bd recompute-blocked는 아무것도 하지 않고 0으로 종료합니다. 서버가 모든 쓰기에서 is_blocked를 유지하며, 오래된 플래그의 복구는 서버 자신의 작업 공간에서 하기 때문입니다(--json은 {"rows_corrected": 0, "maintained_by": "server"}를 보고합니다).

cmd/bd를 실행하지 않고 beads를 라이브러리로 연결하는 프로그램은 공개 backend/http 패키지(bdhttp.Register)로 이 백엔드를 직접 등록하며, beads.OpenBestAvailableWith로 호출자 한 명에게만 범위가 한정된 자격 증명으로 작업 공간을 열 수 있습니다. 여러 테넌트를 다루는 경우는 그 패키지의 문서 주석을 보세요. 이 기능은 실험적입니다. 정확한 beads 버전을 고정해서 쓰세요.

🧹 Claude 규칙 압축

bd rules audit은 .claude/rules/*.md에서 모순과 거의 중복된 규칙을 찾고, bd rules compact는 관련된 규칙을 하나의 합성 규칙으로 합칩니다.

bd rules compact --auto           # Preview: composite, dropped lines, backups, deletes
bd rules compact --auto --force   # Apply

압축은 --force를 주지 않으면 미리 보기만 합니다. 합성 규칙은 원본들의 **Do:**와 **Don't:** 줄만 남기며, 미리 보기가 버려지는 나머지 줄을 모두 보여 줍니다. 적용하면 합성 규칙을 쓰고, 원본마다 <name>.md.backup으로 복사한 다음, 원본을 지웁니다. 합성 규칙이나 백업 경로가 이미 있는 묶음은 거부합니다. 합치기를 되돌리려면 합성 규칙을 지우고 각 .md.backup의 이름을 .md로 되돌리세요.

🔁 GitHub 이슈 동기화

bd github sync(와 bd github pull/push)는 github.owner와 github.repo로 지정한 저장소 하나를 동기화하지만, 데이터베이스에는 여러 저장소의 beads가 들어 있을 수 있습니다. v1.3.2 이후 릴리스에서는 동기화가 이슈 URL이 설정한 저장소를 가리키는 beads만 맞추고, 가져오고, 갱신합니다. 그래서 두 번째 저장소의 이슈 1313을 가져와도 첫 번째 저장소의 이슈 1313에 연결된 bead를 덮어쓰지 않고 새 bead를 만듭니다. github:<number> 참조에는 저장소가 없으므로 항상 설정한 저장소의 것으로 읽습니다. 이름을 바꾸거나 이전한 저장소는 설정에 있는 이름이 무엇이든 계속 동기화됩니다. GitHub가 이전 이름을 그 저장소로 리디렉션하고, 동기화는 beads가 연결된 다른 이름마다 이제 어느 저장소에 속하는지 GitHub에 묻기 때문입니다(이름당 요청 한 번). 그래서 옛 이름으로 연결된 beads와 새 이름으로 연결된 beads가 모두 자기 이슈에 맞춰진 채 유지되고, pull이 현재 URL로 다시 연결해 줍니다. 옛 이름이 이제 다른 저장소에 속한다면, 그 이름으로 연결된 beads는 다른 저장소의 것으로 칩니다. 그것들을 다시 연결하세요(bd update <id> --external-ref <new-url>). 그렇지 않으면 다음 pull이 그 이슈들을 새 beads로 다시 가져옵니다. GitHub가 이런 요청 중 하나에 답하지 않으면(404가 아닌 모든 실패: 장애, 끊어진 연결, 요청 한도, 거부된 토큰), 어느 beads가 설정한 저장소의 것인지 모른 채 동기화하는 대신 저장소 이름을 밝힌 오류와 함께 명령이 멈춥니다. 그런 beads를 건너뛰는 동기화는 그 수정 사항 위로 커서를 넘기고, 나중의 동기화가 충돌 없이 그 수정을 덮어쓸 수 있기 때문입니다. 일시적인 실패라면 명령을 다시 실행하세요. 오류가 내 beads가 연결된 다른 저장소를 가리키는데 GitHub가 그 저장소에 대한 토큰을 거부한다면(403), 토큰에 그 저장소 읽기 권한을 주세요. 그 이름이 설정한 저장소의 옛 이름이라면, 그 beads를 이슈의 현재 URL로 다시 연결해도 조회가 끝납니다.

🌐 커뮤니티 도구

커뮤니티가 만든 UI, 확장, 연동(터미널 인터페이스, 웹 UI, 편집기 확장, 네이티브 앱 포함)의 선별 목록은 docs/community-tools.md를 보세요.

같은 분야에서 다른 문제를 푸는 인접하거나 보완적인 프로젝트는 docs/related-projects.md를 보세요.

🚀 Git 없이 사용하기

Beads는 git 없이도 동작합니다. 저장소 백엔드는 Dolt 데이터베이스이며, git 연동(훅, 저장소 탐색, 신원)은 선택 사항입니다.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR은 git 저장소 탐색을 건너뛰고 bd가 .beads/ 데이터베이스 디렉터리를 어디에 둘지 알려 줍니다. --stealth는 설정에 no-git-ops: true를 넣어 bd 자체의 git 훅 설치와 git 명령을 끕니다. Dolt의 네트워크 동기화는 막지 않으므로, 그것까지 막으려면 dolt.local-only: true를 설정하세요.

다음과 같은 경우에 유용합니다.

  • git이 아닌 버전 관리(Sapling, Jujutsu, Piper) — .git/ 디렉터리가 필요 없습니다
  • 모노레포 — BEADS_DIR이 특정 하위 디렉터리를 가리키게 합니다
  • CI/CD — 저장소 수준의 부작용 없이 격리된 작업 추적
  • 평가 · 테스트 — /tmp의 일회성 데이터베이스

📝 문서


저장소: https://github.com/gastownhall/beads

평점

–평가 0개 기준
5점
0
4점
0
3점
0
2점
0
1점
0