subagent-driven-development

Visión general de la skill subagent-driven-development

Qué hace realmente subagent-driven-development

La skill subagent-driven-development es un flujo de trabajo para ejecutar un plan de implementación dividiendo el trabajo en tareas independientes, asignando cada tarea a un subagente nuevo y revisando cada resultado en dos pasadas: primero el cumplimiento de la especificación y después la calidad del código. Su valor real no está en “usar más agentes”, sino en usar contexto aislado de forma intencional para que cada ejecutor reciba solo la tarea, los requisitos y el contexto local de código que necesita.

Cuándo encaja mejor esta skill

Esta subagent-driven-development skill funciona mejor para quienes ya tienen un plan y necesitan convertirlo en una implementación fiable dentro de la sesión actual. Encaja especialmente bien cuando:

• las tareas son en su mayoría independientes
• quieres que el agente coordinador siga centrado en la orquestación
• te importa detectar tanto desviaciones respecto a los requisitos como código descuidado
• quieres un bucle de revisión repetible, no solo un prompt puntual para programar

El trabajo que resuelve

Los usuarios adoptan subagent-driven-development for Agent Orchestration cuando un prompt normal de “implementa este plan” empieza a fallar de maneras predecibles: el agente mezcla tareas, olvida restricciones, construye de más o entrega código que parece correcto, pero no cumple la especificación. Esta skill aporta un patrón disciplinado de asignación y revisión que reduce esos fallos.

Qué la diferencia de un prompt genérico

Los diferenciales clave son prácticos:

• Un subagente nuevo por tarea en lugar de un único agente de larga duración cargando historial ruidoso
• Paquetes de tarea explícitos con el texto completo de la tarea pegado, en vez de pedir al ejecutor que deduzca los requisitos a partir de archivos dispersos
• Preguntas obligatorias antes de programar para que los requisitos ambiguos aparezcan pronto
• Revisión en dos etapas donde “¿cumple la especificación?” se separa de “¿el código está bien hecho?”

Esa separación importa. Muchos equipos revisan la calidad antes de verificar el alcance, y eso hace más difícil detectar trabajo sobredimensionado o insuficiente.

Cuándo no es la opción adecuada

No empieces con subagent-driven-development si todavía no tienes un plan de implementación concreto, si las tareas están muy acopladas o si el trabajo debería ir en un flujo de ejecución paralelo aparte y no en esta sesión. En esos casos, normalmente conviene empezar por planificación o por otra skill de ejecución.

Cómo usar la skill subagent-driven-development

Instalar subagent-driven-development skill

Si instalas skills de este repositorio mediante Skills CLI, usa:

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

Después, abre la skill instalada y las plantillas de prompt de apoyo antes de la primera ejecución.

Lee primero estos archivos

Para adoptarla rápido, lee los archivos en este orden:

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

Ese recorrido te da primero el flujo de trabajo y después la forma exacta de los prompts para el implementador y las dos fases de revisión.

Entiende el patrón de llamada antes de empezar con subagent-driven-development

En la práctica, subagent-driven-development usage no es un comando mágico único. Se usa actuando como coordinador:

1. toma una tarea del plan
2. lanza un subagente implementador nuevo con un prompt de alcance acotado
3. exige un informe de vuelta
4. ejecuta un spec reviewer sobre el código real
5. solo si la spec pasa, ejecuta un code quality reviewer
6. acepta, revisa o vuelve a despachar

Si te saltas las compuertas de revisión, en realidad ya no estás usando la skill tal como fue diseñada.

Qué información necesita la skill

Prepara estas entradas antes de despachar cualquier subagente:

• el texto exacto de la tarea en tu plan
• criterios de aceptación o requisitos
• contexto arquitectónico relevante
• directorio de trabajo o alcance dentro del repo
• cualquier nota sobre dependencias o secuenciación
• el commit base o SHA de referencia para revisar diffs
• número y nombre de la tarea para trazabilidad

Las plantillas de origen dejan bastante claro que conviene pegar la tarea completa en el prompt, no decirle al subagente que “vaya a leer el archivo del plan”.

Convierte un objetivo difuso en un buen prompt para el implementador

Un prompt débil diría:

• “Implementa la tarea 4 del plan.”

Un prompt mejor de subagent-driven-development guide incluye:

• Título y número de la tarea
• Texto completo de la tarea
• Por qué existe esta tarea
• En qué parte del repo hay que trabajar
• Restricciones sobre la estructura de archivos
• Si se requieren tests
• Qué hacer si hay que asumir algo
• La obligación de hacer preguntas antes de programar

Esa estructura importa porque la skill está diseñada en torno a contexto controlado, no a una interpretación autónoma de todo el repo.

Ejemplo de un mejor paquete de tarea

