[TIP]Beads: AI 에이전트를 위한 작업 관리 도구 가이드

Beads는 AI 에이전트(Claude, OpenCode, Cursor 등)를 위해 특별히 설계된 작업 관리 도구입니다. Git을 데이터베이스로 활용하여 작업(Issue)을 관리하므로, 코드와 함께 작업 내역이 버전 관리되고 팀원들과 쉽게 공유됩니다.

🎯 핵심 특징

특징	설명
Git 기반	작업 데이터가 Git 저장소에 저장되어 버전 관리와 협업이 자연스럽게 가능
AI 에이전트 최적화	CLI 명령어 위주로 토큰 소모를 최소화 (1~~2k vs MCP 10~~50k)
자동 훅 제공	Pre-commit, Pre-push 훅으로 데이터 동기화 자동화
멀티 에이전트 지원	Claude, Cursor, Aider 등 다양한 AI 개발 도구와 통합

📊 기존 도구 vs Beads

도구	데이터 저장	토큰 효율	버전 관리	AI 에이전트 통합
Jira/Linear	원격 서버	-	❌	⚠️
GitHub Issues	GitHub	낮음	✅	⚠️
MCP 서버	로컬	매우 낮음	✅	✅
Beads	Git	매우 높음	✅	✅

🚀 설치 방법

시스템에 bd 명령어를 설치해야 합니다. 환경에 맞는 방법을 선택하세요.

curl을 통한 설치 (macOS / Linux, 추천)

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

npm을 통한 설치

npm install -g @beads/bd

Homebrew를 통한 설치 (macOS)

brew install steveyegge/beads/bd

📋 프로젝트 설정

AI 에이전트가 작업할 프로젝트 루트 디렉토리에서 다음을 수행합니다.

1. Beads 초기화

bd init

이 명령은 .beads 디렉토리를 생성하여 작업 데이터를 저장할 준비를 합니다.

2. Git Hooks 설치 (강력 추천)

bd hooks install

에이전트가 작업할 때 데이터 동기화 문제를 방지하기 위해 필수적입니다. Pre-commit, Pre-push 등의 훅을 설치하여 DB와 JSONL 파일 간의 일관성을 유지합니다.

3. 에이전트 지침 추가 (AGENTS.md)

프로젝트 루트의 AGENTS.md (또는 프롬프트 파일)에 다음 내용을 추가하여 에이전트가 Beads를 사용하도록 지시하세요.

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

⚙️ 에이전트 통합 설정

OpenCode나 Claude Code와 같은 에이전트 환경에서 Beads를 효율적으로 사용하기 위해 전용 설정 명령어를 제공합니다.

★ Insight ─────────────────────────────────────

CLI vs MCP 통합 방식 비교:

CLI 방식: 토큰 소모 1~2k, 빠른 속도
MCP 방식: 토큰 소모 10~50k, 상대적으로 느림
가능하면 CLI 방식을 권장합니다.

─────────────────────────────────────────────────

CLI 기반 통합 (추천)

에이전트가 터미널(Shell) 접근 권한이 있는 경우(대부분의 경우), CLI 방식이 가장 효율적입니다.

1. 설정 명령어 실행:

bd setup claude   # Claude Code용 (SessionStart/PreCompact hooked)
# bd setup cursor   # Cursor IDE용 (.cursor/rules/beads.mdc 생성)
# bd setup aider    # Aider용 (.aider.conf.yml 생성)

2. 동작 원리:

세션 시작 시 bd prime 명령이 자동으로 실행되어 에이전트에게 현재 작업 컨텍스트를 주입합니다.
MCP 스키마를 사용하는 것보다 훨씬 가볍고 빠릅니다.

MCP 서버 방식 (대안)

터미널 접근이 불가능한 환경(Claude Desktop 등)에서는 MCP 서버를 사용해야 합니다.

1. UV로 설치:

uv tool install beads-mcp

