subagent-driven-development

Descripción general

¿Qué es subagent-driven-development?

subagent-driven-development es una skill de orquestación de agentes para ejecutar un plan de implementación como una secuencia de tareas independientes, cada una resuelta por un subagente nuevo. En cada tarea, haces lo siguiente:

1. Creas un subagente implementador dedicado.
2. Ejecutas un subagente revisor de cumplimiento de especificaciones.
3. Ejecutas un subagente revisor de calidad de código.

Los tres se mantienen en un contexto estrictamente controlado para que se centren solo en la tarea actual, mientras tu sesión principal queda libre para coordinación y toma de decisiones.

¿Para quién es esta skill?

subagent-driven-development está diseñada para desarrolladores y equipos que:

• Usan asistentes de programación con IA (como Claude / claude-code) y buscan resultados más fiables.
• Trabajan a partir de un plan de implementación escrito desglosado en tareas discretas.
• Necesitan una forma estructurada y repetible de implementar y revisar código en una única sesión con IA.
• Se preocupan tanto por la corrección respecto a la especificación como por la calidad del código, no solo por "algo que funcione".

Encaja especialmente bien en flujos de trabajo centrados en GitHub, donde puedes pasar SHAs, archivos de plan y diffs a los subagentes.

¿Qué problemas resuelve?

Esta skill aborda problemas habituales al usar un único agente de IA para desarrollo de extremo a extremo:

• Sobrecarga de contexto: Un solo agente acumula demasiada historia y pierde foco.
• Desviación de la especificación: Las implementaciones se alejan gradualmente del plan o requisitos originales.
• Revisiones débiles: El mismo contexto que escribió el código intenta revisarlo y pasa por alto errores.

subagent-driven-development impone un patrón: agente nuevo por tarea, contexto estricto y revisión en dos fases (primero especificación, luego calidad). Esto mejora la corrección, mantiene los cambios acotados y facilita razonar sobre cada paso de tu plan de implementación.

¿Cuándo encaja bien subagent-driven-development?

Usa esta skill cuando:

• Ya tienes un plan de implementación desglosado en tareas.
• Las tareas son mayoritariamente independientes; no requieren coordinación constante entre ellas.
• Planeas completar el plan en la sesión actual, sin repartirlo en varios días.

Si todavía no tienes un plan, o las tareas están fuertemente acopladas y cambian con rapidez, quizá prefieras:

• Hacer primero lluvia de ideas o diseñar el plan con otras skills o planificación manual.
• Usar un flujo de trabajo más libre con un único agente para trabajo exploratorio.

Cómo usarla

Instalación

1. Añade la skill a tu entorno

Instala la skill subagent-driven-development desde el repositorio obra/superpowers:

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

Esto descarga la definición de la skill y las plantillas de prompts de soporte en tu entorno con skills, para que puedas orquestar subagentes para cada tarea de tu plan.

2. Revisa los archivos principales

Tras la instalación, abre el directorio de la skill en el repositorio (o mediante tu navegador de skills) y revisa:

• SKILL.md – descripción de alto nivel, cuándo usarla y flujo de trabajo principal.
• implementer-prompt.md – plantilla para tu subagente implementador.
• spec-reviewer-prompt.md – plantilla para tu subagente revisor de cumplimiento de especificaciones.
• code-quality-reviewer-prompt.md – plantilla para tu subagente revisor de calidad de código.

Trátalas como plantillas que puedes copiar o adaptar a tu propia automatización o integración con herramientas.

Preparar tu plan de implementación

1. Escribe o depura tu lista de tareas

Antes de usar subagent-driven-development, prepara un plan de implementación con tareas que sean:

• Claramente acotadas y comprobables.
• Mayoritariamente independientes entre sí.
• Expresadas con suficiente detalle para que un subagente implementador pueda actuar sin adivinar.

Cada tarea debería poder copiarse y pegarse en el prompt del implementador como "FULL TEXT of task from plan".

2. Define tu directorio de trabajo y tu estrategia con Git

Las plantillas de prompt asumen un flujo de trabajo basado en Git y un directorio de trabajo concreto:

• Elige un directory donde trabajará el implementador.
• Decide cómo vas a seguir los cambios (por ejemplo, BASE_SHA y HEAD_SHA para cada tarea).