Usa una estructura como esta al despachar al implementador:

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

Esto es más fiable que decirle al ejecutor que explore el repo de forma amplia, porque la skill asume que el coordinador es responsable de empaquetar bien la asignación.

Por qué la revisión de spec va antes que la revisión de calidad

Esta es una de las partes de más valor en una decisión de subagent-driven-development install: el orden es intencional.

Ejecuta primero el spec reviewer para responder:

• ¿el código implementa lo que se pidió?
• ¿se saltó requisitos?
• ¿añadió trabajo no solicitado?
• ¿malinterpretó la tarea?

Solo después debería ejecutarse el code quality reviewer, que comprueba mantenibilidad, descomposición, responsabilidad por archivo y forma del cambio. Si inviertes el orden, el código que “se ve bien” puede ocultar errores de alcance.

Cómo usar bien el spec reviewer

La plantilla spec-reviewer-prompt.md es especialmente directa: le dice al revisor que no confíe en el informe del implementador y que verifique el código real línea por línea. Mantén ese tono al adaptarla. El revisor necesita:

• el texto completo de los requisitos
• la salida que afirma haber producido el implementador
• acceso al código modificado

La idea es verificación independiente, no una validación cortés.

Cómo usar bien el code quality reviewer

La revisión de calidad de código no es una vigilancia genérica de estilo. En esta skill pone el foco en:

• una responsabilidad clara por archivo
• interfaces bien definidas
• descomposición en unidades comprensibles
• alineación con la estructura de archivos prevista
• si la tarea creó archivos nuevos demasiado grandes o infló en exceso archivos existentes

Esa última comprobación es útil porque los subagentes a menudo resuelven la tarea metiendo demasiado en un solo cambio.

Flujo recomendado dentro de un repo real

Un bucle práctico de subagent-driven-development usage se ve así:

1. elige la siguiente tarea independiente
2. guarda el commit actual como base
3. despacha al implementador con el texto completo de la tarea
4. recoge su resumen y los archivos modificados
5. ejecuta la revisión de spec contra requisitos y código
6. si la spec falla, devuelve al implementador las brechas concretas
7. si la spec pasa, ejecuta la revisión de calidad de código
8. si la calidad falla, pide una revisión focalizada
9. integra el cambio o pasa a la siguiente tarea

Esto mantiene al coordinador al mando de la secuencia y de la aceptación final.

Restricciones que afectan a la calidad del resultado

La skill funciona mejor cuando respetas sus límites:

• las tareas independientes rinden mejor que las tareas enredadas
• los requisitos explícitos funcionan mejor que los requisitos inferidos
• un alcance de repo estrecho supera a “mira alrededor y decide”
• los ciclos de tarea cortos funcionan mejor que los lotes grandes con varias features
• reglas claras de escalado funcionan mejor que suposiciones silenciosas

Si ves que un subagente necesita reconciliar demasiadas piezas móviles en toda la base de código, probablemente la tarea es demasiado amplia para este flujo.

Error común al adoptarla

El error más frecuente es usar la subagent-driven-development skill solo como etiqueta mientras se siguen escribiendo prompts vagos. El flujo solo compensa si realmente empaquetas bien el contexto y haces cumplir la secuencia de revisión. Si no, te quedas con el coste de la orquestación sin las mejoras de calidad.

Preguntas frecuentes sobre la skill subagent-driven-development

¿subagent-driven-development es buena para principiantes?

Sí, siempre que ya entiendas la tarea que quieres construir. El flujo es explícito y las plantillas de prompt incluidas reducen bastante la incertidumbre. Pero no sustituye la planificación. Los principiantes que todavía no tienen un plan de implementación claro pueden atascarse, porque la skill da por hecho que las definiciones de tarea ya existen.

¿Cuándo no debería usar subagent-driven-development?

Omite subagent-driven-development cuando:

• todavía estás explorando el problema
• las tareas son profundamente interdependientes
• los requisitos son inestables
• una persona o un solo agente necesita razonar de forma continua sobre todo el sistema

Es un patrón de ejecución, no un patrón de descubrimiento.

¿En qué se diferencia de pedirle a un solo agente que programe todo?

Un único prompt largo suele mezclar planificación, implementación, validación y revisión dentro de la misma ventana de contexto. Esta skill separa esos roles. Eso normalmente mejora el foco, facilita detectar desviaciones respecto a los requisitos y preserva el contexto del coordinador para orquestación en lugar de gastarlo en generación de código.

¿La skill requiere herramientas especiales?

No hay scripts especiales incluidos en esta carpeta de skill. El repositorio aporta plantillas de prompt en markdown, no código de automatización. Puedes usar este patrón en cualquier entorno donde puedas despachar subagentes y ejecutar tareas de revisión de código.

