blueprint

Visión general de la skill blueprint

Qué hace blueprint

La skill blueprint convierte un objetivo de una sola línea en un plan de construcción paso a paso para trabajo de ingeniería complejo. Está pensada para tareas de varias sesiones y varios PR, donde un agente nuevo necesita contexto suficiente para continuar sin tener que adivinar. Si necesitas un blueprint para Project Setup, una hoja de ruta de migración o un plan de refactorización con dependencias, esta skill encaja muy bien.

Quién debería instalarla

Instala blueprint si sueles traspasar trabajo entre sesiones, coordinar subtareas en paralelo o necesitas un plan que resista la pérdida de contexto. Es especialmente útil para agentes que trabajan dentro de un repo existente, donde el reto real no es generar ideas, sino secuenciar el trabajo de forma segura.

Qué la hace diferente

A diferencia de un prompt genérico, blueprint incorpora reglas de activación, ordenación de dependencias, detección de pasos paralelos, una puerta de revisión adversarial y un protocolo de mutación del plan. Esto importa cuando el principal riesgo no es escribir código, sino elegir el orden equivocado, definir un paso con un alcance insuficiente o pasar por alto una vía de rollback.

Cómo usar la skill blueprint

Instálala y actívala correctamente

Instala la skill blueprint con el instalador habitual de skills del directorio y actívala solo cuando la tarea sea realmente de varias etapas. La propia regla de activación del repositorio es intencionalmente acotada: úsala para un plan, blueprint u hoja de ruta cuando el trabajo probablemente requiera varias sesiones o varios PR; no la uses para un cambio pequeño que puedas terminar de una sola vez.

Dale el input de origen adecuado

Blueprint funciona mejor cuando tu input nombra el objetivo, el repo de destino, las restricciones y la definición de terminado. Un prompt flojo sería “plan the refactor”. Uno más sólido sería: “Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.” Cuanto más concreto sea el alcance, mejor saldrán el grafo de dependencias y el tamaño de los pasos.

Lee primero estos archivos

Empieza por SKILL.md y luego revisa cualquier documentación del repo que describa el flujo de trabajo, las convenciones o planes ya existentes. En este repositorio, el cuerpo de la skill es autocontenido, así que lo clave es extraer el pipeline: investigación, diseño, revisión y reglas de mutación. Si el codebase de destino tiene archivos de memoria, documentos de arquitectura o notas de migración previas, eso mejorará de forma sustancial el resultado de blueprint.

Flujo de trabajo que da mejores resultados

Usa blueprint en tres pasadas: primero genera el plan, luego comprueba si los pasos realmente pueden sostenerse por sí solos y después revísalo para detectar dependencias faltantes o paralelismo inseguro. Presta atención a los pasos que tocan los mismos archivos, comparten estado o dependen de una secuencia de release; ahí es donde un plan que sobre el papel parece limpio puede fallar en la ejecución. El mejor uso de blueprint no es “más detalle”, sino “secuenciación correcta con contexto suficiente para ejecutar en frío”.

Preguntas frecuentes sobre la skill blueprint

¿Blueprint es solo para proyectos grandes?

Sí, en la mayoría de los casos. La skill está diseñada para trabajo demasiado grande para un único PR o que sería arriesgado intentar sin un plan. Si la tarea es pequeña, directa o se puede completar en unas pocas llamadas a herramientas, un prompt normal suele ser más rápido.

¿En qué se diferencia blueprint de un prompt normal?

Un prompt normal puede pedir un plan, pero blueprint añade estructura: dependencias entre pasos, detección de trabajo en paralelo, pensamiento de rollback y una capa de revisión que intenta detectar supuestos débiles. Eso la hace más fiable cuando necesitas un blueprint para Project Setup u otra tarea donde importan el orden y la calidad del traspaso.

¿Blueprint sirve para principiantes?

Sí, si el objetivo es aprender a dividir un proyecto en fases manejables. Es menos útil si todavía estás decidiendo cuál es exactamente la tarea, porque la skill asume que ya existe un objetivo de ingeniería real, con restricciones y un camino de ejecución.

¿Cuándo no debería usar blueprint?

No uses blueprint cuando el trabajo sea lo bastante pequeño como para completarlo directamente, cuando el usuario diga explícitamente “just do it” o cuando la tarea no tenga una estructura de dependencias significativa. En esos casos, la sobrecarga de planificación puede ralentizarte sin mejorar el resultado.

Cómo mejorar la skill blueprint

Sé explícito con los límites

Los mejores resultados de blueprint salen de límites de alcance claros: qué debe cambiar, qué debe mantenerse estable, qué queda fuera de alcance y qué cuenta como éxito. Si quieres un blueprint para Project Setup, aclara si vas a cambiar el bootstrapping del repo, la configuración de entorno, la configuración de CI o las tres cosas. Un alcance ambiguo es la vía más rápida para acabar con un plan demasiado grande o demasiado superficial.

Aporta pistas de dependencias desde el principio

Blueprint rinde mejor cuando sabe qué piezas bloquean a otras. Menciona migraciones, módulos compartidos, feature flags, contratos de API, orden de release y cualquier elemento que deba aterrizar antes de que otro paso pueda empezar. Esto ayuda a que la skill produzca un grafo de dependencias útil en lugar de una lista de tareas desconectadas.

Pide pasos listos para ejecutar

Si quieres mejores resultados de la skill blueprint, pide pasos que un agente nuevo pueda ejecutar en frío. Eso significa que cada paso debe incluir suficiente contexto, resultado esperado y notas de riesgo como para evitar releer todo el repo. Esto es especialmente importante en trabajo con varios agentes, donde un título de paso vago provoca retrabajo.

Itera sobre el primer plan de blueprint

Trata el primer blueprint como un borrador y luego ajústalo tras revisar restricciones ausentes, trabajo en paralelo que entra en conflicto o pasos demasiado grandes para un solo PR. Si el plan es demasiado amplio, divídelo; si es demasiado detallado, agrupa el trabajo de preparación repetido. El objetivo no es tener un esquema más bonito, sino un blueprint que reduzca el riesgo de ejecución.