Pasarás estos valores a los prompts del revisor de especificaciones y del revisor de calidad de código para obtener revisiones precisas.

Ejecutar el flujo de trabajo por tarea

1. Lanza un subagente implementador

Para cada tarea N, crea un nuevo subagente implementador usando la plantilla en implementer-prompt.md.

Puntos clave de la plantilla:

• Al implementador se le indica explícitamente: "You are implementing Task N: [task name]".
• Pegas el texto completo de la tarea en la sección ## Task Description.
• Rellenas:
  • Context – cómo encaja en tu sistema.
  • directory – dónde hacer los cambios.

Se instruye al implementador para que:

1. Haga preguntas de aclaración antes de empezar si algo no está claro.
2. Implemente exactamente lo que especifica la tarea.
3. Escriba y ejecute tests cuando sea apropiado.
4. Verifique la implementación.
5. Haga commit del trabajo.
6. Genere un informe claro de lo que se ha hecho.

Como creas un subagente nuevo para cada tarea, solo ve el contexto que tú le proporcionas y no hereda historial irrelevante de tu sesión principal.

2. Ejecuta una revisión de cumplimiento de especificaciones

Cuando el implementador termine y te entregue su informe, lanza un subagente revisor de cumplimiento de especificaciones usando spec-reviewer-prompt.md.

En esta plantilla:

• Pegas los requisitos de la tarea en ## What Was Requested.
• Pegas el informe del implementador en ## What Implementer Claims They Built.

Se indica de forma explícita al revisor de especificaciones que no confíe en el informe del implementador y que debe:

• Leer el código real.
• Compararlo línea por línea con los requisitos.
• Identificar requisitos faltantes, trabajo extra/no deseado y malentendidos.

Si el revisor de especificaciones encuentra problemas, vuelves a iterar con el implementador (el mismo o un nuevo subagente) para cubrir las lagunas antes de continuar.

3. Ejecuta una revisión de calidad de código

Cuando la revisión de especificaciones haya pasado, lanza un subagente revisor de calidad de código usando code-quality-reviewer-prompt.md.

La plantilla espera una descripción de tarea al estilo code review, por ejemplo:

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

El revisor comprueba:

• Limpieza y mantenibilidad de la implementación.
• Responsabilidades e interfaces de los archivos (una responsabilidad clara por archivo siempre que sea posible).
• Si los archivos nuevos o modificados tienen un tamaño y descomposición adecuados.
• Cobertura de tests y capacidad de entender y probar unidades de forma independiente.

Devuelven comentarios estructurados: puntos fuertes, problemas (Critical / Important / Minor) y una evaluación general.

A partir de ahí puedes decidir si:

• Aceptar el cambio tal cual.
• Pedir al implementador que haga refactors adicionales.

Adaptar el flujo de trabajo a tu entorno

1. Personaliza los prompts para tu stack

Las plantillas en implementer-prompt.md, spec-reviewer-prompt.md y code-quality-reviewer-prompt.md son intencionadamente genéricas. Adáptalas a tu:

• Lenguajes de programación y frameworks.
• Convenciones de testing (por ejemplo, pytest, Jest, Go test).
• Estructura del repositorio y nomenclatura.

Mantén la estructura central: subagente nuevo, secciones claras, descripción explícita del trabajo, incluso cuando personalices los detalles.

2. Automatiza los pasos repetitivos

Cuando te sientas cómodo con el patrón, puedes crear scripts o herramientas:

• Encapsula las tres llamadas a subagentes (implementer → spec reviewer → code quality reviewer) en un solo comando por tarea.
• Genera prompts específicos por tarea automáticamente a partir de un archivo de plan.
• Rellena BASE_SHA y HEAD_SHA leyendo los metadatos de Git.

Así conviertes subagent-driven-development en una automatización de flujo de trabajo repetible para tu equipo.

3. Cuándo esta skill no es la mejor opción

Quizá te convenga otro enfoque cuando:

• Las tareas están muy interrelacionadas y no se pueden aislar con claridad.
• Aún no tienes un plan de implementación definido.
• Necesitas trabajo de larga duración, entre sesiones, donde el contexto tenga que mantenerse durante días.