¿subagent-driven-development es solo para proyectos grandes?

No. También puede servir para cambios pequeños, pero aporta más valor cuando un plan tiene varias tareas independientes y el coste de pasar por alto requisitos es lo bastante alto como para justificar la sobrecarga de revisión.

¿Qué evidencia del repositorio importa más antes de instalar?

Para esta skill, la evidencia principal está en el diseño del flujo dentro de SKILL.md y en las tres plantillas de prompt. No hay scripts auxiliares ni carpetas de recursos haciendo trabajo oculto, así que tu decisión de instalación debería centrarse en si la estructura de prompts y la disciplina de revisión encajan con la forma en que ya entregas código.

Cómo mejorar la skill subagent-driven-development

Da mejores paquetes de tarea, no prompts más largos

Para mejorar los resultados de subagent-driven-development skill, aumenta la precisión en vez de la longitud. Lo más útil que puedes añadir es:

• criterios de aceptación exactos
• no objetivos explícitos
• notas de arquitectura relevantes solo para esta tarea
• límites de archivos o directorios
• ejemplos del comportamiento esperado
• expectativas de tests

Esto ayuda al implementador a mantenerse enfocado y al spec reviewer a detectar desviaciones.

Define límites de tarea más nítidos

Muchos fallos vienen de trocear mal el trabajo. Si un subagente necesita coordinar varias piezas móviles, decidir arquitectura e inferir requisitos al mismo tiempo, divide la tarea. Las mejores tareas son lo bastante acotadas como para que “implementó exactamente lo solicitado” sea fácil de verificar.

Mantén el paso de preguntar antes de empezar

La plantilla del implementador le indica explícitamente al ejecutor que haga preguntas antes de empezar y otra vez si aparecen sorpresas durante la implementación. Conserva ese comportamiento. Suprimir las peticiones de aclaración produce resultados rápidos, pero poco fiables, y eso va justo contra el propósito de la skill.

Mejora la calidad de la revisión con mejores insumos de comparación

Para el spec reviewer, proporciona:

• texto completo de los requisitos
• informe del implementador
• archivos modificados o alcance del diff
• cualquier exclusión explícita

Para el code quality reviewer, proporciona:

• BASE_SHA
• HEAD_SHA
• resumen de la tarea
• sección relevante del plan

Esos puntos de comparación concretos hacen que las revisiones vayan más allá de una simple opinión.

Vigila estos modos de fallo habituales

Los problemas más comunes en subagent-driven-development for Agent Orchestration son:

• el implementador infiere features adicionales
• el paquete de tarea omite una restricción clave
• el revisor confía demasiado en el resumen del implementador
• la revisión de calidad se ejecuta antes que la revisión de spec
• las tareas son demasiado grandes para verificarse con claridad
• el crecimiento de archivos pasa sin control

Todos son evitables con mejor empaquetado de tareas y compuertas más estrictas.

Itera después de la primera salida

Si la primera pasada sale floja, no reinicies desde cero de inmediato. Primero identifica qué capa falló:

• fallo de spec: requisitos poco claros, incompletos o sobredimensionados
• fallo de calidad: problemas de descomposición, mantenibilidad o estructura de archivos
• fallo de coordinación: la división de tareas o el empaquetado de contexto era incorrecto

Luego revisa solo esa capa. Eso mantiene el flujo eficiente.

Refuerza la guía sobre estructura de archivos

Un detalle útil de la plantilla de calidad es comprobar si la implementación siguió la estructura de archivos prevista y si los archivos nuevos ya nacen demasiado grandes. Si te importa la mantenibilidad, incluye desde el principio en el paquete de tarea los límites deseados de archivos en lugar de esperar a que los revisores lo detecten después.

Crea una checklist local reutilizable

Si vas a usar subagent-driven-development con frecuencia, conserva una checklist corta para el coordinador:

• el plan existe
• la tarea es independiente
• la tarea completa está pegada
• las restricciones están incluidas
• se capturó el SHA base
• se pidió al implementador que aclare dudas antes de programar
• se completó la revisión de spec
• se completó la revisión de calidad

Ese pequeño hábito mejora la consistencia más que escribir prompts más largos.

Adapta la skill a tu propio flujo de trabajo

La skill base es deliberadamente ligera. Para hacerla más efectiva en tu entorno, adapta las plantillas de prompt a tu stack y a tus estándares de revisión:

• añade tus comandos de testing
• añade reglas de arquitectura específicas del repo
• define qué consideras sobreingeniería
• especifica tu formato de informe preferido
• incluye patrones de fallo comunes en tu base de código

Ese tipo de ajuste local suele mejorar subagent-driven-development usage más que añadir más teoría.