LaiAnTan/agentic-setup

Diseño antes de construir

Los agentes son rápidos implementando pero malos notando que un diseño se está degradando. La solución es acordar las decisiones antes de que exista el código, para que cada PR sea rápido de revisar porque coincide con lo que ya fue aprobado. Tú redactas cada etapa; el usuario revisa y aprueba.

1. Dimensiona el trabajo y elige las etapas

Trabajo	Etapas
Funcionalidad mediana, refactorización contenida	diseño de programa → slices
Funcionalidad grande, refactorización transversal	arquitectura → diseño de programa → slices
Proyecto nuevo, multi-repo o problema poco claro	producto → arquitectura → diseño de programa → slices

Di en una línea qué tamaño elegiste y por qué. El usuario puede añadir o saltar etapas.

2. Reúne contexto primero

Antes de redactar nada: lee docs/README.md y la documentación viva a la que apunta, cualquier diseño abierto en docs/designs/, el código relevante y el historial de git del área. Para elecciones entre herramientas o enfoques, investiga (documentación, benchmarks, problemas conocidos) y da opciones concretas con fuentes. No diseñes a partir de suposiciones.

3. Ejecuta cada etapa

Crea el archivo de diseño docs/designs/YYYY-MM-DD-<slug>.md a partir de template.md (configura primero la estructura docs/ según las reglas globales si el repositorio no la tiene). Para cada etapa, lee su archivo de etapa a continuación (en la carpeta de este skill), redacta esa sección del archivo de diseño y luego detente:

• product.md: problema, usuarios, comportamiento, fuera de alcance
• architecture.md: componentes, contratos, modelo de datos, restricciones
• program-design.md: tipos, firmas, estructura de archivos, flujo de llamadas
• slices.md: orden de construcción, repositorios, PRs y la verificación de cada slice

Al detenerte, muéstrale al usuario:

• un diagrama donde sea útil, más un breve resumen (no el documento completo pegado en el chat)
• las decisiones que tomaste y las preguntas abiertas, numeradas para que puedan responder "2: sí"

No comiences la siguiente etapa hasta que el usuario apruebe esta. Si cambian algo, actualiza el archivo de diseño, no solo el chat.

4. Construye slice por slice

Después de que el plan de slices esté aprobado:

• Construye un slice a la vez; cada uno termina cuando su verificación acordada pasa y se muestra la evidencia.
• Un PR (o commit, si el usuario no usa PRs) por slice, descrito según las reglas globales.
• Si la implementación muestra que el diseño es incorrecto, detente y propón el cambio al diseño en lugar de desviarte silenciosamente. Actualiza el archivo de diseño cuando se acuerde un cambio.
• Marca los slices completados en el archivo de diseño a medida que se integran, para que una sesión posterior pueda retomarlo.

5. Finaliza

Cuando el último slice se integre, refleja el resultado para que la documentación viva siga siendo la fuente de verdad:

• Actualiza docs/product.md, docs/architecture.md y cualquier documento temático del repositorio (no los archivos de etapa de este skill) para describir el sistema tal como es ahora, siguiendo las reglas de escritura de documentación de las reglas globales.
• Añade cualquier término nuevo difícil o específico del proyecto a docs/glossary.md.
• Convierte cada decisión significativa en una nota docs/decisions/NNNN-<slug>.md.
• Marca el archivo de diseño como completado y agrégalo a docs/README.md. No lo reescribas después.
• Muéstrale al usuario qué cambió en la documentación viva.