De la especificación a la entrega en paralelo: Spec Kit, Cursor, Beads y Claude Code en una funcionalidad real

Mi artículo anterior sobre Claude Code, Cursor y Beads respondía una pregunta importante: ¿qué herramienta es mejor para la planificación, la ejecución y la persistencia?

La pregunta que quedó pendiente es la que la mayoría de los ingenieros realmente necesita responder: ¿cómo se usan juntas en una funcionalidad lo suficientemente grande como para involucrar decisiones de arquitectura, criterios de aceptación, trabajo en segundo plano, aislamiento de ramas y varias personas?

Este artículo complementa al anterior.

El April 2, 2026, volví a comprobar las capacidades básicas de este flujo de trabajo contra la documentación actual de Spec Kit, el changelog y fragmentos de la documentación de Cursor, la documentación de Claude Code de Anthropic, el README de Beads y la documentación oficial de Git worktree. Una aclaración importante desde el principio: el flujo completo que presento a continuación es mi propia síntesis. Las capacidades individuales están respaldadas por las fuentes. La orquestación es la parte práctica que todavía nos toca diseñar como ingenieros.

En resumen

• El artículo comparativo anterior acertó al señalar que Spec Kit, Cursor, Beads y Claude Code resuelven distintas capas del flujo de trabajo.
• La pieza que faltaba es un modelo de trabajo con la especificación primero: requisitos y criterios de aceptación primero, un grafo de tareas persistente después y, por último, implementación aislada.
• Un buen flujo predeterminado es:
  1. Spec Kit en Cursor para definir la constitución, la especificación, las aclaraciones, el plan y generar las tareas
  2. PR en borrador para los documentos de planificación para que el equipo acuerde el alcance antes de empezar a programar
  3. Beads para convertir el plan aprobado en tareas persistentes con dependencias
  4. Ramas y worktrees de Git para aislar los flujos de implementación en paralelo
  5. Claude Code en la web para tareas de larga duración o bien delimitadas que puedan ejecutarse de forma asíncrona
• Si participan varias personas y agentes, la regla más segura es sencilla: un flujo de trabajo, una rama, un worktree y una persona responsable a la vez.

Qué aprenderás aquí

• Cómo revisar el artículo comparativo anterior y convertirlo en un complemento más práctico
• Cómo usar el flujo de Spec Kit como columna vertebral de la planificación en Cursor
• Cómo convertir los criterios de aceptación y los requisitos en un grafo de tareas de Beads
• Cómo dividir una funcionalidad compleja entre ramas, worktrees, agentes de IA y compañeros de equipo
• Dónde encaja mejor Claude Code en la web dentro de un ciclo de ingeniería real
• Qué evitar cuando varios agentes y desarrolladores modifican el mismo sistema

En qué acertó el artículo anterior

El artículo anterior sigue siendo válido en tres aspectos importantes:

• Claude Code destaca cuando necesitas planificación explícita, acceso a la terminal y ejecución orientada a ramas.
• Cursor destaca cuando necesitas un espacio de planificación integrado en el IDE y una experiencia con agentes asíncronos.
• Beads destaca cuando necesitas una memoria de tareas persistente que sobreviva a los reinicios de contexto y a los traspasos de trabajo.

La parte que ese artículo mantuvo deliberadamente a un nivel más general es precisamente con la que más equipos tienen dificultades en la práctica:

• cuáles deberían ser los artefactos de planificación
• cuándo cerrar la especificación y abrir ramas de implementación
• cómo evitar conflictos entre tareas de personas y agentes
• cuándo trabajar localmente y cuándo ejecutar en la nube

Así que, en lugar de hacer otra comparación, recorramos una funcionalidad realista de principio a fin.

El caso de uso real

Supongamos que estamos construyendo una plataforma SaaS B2B y necesitamos agregar:

• SAML SSO para tenants empresariales
• Aprovisionamiento de usuarios justo a tiempo
• Sincronización de directorios con SCIM
• Eventos de registro de auditoría para acciones administrativas y de identidad
• Interfaz de administración para configurar proveedores de identidad y monitorear la sincronización

Es un buen ejemplo porque atraviesa los límites de producto, backend, worker, seguridad y plataforma. También impone una secuencia de trabajo real:

• primero hay que acordar el modelo de dominio y los límites de autenticación
• la API y los flujos de callback necesitan criterios de aceptación sólidos
• el trabajo del worker puede hacerse en paralelo, pero solo cuando los contratos sean estables
• el registro de auditoría afecta casi todos los flujos