2. Claude Desktop 설정 (claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

⚠️ 주의: CLI 방식보다 토큰 소모가 크고 느리므로, 터미널 사용이 가능하다면 CLI 방식을 권장합니다.

🎮 주요 명령어

기본 작업 명령어

명령어	설명	예시
`bd ready`	진행 가능한 작업 목록 표시	`bd ready`
`bd create`	새 작업 생성	`bd create "버그 수정" -p 0`
`bd show <ID>`	작업 상세 조회	`bd show bd-a1b2`
`bd update <ID>`	작업 정보 수정	`bd update bd-123 --status in_progress`
`bd close <ID>`	작업 완료 처리	`bd close bd-123 --reason "completed"`
`bd sync`	Git에 변경사항 저장	`bd sync`

상태 값

ready: 진행 가능
in_progress: 진행 중
done: 완료
blocked: 차단됨

우선순위

숫자가 낮을수록 높음 (0이 최우선)

⚠️ AI 에이전트 필독 주의사항

AI 에이전트는 대화형 에디터를 사용할 수 없으므로 다음 규칙을 반드시 따라야 합니다.

금지 사항

명령어	이유	대안
`bd edit`	`vi`나 `nano`가 열려 에이전트가 멈춤	`bd update` 플래그 사용

권장 작업 흐름

# 1. 할 일 확인
bd ready

# 2. 작업 생성 (필요시)
bd create "작업 제목" -p 0

# 3. 상태 변경
bd update <ID> --status in_progress

# 4. 내용 수정
bd update <ID> --description "새로운 설명..."
bd update <ID> --acceptance "완료 기준..."

# 5. 작업 완료
bd close <ID> --reason "completed"

# 6. 세션 종료 시 필수 동기화
bd sync

💡 실전 활용 예시

시나리오: 로그인 페이지 버그 수정

사용자: "로그인 페이지 버그 수정해줘."

에이전트의 행동:

# 1. 관련 작업 확인
bd ready

# 2. 작업 생성 (없는 경우)
bd create "로그인 페이지 버그 수정" -p 1

# 3. 상태 변경
bd update bd-xxx --status in_progress

# 4. 코드 수정 및 테스트 수행
# (에이전트가 개발 작업 수행)

# 5. 작업 완료
bd close bd-xxx --reason "completed"

# 6. 변경사항 저장
bd sync

🔧 문제 해결

자주 발생하는 문제

문제	해결 방법
`bd: command not found`	설치 스크립트를 다시 실행하거나 PATH 확인
Git 훅이 작동하지 않음	`bd hooks install` 재실행
에이전트가 작업을 인식하지 못함	`bd prime` 실행으로 컨텍스트 갱신
동기화 오류 발생	`bd sync --force`로 강제 동기화

📚 추가 자료

공식 저장소: github.com/steveyegge/beads
문서: Beads GitHub Wiki
관련 도구: Claude Code, Cursor, Aider

⚠️ 면책 조항

본 가이드를 따르면서 발생하는 모든 결과에 대한 책임은 전적으로 사용자 본인에게 있습니다. 이 문서는 참고용으로 제공되며, 작성자는 어떠한 손해나 문제에 대해 책임지지 않습니다.

금지 사항:

본 내용을 악의적인 목적으로 사용하는 것을 엄격히 금지합니다.
타인의 권리를 침해하거나 불법적인 활동에 사용하는 것을 금지합니다.
상업적 목적의 무단 복제나 재배포를 금지합니다.

본 가이드의 내용은 학습 및 교육 목적으로만 사용해야 합니다.

🎯 핵심 특징

특징	설명
Git 기반	작업 데이터가 Git 저장소에 저장되어 버전 관리와 협업이 자연스럽게 가능
AI 에이전트 최적화	CLI 명령어 위주로 토큰 소모를 최소화 (1~~2k vs MCP 10~~50k)
자동 훅 제공	Pre-commit, Pre-push 훅으로 데이터 동기화 자동화
멀티 에이전트 지원	Claude, Cursor, Aider 등 다양한 AI 개발 도구와 통합

📊 기존 도구 vs Beads

도구	데이터 저장	토큰 효율	버전 관리	AI 에이전트 통합
Jira/Linear	원격 서버	-	❌	⚠️
GitHub Issues	GitHub	낮음	✅	⚠️
MCP 서버	로컬	매우 낮음	✅	✅
Beads	Git	매우 높음	✅	✅

🚀 설치 방법

시스템에 bd 명령어를 설치해야 합니다. 환경에 맞는 방법을 선택하세요.

curl을 통한 설치 (macOS / Linux, 추천)

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

npm을 통한 설치

npm install -g @beads/bd

Homebrew를 통한 설치 (macOS)

brew install steveyegge/beads/bd

📋 프로젝트 설정

AI 에이전트가 작업할 프로젝트 루트 디렉토리에서 다음을 수행합니다.

1. Beads 초기화

bd init

이 명령은 .beads 디렉토리를 생성하여 작업 데이터를 저장할 준비를 합니다.

2. Git Hooks 설치 (강력 추천)

bd hooks install

3. 에이전트 지침 추가 (AGENTS.md)

프로젝트 루트의 AGENTS.md (또는 프롬프트 파일)에 다음 내용을 추가하여 에이전트가 Beads를 사용하도록 지시하세요.

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

⚙️ 에이전트 통합 설정

OpenCode나 Claude Code와 같은 에이전트 환경에서 Beads를 효율적으로 사용하기 위해 전용 설정 명령어를 제공합니다.

★ Insight ─────────────────────────────────────

CLI vs MCP 통합 방식 비교:

CLI 방식: 토큰 소모 1~2k, 빠른 속도
MCP 방식: 토큰 소모 10~50k, 상대적으로 느림
가능하면 CLI 방식을 권장합니다.

─────────────────────────────────────────────────

CLI 기반 통합 (추천)

에이전트가 터미널(Shell) 접근 권한이 있는 경우(대부분의 경우), CLI 방식이 가장 효율적입니다.

1. 설정 명령어 실행:

bd setup claude   # Claude Code용 (SessionStart/PreCompact hooked)
# bd setup cursor   # Cursor IDE용 (.cursor/rules/beads.mdc 생성)
# bd setup aider    # Aider용 (.aider.conf.yml 생성)

2. 동작 원리:

세션 시작 시 bd prime 명령이 자동으로 실행되어 에이전트에게 현재 작업 컨텍스트를 주입합니다.
MCP 스키마를 사용하는 것보다 훨씬 가볍고 빠릅니다.

MCP 서버 방식 (대안)

터미널 접근이 불가능한 환경(Claude Desktop 등)에서는 MCP 서버를 사용해야 합니다.

1. UV로 설치:

uv tool install beads-mcp

2. Claude Desktop 설정 (claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

⚠️ 주의: CLI 방식보다 토큰 소모가 크고 느리므로, 터미널 사용이 가능하다면 CLI 방식을 권장합니다.

🎮 주요 명령어

기본 작업 명령어

명령어	설명	예시
`bd ready`	진행 가능한 작업 목록 표시	`bd ready`
`bd create`	새 작업 생성	`bd create "버그 수정" -p 0`
`bd show <ID>`	작업 상세 조회	`bd show bd-a1b2`
`bd update <ID>`	작업 정보 수정	`bd update bd-123 --status in_progress`
`bd close <ID>`	작업 완료 처리	`bd close bd-123 --reason "completed"`
`bd sync`	Git에 변경사항 저장	`bd sync`

상태 값

ready: 진행 가능
in_progress: 진행 중
done: 완료
blocked: 차단됨

우선순위

숫자가 낮을수록 높음 (0이 최우선)

⚠️ AI 에이전트 필독 주의사항

AI 에이전트는 대화형 에디터를 사용할 수 없으므로 다음 규칙을 반드시 따라야 합니다.

금지 사항

명령어	이유	대안
`bd edit`	`vi`나 `nano`가 열려 에이전트가 멈춤	`bd update` 플래그 사용

권장 작업 흐름

# 1. 할 일 확인
bd ready

# 2. 작업 생성 (필요시)
bd create "작업 제목" -p 0

# 3. 상태 변경
bd update <ID> --status in_progress

# 4. 내용 수정
bd update <ID> --description "새로운 설명..."
bd update <ID> --acceptance "완료 기준..."

# 5. 작업 완료
bd close <ID> --reason "completed"

# 6. 세션 종료 시 필수 동기화
bd sync

💡 실전 활용 예시

시나리오: 로그인 페이지 버그 수정

사용자: "로그인 페이지 버그 수정해줘."

에이전트의 행동:

# 1. 관련 작업 확인
bd ready

# 2. 작업 생성 (없는 경우)
bd create "로그인 페이지 버그 수정" -p 1

# 3. 상태 변경
bd update bd-xxx --status in_progress

# 4. 코드 수정 및 테스트 수행
# (에이전트가 개발 작업 수행)

# 5. 작업 완료
bd close bd-xxx --reason "completed"

# 6. 변경사항 저장
bd sync

🔧 문제 해결

자주 발생하는 문제

문제	해결 방법
`bd: command not found`	설치 스크립트를 다시 실행하거나 PATH 확인
Git 훅이 작동하지 않음	`bd hooks install` 재실행
에이전트가 작업을 인식하지 못함	`bd prime` 실행으로 컨텍스트 갱신
동기화 오류 발생	`bd sync --force`로 강제 동기화

📚 추가 자료

공식 저장소: github.com/steveyegge/beads
문서: Beads GitHub Wiki
관련 도구: Claude Code, Cursor, Aider

⚠️ 면책 조항

금지 사항:

본 내용을 악의적인 목적으로 사용하는 것을 엄격히 금지합니다.
타인의 권리를 침해하거나 불법적인 활동에 사용하는 것을 금지합니다.
상업적 목적의 무단 복제나 재배포를 금지합니다.

본 가이드의 내용은 학습 및 교육 목적으로만 사용해야 합니다.

🎯 핵심 특징

📊 기존 도구 vs Beads

🚀 설치 방법

curl을 통한 설치 (macOS / Linux, 추천)

npm을 통한 설치

Homebrew를 통한 설치 (macOS)

📋 프로젝트 설정

1. Beads 초기화

2. Git Hooks 설치 (강력 추천)

3. 에이전트 지침 추가 (AGENTS.md)

⚙️ 에이전트 통합 설정

CLI 기반 통합 (추천)

MCP 서버 방식 (대안)

🎮 주요 명령어

기본 작업 명령어

상태 값

우선순위

⚠️ AI 에이전트 필독 주의사항

금지 사항

권장 작업 흐름

💡 실전 활용 예시

시나리오: 로그인 페이지 버그 수정

🔧 문제 해결

자주 발생하는 문제

📚 추가 자료

⚠️ 면책 조항

태그

🎯 핵심 특징

📊 기존 도구 vs Beads

🚀 설치 방법

curl을 통한 설치 (macOS / Linux, 추천)

npm을 통한 설치

Homebrew를 통한 설치 (macOS)

📋 프로젝트 설정

1. Beads 초기화

2. Git Hooks 설치 (강력 추천)

3. 에이전트 지침 추가 (AGENTS.md)

⚙️ 에이전트 통합 설정

CLI 기반 통합 (추천)

MCP 서버 방식 (대안)

🎮 주요 명령어

기본 작업 명령어

상태 값

우선순위

⚠️ AI 에이전트 필독 주의사항

금지 사항

권장 작업 흐름

💡 실전 활용 예시

시나리오: 로그인 페이지 버그 수정

🔧 문제 해결

자주 발생하는 문제

📚 추가 자료

⚠️ 면책 조항

태그