Beads - Memória de Tarefas Persistente para Agentes de IA
Rastreador de problemas baseado em grafos que sobrevive à compactação de conversas. Fornece memória persistente para trabalho em várias sessões com dependências complexas.
Visão Geral
bd (beads) substitui listas de tarefas em markdown por um grafo ciente de dependências armazenado no git. Ao contrário do TodoWrite (escopo de sessão), o bd persiste entre compactações e rastreia dependências complexas.
Distinção Principal:
- bd: Trabalho em várias sessões, dependências, sobrevive à compactação, apoiado por git
- TodoWrite: Tarefas de sessão única, execução linear, escopo da conversa
Capacidades Principais:
- 📊 Gráficos de Dependência: Rastreie o que bloqueia o quê (bloqueia, pai-filho, descoberto de, relacionado)
- 💾 Sobrevivência à Compactação: As tarefas persistem quando o histórico da conversa é compactado
- 🐙 Integração com Git: Problemas versionados em
.beads/issues.jsonl, sincronize combd sync - 🔍 Descoberta Inteligente: Encontra automaticamente trabalho pronto (
bd ready), trabalho bloqueado (bd blocked) - 📝 Trilhas de Auditoria: Histórico completo de mudanças de status, anotações e decisões
- 🏷️ Metadados Ricos: Prioridade (P0-P4), tipos (bug/feature/task/epic), rótulos, responsáveis
Quando Usar bd vs TodoWrite:
- ❓ "Vou precisar deste contexto em 2 semanas?" → SIM = bd
- ❓ "O histórico da conversa pode ser compactado?" → SIM = bd
- ❓ "Isso tem bloqueadores/dependências?" → SIM = bd
- ❓ "Isso é um trabalho difuso/exploratório?" → SIM = bd
- ❓ "Isso será concluído nesta sessão?" → SIM = TodoWrite
- ❓ "Isso é apenas uma lista de tarefas para mim agora?" → SIM = TodoWrite
Regra de Decisão: Se retomar em 2 semanas seria difícil sem o bd, use o bd.
Pré-requisitos
Obrigatórios:
- CLI bd: Versão 0.34.0 ou posterior instalada e no PATH
- Repositório Git: O diretório atual deve ser um repositório git
- Inicialização:
bd initdeve ser executado uma vez (humanos fazem isso, não agentes)
Verificar Instalação:
bd --version # Deve retornar 0.34.0 ou posterior
Configuração Inicial (humanos executam uma vez):
cd /caminho/para/seu/repo
bd init # Cria o diretório .beads/ com o banco de dados
Opcionais:
- Variável de ambiente BEADS_DIR para local alternativo do banco de dados
- Daemon para sincronização em segundo plano:
bd daemon --start
Instruções
Protocolo de Início de Sessão
Toda sessão, comece aqui:
Passo 1: Verificar Trabalho Pronto
bd ready
Mostra tarefas sem bloqueadores abertos, ordenadas por prioridade (P0 → P4).
O que isso mostra:
- ID da Tarefa (ex.:
myproject-abc) - Título
- Nível de prioridade
- Tipo de problema (bug, feature, task, epic)
Exemplo de saída:
claude-code-plugins-abc [P1] [task] open
Implementar autenticação de usuário
claude-code-plugins-xyz [P0] [epic] in_progress
Refatorar camada de banco de dados
Passo 2: Escolher a Tarefa de Maior Prioridade
Escolha a tarefa de maior prioridade (P0 > P1 > P2 > P3 > P4) que estiver pronta.
Passo 3: Obter Contexto Completo
bd show <id-da-tarefa>
Exibe:
- Descrição completa da tarefa
- Grafo de dependência (o que bloqueia isso, o que isso bloqueia)
- Trilha de auditoria (todas as mudanças de status, anotações)
- Metadados (criação, atualização, responsável, rótulos)
Passo 4: Começar a Trabalhar
bd update <id-da-tarefa> --status in_progress
Marca a tarefa como sendo ativamente trabalhada.
Passo 5: Adicionar Anotações Enquanto Trabalha
bd update <id-da-tarefa> --notes "Concluído: X. Em andamento: Y. Bloqueado por: Z"
Crucial para a sobrevivência à compactação: Escreva anotações como se estivesse explicando a um agente futuro sem nenhum contexto de conversa.
Formato da Anotação (melhor prática):
CONCLUÍDO: Entregáveis específicos (ex.: "implementei endpoint de refresh JWT + limitação de taxa")
EM ANDAMENTO: Estado atual + próximo passo imediato
BLOQUEADORES: O que está impedindo o progresso
DECISÕES PRINCIPAIS: Contexto importante ou orientação do usuário
Fluxo de Criação de Tarefas
Quando Criar Tarefas
Crie tarefas bd quando:
- O usuário mencionar rastrear trabalho entre sessões
- O usuário disser "devemos consertar/construir/adicionar X"
- O trabalho tiver dependências ou bloqueadores
- Trabalho exploratório/de pesquisa com limites difusos
Criação Básica de Tarefa
bd create "Título da tarefa" -p 1 --type task
Argumentos:
- Título: Breve descrição (obrigatório)
- Prioridade: 0-4 onde 0=crítico, 1=alto, 2=médio, 3=baixo, 4=backlog (padrão: 2)
- Tipo: bug, feature, task, epic, chore (padrão: task)
Exemplo:
bd create "Corrigir bug de autenticação" -p 0 --type bug
Criar com Descrição
bd create "Implementar OAuth" -p 1 --description "Adicionar suporte OAuth2 para Google, GitHub, Microsoft. Usar biblioteca passport.js."
Épico com Filhos
# Criar épico pai
bd create "Épico: Implementação OAuth" -p 0 --type epic
# Retorna: myproject-abc
# Criar tarefas filhas
bd create "Pesquisar provedores OAuth" -p 1 --parent myproject-abc
bd create "Implementar endpoints de autenticação" -p 1 --parent myproject-abc
bd create "Adicionar UI de login no frontend" -p 2 --parent myproject-abc
Fluxo de Atualização e Progresso
Alterar Status
bd update <id-da-tarefa> --status <novo-status>
Valores de Status:
open- Não iniciadoin_progress- Trabalhando ativamenteblocked- Travado, esperando algoclosed- Concluído
Exemplo:
bd update myproject-abc --status blocked
Adicionar Anotações de Progresso
bd update <id-da-tarefa> --notes "Atualização de progresso aqui"
Anexa ao campo de anotações existente (não substitui).
Alterar Prioridade
bd update <id-da-tarefa> -p 0 # Elevar para crítico
Adicionar Rótulos
bd label add <id-da-tarefa> backend
bd label add <id-da-tarefa> security
Rótulos fornecem categorização transversal além de status/tipo.
Gerenciamento de Dependências
Adicionar Dependências
bd dep add <id-filho> <id-pai>
Significado: <id-pai> bloqueia <id-filho> (o pai deve ser concluído primeiro).
Tipos de Dependência:
- blocks: O pai deve fechar antes do filho ficar pronto
- parent-child: Relacionamento hierárquico (épicos e subtarefas)
- discovered-from: A tarefa A levou à descoberta da tarefa B
- related: As tarefas estão relacionadas, mas não se bloqueiam
Exemplo:
# Implantação bloqueada pela aprovação dos testes
bd dep add tarefa-implantacao tarefa-teste # tarefa-teste bloqueia tarefa-implantacao
Visualizar Dependências
bd dep list <id-da-tarefa>
Mostra:
- O que esta tarefa bloqueia (dependentes)
- O que bloqueia esta tarefa (bloqueadores)
Prevenção de Dependência Circular
O bd previne automaticamente dependências circulares. Se você tentar criar um ciclo, o comando falha.
Fluxo de Conclusão
Fechar uma Tarefa
bd close <id-da-tarefa> --reason "Resumo da conclusão"
Melhor Prática: Inclua sempre um motivo descrevendo o que foi realizado.
Exemplo:
bd close myproject-abc --reason "Concluído: Endpoints OAuth implementados com provedores Google, GitHub. Testes passando."
Verificar Trabalho Recentemente Desbloqueado
Após fechar uma tarefa, execute:
bd ready
Fechar uma tarefa pode desbloquear tarefas dependentes, tornando-as prontas.
Fechar Épicos Quando os Filhos Concluírem
bd epic close-eligible
Fecha automaticamente épicos onde todas as tarefas filhas estão fechadas.
Fluxo de Sincronização Git
Sincronização Tudo-em-Um
bd sync
Executa:
- Exportar banco de dados para
.beads/issues.jsonl - Commitar alterações no git
- Puxar do remoto (fazer merge se necessário)
- Importar JSONL atualizado de volta para o banco de dados
- Enviar commits locais para o remoto
Use quando: Fim da sessão, antes de passar para um colega, após progresso significativo.
Apenas Exportar
bd export -o backup.jsonl
Cria backup JSONL sem operações git.
Apenas Importar
bd import -i backup.jsonl
Importa arquivo JSONL para o banco de dados.
Daemon em Segundo Plano
bd daemon --start # Sincronização automática em segundo plano
bd daemon --status # Verificar saúde do daemon
bd daemon --stop # Parar sincronização automática
O daemon monitora mudanças no banco de dados e exporta automaticamente para JSONL.
Comandos de Busca e Localização
Encontrar Trabalho Pronto
bd ready
Mostra tarefas sem bloqueadores abertos.
Listar Todas as Tarefas
bd list --status open # Apenas tarefas abertas
bd list --priority 0 # Apenas P0 (crítico)
bd list --type bug # Apenas bugs
bd list --label backend # Apenas rotuladas como "backend"
bd list --assignee alice # Apenas atribuídas a alice
Mostrar Detalhes da Tarefa
bd show <id-da-tarefa>
Detalhes completos: descrição, dependências, trilha de auditoria, metadados.
Buscar por Texto
bd search "autenticação" # Buscar títulos e descrições
bd search login --status open # Combinar com filtros
Encontrar Trabalho Bloqueado
bd blocked
Mostra todas as tarefas que têm bloqueadores abertos impedindo que sejam trabalhadas.
Estatísticas do Projeto
bd stats
Mostra:
- Total de problemas por status (open, in_progress, blocked, closed)
- Problemas por prioridade (P0-P4)
- Problemas por tipo (bug, feature, task, epic, chore)
- Taxa de conclusão
Referência Completa de Comandos
| Comando | Quando Usar | Exemplo |
|---|---|---|
| COMANDOS DE BUSCA | ||
bd ready | Encontrar tarefas desbloqueadas | Usuário pergunta "no que devo trabalhar?" |
bd list | Visualizar todas as tarefas (com filtros) | "Mostre-me todos os bugs abertos" |
bd show <id> | Obter detalhes da tarefa | "Mostre-me a tarefa bd-42" |
bd search <consulta> | Busca textual entre tarefas | "Encontrar tarefas sobre auth" |
bd blocked | Encontrar trabalho travado | "O que está nos bloqueando?" |
bd stats | Métricas do projeto | "Quantas tarefas estão abertas?" |
| COMANDOS DE CRIAÇÃO | ||
bd create | Rastrear novo trabalho | "Criar uma tarefa para este bug" |
bd template create | Usar modelo de issue | "Criar tarefa a partir do modelo de bug" |
bd init | Inicializar beads | "Configurar beads neste repositório" (apenas humanos) |
| COMANDOS DE ATUALIZAÇÃO | ||
bd update <id> | Alterar status/prioridade/anotações | "Marcar como em andamento" |
bd dep add | Vincular dependências | "Isso bloqueia aquilo" |
bd label add | Etiquetar com rótulos | "Rotular isso como backend" |
bd comments add | Adicionar comentário | "Adicionar comentário à tarefa" |
bd reopen <id> | Reabrir tarefa fechada | "Reabrir bd-42, regressão encontrada" |
bd rename-prefix | Renomear prefixo da issue | "Alterar prefixo de bd- para proj-" |
bd epic status | Verificar progresso do épico | "Mostrar % de conclusão do épico" |
| COMANDOS DE CONCLUSÃO | ||
bd close <id> | Marcar tarefa como concluída | "Fechar esta tarefa, está concluída" |
bd epic close-eligible | Fechar épicos completos automaticamente | "Fechar épicos onde todos os filhos estão concluídos" |
| COMANDOS DE SINCRONIZAÇÃO | ||
bd sync | Sincronização git (tudo-em-um) | "Sincronizar tarefas com git" |
bd export | Exportar para JSONL | "Fazer backup de todas as tarefas" |
bd import | Importar de JSONL | "Restaurar a partir de backup" |
bd daemon | Gerenciador de sincronização em segundo plano | "Iniciar daemon de sincronização automática" |
| COMANDOS DE LIMPEZA | ||
bd delete <id> | Excluir problemas | "Excluir tarefa de teste" (requer --force) |
bd compact | Arquivar tarefas fechadas antigas | "Comprimir banco de dados" |
| COMANDOS DE RELATÓRIO | ||
bd stats | Métricas do projeto | "Mostrar saúde do projeto" |
bd audit record | Registrar interações | "Registrar esta chamada LLM" |
bd workflow | Mostrar guia de fluxo de trabalho | "Como usar beads?" |
| COMANDOS AVANÇADOS | ||
bd prime | Atualizar contexto do agente | "Carregar regras de fluxo de trabalho do bd" |
bd quickstart | Tutorial interativo | "Ensinar-me o básico de beads" |
bd daemons | Gerenciamento de daemon multi-repo | "Gerenciar todos os daemons beads" |
bd version | Verificação de versão | "Verificar versão do bd" |
bd restore <id> | Restaurar issue compactada | "Obter histórico completo do git" |
Saída
Esta habilidade produz:
IDs de Tarefa: Formato <prefixo>-<hash> (ex.: claude-code-plugins-abc, myproject-xyz)
Resumos de Status:
5 open, 2 in_progress, 1 blocked, 47 closed
Grafos de Dependência (árvore visual):
myproject-abc: Implantar em produção [P0] [blocked]
Bloqueado por:
↳ myproject-def: Executar testes de integração [P1] [in_progress]
↳ myproject-ghi: Corrigir testes com falha [P1] [open]
Trilhas de Auditoria (histórico completo):
2025-12-22 10:00 - Criado por alice (P2, task)
2025-12-22 10:15 - Prioridade alterada: P2 → P0
2025-12-22 10:30 - Status alterado: open → in_progress
2025-12-22 11:00 - Anotações adicionadas: "Implementado JWT auth..."
2025-12-22 14:00 - Status alterado: in_progress → blocked
2025-12-22 14:01 - Anotações adicionadas: "Bloqueado: Endpoint da API retorna 503"
Tratamento de Erros
Falhas Comuns
1. bd: comando não encontrado
Causa: CLI bd não instalado ou não no PATH Solução: Instalar de https://github.com/steveyegge/beads
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Ou via npm
npm install -g @beads/bd
# Ou via Homebrew
brew install steveyegge/beads/bd
2. Nenhum banco de dados .beads encontrado
Causa: beads não inicializado neste repositório
Solução: Execute bd init (humanos fazem isso uma vez, não agentes)
bd init # Cria o diretório .beads/
3. Tarefa não encontrada: <id>
Causa: ID de tarefa inválido ou tarefa não existe
Solução: Use bd list para ver todas as tarefas e verificar o formato do ID
bd list # Ver todas as tarefas
bd search <titulo-parcial> # Encontrar tarefa pelo título
4. Dependência circular detectada
Causa: Tentativa de criar um ciclo de dependência (A bloqueia B, B bloqueia A) Solução: O bd previne dependências circulares automaticamente. Reestruture o grafo de dependências.
bd dep list <id> # Visualizar dependências atuais
5. Conflitos de merge git em .beads/issues.jsonl
Causa: Vários usuários modificaram a mesma issue Solução: O bd sync lida com conflitos JSONL automaticamente. Se for necessária intervenção manual:
# Visualizar conflito
git status
# bd fornece ferramentas de resolução de conflitos
bd sync --merge # Tentar resolução automática
6. Banco de dados está bloqueado
Causa: Daemon ou outro processo possui bloqueio exclusivo Solução: Reiniciar daemon ou aguardar a liberação do bloqueio
bd daemon --stop
bd daemon --start
7. Falhas de sincronização
Causa: Problemas de rede, falhas de autenticação ou configuração git Solução: Verificar acesso remoto e credenciais git
git fetch # Testar conectividade
git status # Verificar estado do repositório
Exemplos
…
[truncado para tradução]