Este es el modelo mental:

feature request
  -> Spec Kit + Cursor
  -> acceptance criteria + requirements + technical plan
  -> draft PR for plan review
  -> Beads task graph
  -> isolated branches + git worktrees
  -> humans + Cursor agents + Claude Code web sessions
  -> PRs + review + merge

Esa es la tesis central de este artículo: los artefactos de planificación no bastan por sí solos. Necesitas un traspaso claro de la planificación a la ejecución.

Por qué este flujo de trabajo es viable

Este flujo no es magia. Es simplemente una combinación ordenada de capacidades que ya existen.

Spec Kit te da la secuencia de planificación

La guía de inicio rápido de Spec Kit describe un flujo estructurado: definir una constitución, crear la especificación, aclarar las ambigüedades, crear un plan técnico y luego dividir el trabajo en tareas. También señala que la funcionalidad activa se infiere de la rama actual de Git, un detalle sutil pero muy útil para los flujos de ingeniería.

Por eso Spec Kit es una buena columna vertebral para:

• reglas del proyecto
• propósito de la funcionalidad
• ciclos de aclaración
• generación del plan
• desglose de tareas

Cursor te da un espacio sólido para planificar

La documentación de planificación de Cursor describe la planificación en torno a tareas pendientes y trabajo en cola, y el changelog actual de Cursor 3 indica explícitamente que la nueva Agents Window puede ejecutar muchos agentes en paralelo entre repositorios y entornos, incluidos worktrees, la nube y SSH remoto. Cursor también agregó un comando /worktree explícito e incluye planes en los chats compartidos.

Eso hace de Cursor un buen lugar para resolver la parte intermedia más compleja:

• explorar la base de código
• debatir la arquitectura en contexto
• mantener visibles las tareas pendientes
• compartir el plan en evolución con el equipo

Beads te da memoria persistente para la ejecución

Beads se describe como un sistema distribuido de seguimiento de incidencias basado en grafos para agentes de IA, con memoria estructurada persistente, tareas con dependencias, IDs basados en hashes, una cola bd ready y asignación explícita de tareas. Esa es la capa que falta después de aprobar el plan.

Claude Code en la web te permite ejecutar de forma asíncrona

La documentación actual de Anthropic indica que Claude Code está disponible en la terminal, el IDE, la aplicación de escritorio y el navegador. El producto web puede ejecutar tareas de forma asíncrona en infraestructura de la nube, clonar el repositorio, ejecutar scripts de configuración y tareas, mostrar diffs, crear PRs, corregir automáticamente problemas relacionados con los PRs y ejecutar varias tareas remotas en paralelo. Anthropic también documenta el patrón de planificar localmente y ejecutar de forma remota con claude --permission-mode plan seguido de claude --remote.

Git worktree te da aislamiento seguro

La documentación oficial de Git describe git worktree como una forma de administrar varios árboles de trabajo asociados al mismo repositorio. Esto significa que puedes tener varias ramas activas a la vez sin el caos de guardar cambios en el stash y cambiar constantemente de rama.

Esa es la medida de seguridad que falta cuando tienes varios flujos en paralelo.

Paso 1: comienza con una rama de planificación

Antes de que alguien toque código de producción, crea una rama exclusiva para los artefactos de planificación.

git switch -c 042-enterprise-sso-spec

Me gusta usar un prefijo numérico porque se relaciona claramente con:

• una carpeta de la funcionalidad
• una épica de Beads
• un PR en borrador
• una convención de nombres para las ramas

Si usas el flujo de Spec Kit que tiene en cuenta la rama, una rama como 042-enterprise-sso-spec le da a la funcionalidad una identidad estable desde el principio.

En este punto, la rama debería contener solo artefactos de planificación como estos:

specs/042-enterprise-sso/
  constitution.md
  spec.md
  plan.md
  tasks.md

No conviene mezclar la implementación en esta rama. El objetivo es que el plan se pueda revisar por sí solo.

Paso 2: usa Spec Kit en Cursor para definir el trabajo

Aquí es donde Cursor se convierte en el centro de planificación.

Si ya usas Cursor como IDE principal, mantén allí toda la conversación de planificación y ejecuta la secuencia de Spec Kit en orden.

1. Constitución

Comienza con las reglas del proyecto y los aspectos no negociables:

/speckit.constitution
This feature is security-first and audit-first.
All identity changes must be attributable to a tenant and actor.
All SSO and SCIM flows must emit structured audit events.
Database changes must be backward compatible for one deploy cycle.
We prefer incremental delivery over a single big-bang release.

Esto no es trabajo burocrático. Es lo que evita que los resultados posteriores de los agentes se reduzcan a «cualquier cosa que compile».

2. Especificación

Luego describe la funcionalidad en términos de negocio, no de detalles de implementación:

/speckit.specify
Build enterprise identity management for a B2B SaaS platform.
Tenant admins must be able to configure a SAML identity provider,
test login safely, enable just-in-time provisioning, and monitor SCIM
sync status. The system must maintain audit history for configuration
changes, login attempts, provisioning events, and directory sync actions.

3. Aclaración

Ahora usa el paso de aclaración para eliminar las ambigüedades.

Ejemplos:

/speckit.clarify
Focus on tenant isolation, rollback strategy, audit retention, and failure handling.

/speckit.clarify
Clarify whether SCIM deactivation removes access immediately or marks the user as suspended.
Clarify whether SSO can be enabled before SCIM is configured.
Clarify the safe rollout sequence for existing enterprise tenants.

4. Plan técnico

Solo cuando la especificación sea lo suficientemente precisa pasamos a definir la implementación:

/speckit.plan
The product is a TypeScript monorepo with Next.js web app, Node API,
Postgres, Redis-backed jobs, and OpenTelemetry. Keep the rollout incremental.
Add feature flags per tenant. Prefer additive schema changes. Use idempotent
worker behavior for SCIM sync.

5. Generación de tareas

Por último:

/speckit.tasks

Aquí es donde termina el artículo comparativo anterior y comienza el sistema de ejecución.

Paso 3: convierte el plan en criterios de aceptación antes de confiar en las tareas

Esta es la parte que muchos omiten. No pases directamente de las tareas generadas a escribir código.

La rama de planificación primero debe producir una capa clara de criterios de aceptación.

Para esta funcionalidad, querría que los documentos de planificación establecieran criterios como estos:

• Los administradores del tenant pueden configurar los metadatos de SAML sin habilitar SSO de inmediato.
• El inicio de sesión de prueba valida el intercambio de SAML sin bloquear la alternativa de autenticación por contraseña.
• Cuando SSO está habilitado para un tenant, solo los dominios aprobados pueden aprovisionar usuarios mediante JIT.
• La desactivación mediante SCIM suspende el acceso dentro del SLA acordado y emite un evento de auditoría.
• Las sincronizaciones fallidas de SCIM pueden reintentarse, son observables y aparecen en la interfaz de administración.
• Cada acción de administración de identidad genera un evento de auditoría estructurado con tenant, actor, acción y marca de tiempo.
• El despliegue puede habilitarse por tenant mediante una feature flag.
• Los tenants que usan autenticación local pueden migrar sin interrupciones.

Si el tasks.md generado no se relaciona claramente con estos criterios de aceptación, la lista de tareas es prematura.

Una regla útil es:

Los criterios de aceptación son el contrato. Las tareas son la propuesta de implementación.

La distinción importa porque las tareas suelen cambiar durante la entrega. El contrato no debería hacerlo.

Paso 4: abre un PR en borrador para el plan antes de abrir ramas de ejecución

Una vez que constitution.md, spec.md, plan.md y tasks.md estén en buen estado, abre un PR en borrador que contenga solo esos documentos.

Así tendrás un único punto de revisión claro para:

• alcance
• orden de despliegue
• criterios de aceptación
• secuencia de dependencias
• límites de responsabilidad

Aquí es donde el tech lead, el staff engineer o el PM responsable deberían cuestionar el plan antes de que comience la implementación.

Si omites este paso, Beads y los worktrees solo pondrán en marcha un plan débil más rápido.

Paso 5: lleva el trabajo aprobado a Beads

Ahora convertimos el plan aprobado en memoria persistente de tareas.

Inicializa Beads en el repositorio:

bd init

Luego crea la épica y los flujos principales usando el plan aprobado, no el historial original de prompts:

bd create "Enterprise SSO rollout" -p 0
bd create "Admin UI for IdP setup and sync monitoring" -p 1
bd create "SAML ACS endpoint and JIT provisioning" -p 0
bd create "SCIM sync worker with retry and reconciliation" -p 0
bd create "Audit events for SSO, SCIM, and admin changes" -p 0
bd create "Tenant rollout flags and migration path" -p 1

