Configuración de agentes

Prerrequisitos

Antes de configurar agentes, necesitas:

• El CLI bd instalado y en el PATH (Primeros pasos)
• Al menos un workspace inicializado (bd init en tu directorio de proyecto)
• Beadbox ejecutándose y conectado a ese workspace

Identidad del agente

Cada agente necesita un archivo CLAUDE.md (o prompt de sistema equivalente) que defina:

• Qué es responsabilidad del agente (implementación, QA, operaciones)
• Qué no es responsabilidad del agente (evita que los agentes se desvíen a otros roles)
• Cómo comunicarse (comentar en beads, reportar al coordinador)

Aquí tienes una identidad mínima para un agente de ingeniería:

## 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.

La sección de límites evita que el agente haga el trabajo de QA. Sin límites explícitos, los agentes se auto-validan y omiten la revisión independiente.

Comandos esenciales

Estos son los comandos de bd que tus agentes usan con más frecuencia:

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 los comandos aceptan un flag --db para apuntar a una base de datos de workspace específica, útil cuando los agentes trabajan en múltiples proyectos.

El comando bd prime

La forma más rápida de enseñar a un nuevo agente el CLI bd:

bd prime

Esto genera un bloque de contexto diseñado para asistentes de código IA. Cubre el conjunto completo de comandos, formatos de salida y flujos de trabajo comunes. Pégalo en el prompt de sistema o ventana de contexto de tu agente.

Ejecuta bd prime desde dentro de tu directorio de workspace para incluir contexto específico del workspace.

Flujo de trabajo del agente

Un flujo de trabajo típico del agente para un solo bead:

1. Reclamar el bead
2. Comentar un plan antes de programar
3. Implementar el cambio
4. Ejecutar tests
5. Comentar completado con pasos de verificación
6. Hacer push y actualizar el estado a 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

El comentario DONE debe incluir pasos de verificación que permitan a otro agente (o a un humano) confirmar el trabajo sin leer el código fuente.

Retroalimentación en tiempo real

Cuando un agente ejecuta un comando bd, Beadbox detecta el cambio en la base de datos y actualiza la interfaz en menos de dos segundos. Sin necesidad de recargar manualmente.

Esto significa que puedes observar a tus agentes trabajar en tiempo real: ver beads pasar de open a in_progress, ver planes aparecer como comentarios y detectar bloqueos en cuanto surgen.

Para configuraciones multi-agente, el Dashboard de Actividad muestra qué agente está trabajando en qué, dónde se acumula el trabajo en el pipeline y qué acaba de pasar en toda la flota.