Configuração de agentes

Pré-requisitos

Antes de configurar agentes, você precisa de:

• O CLI bd instalado e no PATH (Primeiros Passos)
• Pelo menos um workspace inicializado (bd init no diretório do seu projeto)
• O Beadbox rodando e conectado a esse workspace

Identidade do agente

Cada agente precisa de um arquivo CLAUDE.md (ou prompt de sistema equivalente) que defina:

• O que o agente é responsável (implementação, QA, operações)
• O que o agente não é responsável (impede que agentes desviem para outros papéis)
• Como se comunicar (comentar em beads, reportar ao coordenador)

Aqui está uma identidade mínima para um agente de engenharia:

## Identity
Engineer for MyProject. You implement features, fix bugs,
and write tests. You own implementation quality.

## Boundary with QA
QA validates your work independently. You provide QA with
executable verification steps. If your DONE comment doesn't
let QA verify without reading source code, it's incomplete.

A seção de limites impede que o agente faça o trabalho do QA. Sem limites explícitos, os agentes se auto-validam e pulam a revisão independente.

Comandos essenciais

Estes são os comandos bd que seus agentes usam com mais frequência:

bd create --title="Fix login bug" --type=bug --priority=2

bd show BEAD-ID

bd update BEAD-ID --claim --actor agent-name
bd update BEAD-ID --status in_progress

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

bd list --status=open --assignee=agent-name

bd close BEAD-ID

Todos os comandos aceitam a flag --db para apontar para um banco de dados de workspace específico, útil quando agentes trabalham em múltiplos projetos.

O comando bd prime

A forma mais rápida de ensinar a um novo agente o CLI bd:

bd prime

Isso gera um bloco de contexto projetado para assistentes de código IA. Cobre o conjunto completo de comandos, formatos de saída e fluxos de trabalho comuns. Cole-o no prompt de sistema ou na janela de contexto do seu agente.

Execute bd prime de dentro do diretório do seu workspace para incluir contexto específico do workspace.

Fluxo de trabalho do agente

Um fluxo de trabalho típico do agente para um único bead:

1. Assumir o bead
2. Comentar um plano antes de programar
3. Implementar a mudança
4. Rodar os testes
5. Comentar conclusão com passos de verificação
6. Fazer push e atualizar o status para ready_for_qa

# Full workflow example
bd update proj-a1b2 --claim --actor eng1
bd comments add proj-a1b2 --author eng1 "PLAN: 1. Fix auth check 2. Add test"

# ... implement and test ...

bd comments add proj-a1b2 --author eng1 "DONE: Fixed auth. Commit: abc123"
git push
bd update proj-a1b2 --status ready_for_qa

O comentário DONE deve incluir passos de verificação que permitam a outro agente (ou a uma pessoa) confirmar o trabalho sem ler o código-fonte.

Feedback em tempo real

Quando um agente executa um comando bd, o Beadbox detecta a mudança no banco de dados e atualiza a interface em até dois segundos. Sem necessidade de atualização manual.

Isso significa que você pode acompanhar seus agentes trabalhando em tempo real: ver beads passando de open para in_progress, observar planos aparecendo como comentários e detectar bloqueios assim que surgem.

Para configurações multi-agente, o Dashboard de Atividade mostra qual agente está trabalhando em quê, onde o trabalho está se acumulando no pipeline e o que acabou de acontecer em toda a frota.