Después conecta las dependencias:

bd dep add <ui-task-id> <epic-id>
bd dep add <api-task-id> <epic-id>
bd dep add <worker-task-id> <api-task-id>
bd dep add <audit-task-id> <api-task-id>
bd dep add <rollout-task-id> <api-task-id>
bd ready

Lo importante no son los comandos exactos. Lo importante es la estructura:

• la rama de la especificación proporciona el alcance aprobado
• Beads convierte ese alcance en trabajo persistente, asignable y con dependencias
• bd ready se convierte en la cola operativa para personas y agentes

Este es el momento adecuado para agregar campos de responsabilidad, notas y enlaces a los documentos de planificación.

Paso 6: crea una rama y un worktree por cada flujo de entrega

Después de que se apruebe el PR de planificación, haz merge.

Luego crea las ramas de implementación a partir de main actualizado, no de copias desactualizadas de la rama de planificación.

git switch main
git pull --ff-only

git worktree add ../wt-042-sso-ui -b feat/042-sso-ui
git worktree add ../wt-042-sso-api -b feat/042-sso-api
git worktree add ../wt-042-sso-worker -b feat/042-sso-worker
git worktree add ../wt-042-sso-audit -b feat/042-sso-audit
git worktree add ../wt-042-sso-rollout -b feat/042-sso-rollout

Ahora cada flujo tiene:

• su propia rama
• su propio árbol de trabajo
• su propia persona responsable
• su propia tarea o subgrafo de Beads

Eso es lo que evita el caos de «todos están editando la autenticación y las migraciones al mismo tiempo».

Un mapa claro de responsabilidades

Si dos flujos necesitan los mismos archivos, todavía no son flujos separados. Vuelve atrás y redefine los límites.

Paso 7: usa Cursor para trabajo ambiguo y Claude Code en la web para trabajo delimitado

Esta es la división práctica que recomiendo.

Mantén el trabajo en Cursor cuando:

• la arquitectura todavía está cambiando
• necesitas explorar la base de código en profundidad
• una persona necesita guiar la solución mediante ciclos cortos
• la tarea afecta varias abstracciones compartidas a la vez

Usa Claude Code en la web cuando:

• la tarea está bien delimitada y ya está vinculada a una rama
• los criterios de aceptación son estables
• el agente puede trabajar durante un tiempo sin supervisión constante
• quieres progreso asíncrono, revisión de diffs o corrección automática de PRs

Por ejemplo, el flujo del worker de SCIM es un excelente candidato para ejecutarse en la nube una vez que los contratos sean estables.

Desde el worktree del worker:

cd ../wt-042-sso-worker
git push -u origin feat/042-sso-worker

claude --remote "Checkout feat/042-sso-worker and implement the approved
SCIM retry and reconciliation tasks from specs/042-enterprise-sso/tasks.md.
Do not change API contracts without asking. Run tests and leave the branch
ready for PR review."

Por qué funciona esta división:

• Claude Code en la web ejecuta la tarea de forma asíncrona en infraestructura administrada por Anthropic
• permite revisar los diffs antes de crear el PR
• puede responder a comentarios del PR y fallas de CI si la corrección automática está habilitada
• puedes teletransportar la sesión de vuelta a la terminal más adelante si quieres continuar localmente

Esto es mucho más seguro que darle a un agente en la nube un prompt vago como «construye SSO empresarial».

Paso 8: establece las mismas reglas de trabajo para personas y agentes

Si participan tanto personas como IA, el repositorio necesita un contrato compartido.

Yo agregaría un breve bloque de instrucciones a AGENTS.md o CLAUDE.md como este:

## Delivery rules for feature 042-enterprise-sso

- Read `specs/042-enterprise-sso/spec.md`, `plan.md`, and `tasks.md` before editing code.
- Claim a Beads task before starting implementation.
- One task stream per branch and worktree.
- Do not change auth contracts, audit schema, or rollout flags without updating the planning docs.
- If a task touches files owned by another active stream, stop and ask for re-planning.

Esto importa más de lo que parece.

Cuando varios agentes están activos, el principal modo de falla no son los errores de sintaxis. Es la superposición de trabajo no declarada.

Paso 9: asigna el trabajo como líder de ingeniería, no como autor de prompts

