Beads - Memoria Persistente de Tareas para Agentes de IA
Gestor de incidencias basado en grafos que sobrevive a la compactación de la conversación. Proporciona memoria persistente para trabajo en múltiples sesiones con dependencias complejas.
Resumen
bd (beads) reemplaza las listas de tareas Markdown con un grafo consciente de dependencias almacenado en Git. A diferencia de TodoWrite (ámbito de sesión), bd persiste a través de compactaciones y rastrea dependencias complejas.
Distinción Clave:
- bd: Trabajo en múltiples sesiones, dependencias, sobrevive a la compactación, respaldado por Git
- TodoWrite: Tareas de una sola sesión, ejecución lineal, ámbito de conversación
Capacidades Principales:
- 📊 Grafos de Dependencias: Rastrea qué bloquea qué (bloquea, padre-hijo, descubierto-de, relacionado)
- 💾 Supervivencia a la Compactación: Las tareas persisten cuando se compacta el historial de la conversación
- 🐙 Integración con Git: Incidencias versionadas en
.beads/issues.jsonl, sincronizar conbd sync - 🔍 Descubrimiento Inteligente: Encuentra automáticamente trabajo listo (
bd ready), trabajo bloqueado (bd blocked) - 📝 Pistas de Auditoría: Historial completo de cambios de estado, notas y decisiones
- 🏷️ Metadatos Ricos: Prioridad (P0-P4), tipos (bug/feature/task/epic), etiquetas, asignados
Cuándo Usar bd vs TodoWrite:
- ❓ "¿Necesitaré este contexto en 2 semanas?" → SÍ = bd
- ❓ "¿Podría compactarse el historial de la conversación?" → SÍ = bd
- ❓ "¿Tiene bloqueadores/dependencias?" → SÍ = bd
- ❓ "¿Es trabajo difuso/exploratorio?" → SÍ = bd
- ❓ "¿Se terminará en esta sesión?" → SÍ = TodoWrite
- ❓ "¿Es solo una lista de tareas para mí ahora mismo?" → SÍ = TodoWrite
Regla de Decisión: Si retomar el trabajo en 2 semanas sería difícil sin bd, usa bd.
Prerrequisitos
Requeridos:
- CLI de bd: Versión 0.34.0 o posterior instalada y en PATH
- Repositorio Git: El directorio actual debe ser un repositorio Git
- Inicialización:
bd initdebe ejecutarse una vez (los humanos lo hacen, no los agentes)
Verificar Instalación:
bd --version # Debería devolver 0.34.0 o posterior
Configuración Inicial (los humanos ejecutan una vez):
cd /path/to/your/repo
bd init # Crea el directorio .beads/ con la base de datos
Opcional:
- Variable de entorno BEADS_DIR para ubicación alternativa de la base de datos
- Daemon para sincronización en segundo plano:
bd daemon --start
Instrucciones
Protocolo de Inicio de Sesión
Cada sesión, comienza aquí:
Paso 1: Verificar Trabajo Listo
bd ready
Muestra tareas sin bloqueadores abiertos, ordenadas por prioridad (P0 → P4).
Lo que muestra:
- ID de tarea (ej.,
myproject-abc) - Título
- Nivel de prioridad
- Tipo de incidencia (bug, feature, task, epic)
Ejemplo de salida:
claude-code-plugins-abc [P1] [task] open
Implementar autenticación de usuario
claude-code-plugins-xyz [P0] [epic] in_progress
Refactorizar capa de base de datos
Paso 2: Elegir la Tarea de Mayor Prioridad
Elige la tarea de mayor prioridad (P0 > P1 > P2 > P3 > P4) que esté lista.
Paso 3: Obtener Contexto Completo
bd show <task-id>
Muestra:
- Descripción completa de la tarea
- Grafo de dependencias (qué bloquea esto, qué está bloqueado por esto)
- Pista de auditoría (todos los cambios de estado, notas)
- Metadatos (creado, actualizado, asignado, etiquetas)
Paso 4: Empezar a Trabajar
bd update <task-id> --status in_progress
Marca la tarea como que se está trabajando activamente.
Paso 5: Añadir Notas Mientras Trabajas
bd update <task-id> --notes "Completado: X. En progreso: Y. Bloqueado por: Z"
Crítico para la supervivencia a la compactación: Escribe notas como si explicaras a un agente futuro con cero contexto de conversación.
Formato de Nota (mejor práctica):
COMPLETADO: Entregables específicos (ej., "implementado endpoint de actualización JWT + límite de velocidad")
EN PROGRESO: Estado actual + próximo paso inmediato
BLOQUEADORES: Qué está impidiendo el progreso
DECISIONES CLAVE: Contexto importante o guía del usuario
Flujo de Trabajo de Creación de Tareas
Cuándo Crear Tareas
Crea tareas bd cuando:
- El usuario menciona rastrear trabajo entre sesiones
- El usuario dice "deberíamos arreglar/construir/añadir X"
- El trabajo tiene dependencias o bloqueadores
- Trabajo exploratorio/de investigación con límites difusos
Creación Básica de Tareas
bd create "Título de la tarea" -p 1 --type task
Argumentos:
- Título: Descripción breve (requerido)
- Prioridad: 0-4 donde 0=crítico, 1=alta, 2=media, 3=baja, 4=backlog (por defecto: 2)
- Tipo: bug, feature, task, epic, chore (por defecto: task)
Ejemplo:
bd create "Arreglar fallo de autenticación" -p 0 --type bug
Crear con Descripción
bd create "Implementar OAuth" -p 1 --description "Añadir soporte OAuth2 para Google, GitHub, Microsoft. Usar la librería passport.js."
Épica con Hijos
# Crear épica padre
bd create "Épica: Implementación de OAuth" -p 0 --type epic
# Devuelve: myproject-abc
# Crear tareas hijas
bd create "Investigar proveedores OAuth" -p 1 --parent myproject-abc
bd create "Implementar endpoints de autenticación" -p 1 --parent myproject-abc
bd create "Añadir interfaz de inicio de sesión frontend" -p 2 --parent myproject-abc
Flujo de Trabajo de Actualización y Progreso
Cambiar Estado
bd update <task-id> --status <nuevo-estado>
Valores de Estado:
open- No iniciadoin_progress- Trabajando activamenteblocked- Atascado, esperando algoclosed- Completado
Ejemplo:
bd update myproject-abc --status blocked
Añadir Notas de Progreso
bd update <task-id> --notes "Actualización de progreso aquí"
Añade al campo de notas existente (no lo reemplaza).
Cambiar Prioridad
bd update <task-id> -p 0 # Escalar a crítico
Añadir Etiquetas
bd label add <task-id> backend
bd label add <task-id> security
Las etiquetas proporcionan categorización transversal más allá del estado/tipo.
Gestión de Dependencias
Añadir Dependencias
bd dep add <id-hijo> <id-padre>
Significado: <id-padre> bloquea <id-hijo> (el padre debe completarse primero).
Tipos de Dependencia:
- blocks: El padre debe cerrarse antes de que el hijo esté listo
- parent-child: Relación jerárquica (épicas y subtareas)
- discovered-from: La tarea A llevó a descubrir la tarea B
- related: Las tareas están relacionadas pero no se bloquean
Ejemplo:
# Despliegue bloqueado por que las pruebas pasen
bd dep add deploy-task test-task # test-task bloquea deploy-task
Ver Dependencias
bd dep list <task-id>
Muestra:
- Lo que esta tarea bloquea (dependientes)
- Lo que bloquea esta tarea (bloqueadores)
Prevención de Dependencias Circulares
bd previene automáticamente las dependencias circulares. Si intentas crear un ciclo, el comando falla.
Flujo de Trabajo de Finalización
Cerrar una Tarea
bd close <task-id> --reason "Resumen de finalización"
Mejor Práctica: Incluye siempre una razón describiendo lo que se logró.
Ejemplo:
bd close myproject-abc --reason "Completado: Endpoints OAuth implementados con proveedores Google, GitHub. Pruebas pasando."
Verificar Trabajo Recién Desbloqueado
Después de cerrar una tarea, ejecuta:
bd ready
Cerrar una tarea puede desbloquear tareas dependientes, haciéndolas recién listas.
Cerrar Épicas Cuando los Hijos se Completan
bd epic close-eligible
Cierra automáticamente épicas donde todas las tareas hijas están cerradas.
Flujo de Trabajo de Sincronización con Git
Sincronización Todo-en-Uno
bd sync
Realiza:
- Exportar base de datos a
.beads/issues.jsonl - Confirmar cambios en Git
- Obtener del remoto (fusionar si es necesario)
- Importar el JSONL actualizado de vuelta a la base de datos
- Enviar confirmaciones locales al remoto
Usar cuando: Fin de sesión, antes de entregar a un compañero, después de un progreso importante.
Solo Exportar
bd export -o backup.jsonl
Crea una copia de seguridad JSONL sin operaciones de Git.
Solo Importar
bd import -i backup.jsonl
Importa un archivo JSONL a la base de datos.
Daemon en Segundo Plano
bd daemon --start # Auto-sincronización en segundo plano
bd daemon --status # Verificar salud del daemon
bd daemon --stop # Detener auto-sincronización
El daemon monitorea cambios en la base de datos y exporta automáticamente a JSONL.
Comandos de Búsqueda y Encuentro
Encontrar Trabajo Listo
bd ready
Muestra tareas sin bloqueadores abiertos.
Listar Todas las Tareas
bd list --status open # Solo tareas abiertas
bd list --priority 0 # Solo P0 (crítico)
bd list --type bug # Solo bugs
bd list --label backend # Solo etiquetadas "backend"
bd list --assignee alice # Solo asignadas a alice
Mostrar Detalles de la Tarea
bd show <task-id>
Detalles completos: descripción, dependencias, pista de auditoría, metadatos.
Buscar por Texto
bd search "authentication" # Buscar títulos y descripciones
bd search login --status open # Combinar con filtros
Encontrar Trabajo Bloqueado
bd blocked
Muestra todas las tareas que tienen bloqueadores abiertos impidiendo que se trabajen.
Estadísticas del Proyecto
bd stats
Muestra:
- Total de incidencias por estado (open, in_progress, blocked, closed)
- Incidencias por prioridad (P0-P4)
- Incidencias por tipo (bug, feature, task, epic, chore)
- Tasa de finalización
Referencia Completa de Comandos
| Comando | Cuándo Usar | Ejemplo |
|---|---|---|
| COMANDOS DE BÚSQUEDA | ||
bd ready | Encontrar tareas no bloqueadas | El usuario pregunta "¿en qué debería trabajar?" |
bd list | Ver todas las tareas (con filtros) | "Muéstrame todos los bugs abiertos" |
bd show <id> | Obtener detalles de la tarea | "Muéstrame la tarea bd-42" |
bd search <consulta> | Buscar texto en tareas | "Encontrar tareas sobre auth" |
bd blocked | Encontrar trabajo atascado | "¿Qué nos está bloqueando?" |
bd stats | Métricas del proyecto | "¿Cuántas tareas están abiertas?" |
| COMANDOS DE CREACIÓN | ||
bd create | Rastrear nuevo trabajo | "Crear una tarea para este bug" |
bd template create | Usar plantilla de incidencia | "Crear tarea desde plantilla de bug" |
bd init | Inicializar beads | "Configurar beads en este repo" (solo humanos) |
| COMANDOS DE ACTUALIZACIÓN | ||
bd update <id> | Cambiar estado/prioridad/notas | "Marcar como en progreso" |
bd dep add | Vincular dependencias | "Esto bloquea aquello" |
bd label add | Etiquetar con etiquetas | "Etiquetar esto como backend" |
bd comments add | Añadir comentario | "Añadir comentario a la tarea" |
bd reopen <id> | Reabrir tarea cerrada | "Reabrir bd-42, encontrada regresión" |
bd rename-prefix | Renombrar prefijo de incidencia | "Cambiar prefijo de bd- a proj-" |
bd epic status | Verificar progreso de épica | "Mostrar % de finalización de épica" |
| COMANDOS DE FINALIZACIÓN | ||
bd close <id> | Marcar tarea como hecha | "Cerrar esta tarea, está hecha" |
bd epic close-eligible | Auto-cerrar épicas completas | "Cerrar épicas donde todos los hijos están hechos" |
| COMANDOS DE SINCRONIZACIÓN | ||
bd sync | Sincronizar con Git (todo-en-uno) | "Sincronizar tareas a Git" |
bd export | Exportar a JSONL | "Respaldar todas las tareas" |
bd import | Importar desde JSONL | "Restaurar desde respaldo" |
bd daemon | Gestor de sincronización en segundo plano | "Iniciar daemon de auto-sincronización" |
| COMANDOS DE LIMPIEZA | ||
bd delete <id> | Eliminar incidencias | "Eliminar tarea de prueba" (requiere --force) |
bd compact | Archivar tareas cerradas antiguas | "Comprimir base de datos" |
| COMANDOS DE INFORMES | ||
bd stats | Métricas del proyecto | "Mostrar salud del proyecto" |
bd audit record | Registrar interacciones | "Registrar esta llamada LLM" |
bd workflow | Mostrar guía de flujo de trabajo | "¿Cómo uso beads?" |
| COMANDOS AVANZADOS | ||
bd prime | Refrescar contexto de IA | "Cargar reglas de flujo de trabajo de bd" |
bd quickstart | Tutorial interactivo | "Enséñame los conceptos básicos de beads" |
bd daemons | Gestión de daemons multi-repo | "Gestionar todos los daemons de beads" |
bd version | Verificar versión | "Verificar versión de bd" |
bd restore <id> | Restaurar incidencia compactada | "Obtener historial completo desde Git" |
Salida
Esta habilidad produce:
IDs de Tarea: Formato <prefijo>-<hash> (ej., claude-code-plugins-abc, myproject-xyz)
Resúmenes de Estado:
5 open, 2 in_progress, 1 blocked, 47 closed
Grafos de Dependencias (árbol visual):
myproject-abc: Desplegar a producción [P0] [blocked]
Bloqueado por:
↳ myproject-def: Ejecutar pruebas de integración [P1] [in_progress]
↳ myproject-ghi: Arreglar pruebas fallidas [P1] [open]
Pistas de Auditoría (historial completo):
2025-12-22 10:00 - Creado por alice (P2, task)
2025-12-22 10:15 - Prioridad cambiada: P2 → P0
2025-12-22 10:30 - Estado cambiado: open → in_progress
2025-12-22 11:00 - Notas añadidas: "Implementada autenticación JWT..."
2025-12-22 14:00 - Estado cambiado: in_progress → blocked
2025-12-22 14:01 - Notas añadidas: "Bloqueado: El endpoint de la API devuelve 503"
Manejo de Errores
Fallos Comunes
1. bd: command not found
Causa: CLI de bd no instalado o no en PATH Solución: Instalar desde https://github.com/steveyegge/beads
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# O via npm
npm install -g @beads/bd
# O via Homebrew
brew install steveyegge/beads/bd
2. No .beads database found
Causa: beads no inicializado en este repositorio
Solución: Ejecutar bd init (los humanos lo hacen una vez, no los agentes)
bd init # Crea el directorio .beads/
3. Task not found: <id>
Causa: ID de tarea inválido o la tarea no existe
Solución: Usar bd list para ver todas las tareas y verificar el formato del ID
bd list # Ver todas las tareas
bd search <título-parcial> # Encontrar tarea por título
4. Circular dependency detected
Causa: Intento de crear un ciclo de dependencia (A bloquea B, B bloquea A) Solución: bd previene automáticamente dependencias circulares. Reestructurar el grafo de dependencias.
bd dep list <id> # Ver dependencias actuales
5. Conflictos de fusión Git en .beards/issues.jsonl
Causa: Múltiples usuarios modificaron la misma incidencia Solución: bd sync maneja conflictos JSONL automáticamente. Si se necesita intervención manual:
# Ver conflicto
git status
# bd proporciona herramientas de resolución de conflictos
bd sync --merge # Intentar resolución automática
6. Database is locked
Causa: El daemon u otro proceso tiene un bloqueo exclusivo Solución: Reiniciar el daemon o esperar a que se libere el bloqueo
bd daemon --stop
bd daemon --start
7. Fallos de sincronización
Causa: Problemas de red, fallos de autenticación o configuración de Git Solución: Verificar acceso remoto a Git y credenciales
git fetch # Probar conectividad
git status # Verificar estado del repositorio
Ejemplos
…
[truncado para traducción]