En esos casos, recurre a skills o procesos centrados en planificación, arquitectura o agentes de largo plazo, y vuelve a subagent-driven-development cuando estés listo para ejecutar tareas discretas.

Preguntas frecuentes

¿Qué significa "subagent-driven-development" en la práctica?

En la práctica, subagent-driven-development significa que no le pides a un agente "todopoderoso" que planifique, programe y revise todo. En lugar de eso:

• Mantienes la coordinación y el contexto general en tu sesión principal.
• Para cada tarea, construyes un subagente nuevo con solo la información que necesita.
• Ejecutas ese subagente para implementar la tarea y luego ejecutas dos subagentes más para revisarla.

Esto separa las responsabilidades, mantiene el contexto manejable y mejora la fiabilidad en cada paso de tu plan de implementación.

¿En qué se diferencia de una sesión de programación normal con un solo agente?

Con un solo agente, la conversación previa y los cambios de código se acumulan en un único contexto, lo que puede llevar a:

• Confusión entre requisitos antiguos y nuevos.
• Reutilizar los mismos patrones de razonamiento tanto para programar como para revisar.

En cambio, subagent-driven-development:

• Usa prompts y roles separados para implementación y revisión.
• Arranca cada subagente con contexto seleccionado, no con todo el historial de la sesión.
• Impone un orden de revisión de primero especificación y luego calidad.

Esto suele producir implementaciones más precisas y revisiones más honestas.

¿Tengo que seguir las plantillas al pie de la letra?

No. Las plantillas del repositorio son ejemplos de cómo estructurar los prompts del implementador, del revisor de especificaciones y del revisor de calidad de código. Se espera que:

• Mantengas el patrón general: implementer → spec review → quality review.
• Conserves comportamientos clave (por ejemplo, el revisor de especificaciones debe leer el código real y no confiar en el informe).

Dentro de esa estructura puedes ajustar la redacción, añadir indicaciones específicas del proyecto e integrarlo con tus herramientas y convenciones.

¿Puedo usar subagent-driven-development sin Git?

La plantilla del revisor de calidad de código asume campos como BASE_SHA y HEAD_SHA, naturales en un flujo de trabajo con Git. Si no usas Git:

• Puedes aplicar igualmente las mismas ideas clave: subagentes nuevos y revisión en dos etapas.
• Sustituye las SHAs por tu propia manera de referenciar el estado anterior/posterior (por ejemplo, identificadores de archivo comprimido o rutas de snapshots).

La skill no obliga a usar Git; simplemente proporciona ejemplos orientados a Git.

¿Esta skill depende de un modelo de IA específico?

El repositorio no te bloquea en un modelo concreto, pero está claramente orientado a modelos modernos y generalistas para programación, como Claude / claude-code de Anthropic. Deberías:

• Usar un modelo capaz de leer y razonar sobre código y tests.
• Asegurarte de que tu entorno permite lanzar varios subagentes con prompts personalizados.

Si tu stack soporta herramientas de agente o task runners, puedes integrar estas plantillas en ese sistema.

¿Cómo sé cuándo usar subagent-driven-development frente a otra skill de superpowers?

El archivo SKILL.md describe los criterios de decisión: usa subagent-driven-development cuando ya tienes un plan de implementación, tus tareas son mayoritariamente independientes y planeas mantenerte en la sesión actual. Si alguna de estas condiciones no se cumple, puedes:

• Usar skills de planificación o brainstorming para crear primero el plan.
• Usar otros patrones de ejecución o planificación para trabajo fuertemente acoplado y entre sesiones.

¿Por dónde empiezo en el repositorio?

Si estás evaluando si instalar o adoptar esta skill, empieza por:

1. SKILL.md – para el razonamiento y el flujo de trabajo de alto nivel.
2. implementer-prompt.md – para ver cómo se plantean los subagentes implementadores.
3. spec-reviewer-prompt.md – para entender las comprobaciones de cumplimiento de especificaciones.
4. code-quality-reviewer-prompt.md – para ver las comprobaciones adicionales de calidad y estructura.

A partir de ahí, puedes adaptar estas plantillas a tu propia orquestación de agentes o configuración de automatización de flujos de trabajo y aprovechar al máximo subagent-driven-development.