La unidad de trabajo más útil para un traspaso no es «ayúdame con SSO».

Se parece más a esto:

• Ingeniero de frontend: responsable de feat/042-sso-ui; implementa las pantallas de configuración administrativa, validación y estado de sincronización; no modifica la semántica del callback
• Ingeniero de backend: responsable de feat/042-sso-api; implementa el flujo ACS de SAML, el aprovisionamiento JIT y la aplicación de las reglas de dominio del tenant
• Ingeniero de plataforma: responsable de feat/042-sso-audit; define el esquema de eventos de auditoría y los hooks de instrumentación
• Claude Code en la web: responsable de feat/042-sso-worker; implementa la reconciliación de SCIM con reintentos conforme a los contratos aprobados
• Tech lead: responsable de feat/042-sso-rollout; mantiene la coherencia de la ruta de migración y la estrategia de feature flags entre todos los flujos

Así es como Beads, los worktrees y los agentes asíncronos pasan a ser útiles en lugar de generar ruido.

Cada colaborador debe tomar las tareas de forma explícita:

bd ready
bd update <task-id> --claim
bd show <task-id>

Ahora el espacio de coordinación es persistente, se puede inspeccionar y no queda atrapado en el historial del chat.

Paso 10: haz merge según el orden de las dependencias, no según el orden de finalización

Aquí es donde los equipos pueden volver a crear caos accidentalmente después de haber hecho el trabajo difícil de planificación.

No hagas merge de la rama que termine primero solo porque está lista.

Haz merge según el orden de las dependencias:

1. Contratos de API y migraciones que definen la superficie estable
2. Instrumentación de auditoría, si varios flujos la necesitan
3. Comportamiento del worker, una vez que los contratos estén implementados
4. UI y controles de despliegue, una vez que las capas inferiores sean estables

Si un flujo termina antes, no hay problema. Puede permanecer abierto hasta que la cadena de dependencias esté lista.

Aquí también puede ser útil el ciclo de corrección automática de PRs de Claude Code. Una rama bien delimitada que ya tiene una persona responsable es una buena candidata para:

• correcciones de fallas de CI
• ajustes de estilo o lint
• pequeñas iteraciones sobre comentarios de revisión

No es el lugar para permitir que un agente reinterprete la arquitectura después de que el equipo ya acordó la especificación.

Dónde falla este flujo de trabajo

Este patrón es sólido, pero no universal.

Deja de funcionar cuando:

• la funcionalidad es demasiado pequeña para justificar una rama de planificación
• el repositorio está tan acoplado que los «flujos separados» siguen editando los mismos archivos
• el equipo trata Beads y los planes en Markdown como dos fuentes de verdad separadas
• nadie se hace responsable de los criterios de aceptación después de generar las tareas

También falla si omites la revisión de planificación y pasas directamente de un prompt a un plan de ejecución con cinco ramas. Eso solo genera confusión más rápido.

Las opciones predeterminadas más seguras son:

• la especificación primero
• un grafo de tareas aprobado
• una persona responsable por flujo
• un worktree por flujo
• una fuente de verdad para el estado de las tareas

La conclusión práctica

El artículo comparativo anterior fue útil porque separó la planificación, la ejecución y la persistencia como fortalezas de distintas herramientas.

La conclusión más práctica de este artículo es la siguiente:

Usa Spec Kit y Cursor para decidir qué se debe construir. Usa Beads para recordar qué se está construyendo actualmente. Usa ramas, worktrees y Claude Code para controlar cómo se construye.

Suena sencillo, pero resuelve un problema de ingeniería muy real:

• las especificaciones tienden a desaparecer en los historiales de chat
• las tareas pierden coherencia entre sesiones
• las ramas se convierten en cajones de sastre
• los agentes se superponen cuando nadie define las responsabilidades

Una rama de planificación basada primero en la especificación, seguida de un grafo de tareas de Beads y luego de worktrees aislados, es el patrón más claro que he encontrado hasta ahora para mantener comprensible una funcionalidad compleja mientras varias personas y agentes trabajan al mismo tiempo.

Fuentes

• Guía de inicio rápido de Spec Kit
• Página principal de la documentación de Spec Kit
• Documentación de planificación de Cursor
• Documentación de reglas y orientación para proyectos de Cursor
• Changelog de Cursor
• Descripción general de Claude Code
• Claude Code en la web
• Control remoto de Claude Code
• README de Beads
• Documentación de Git worktree