xxxx2l/design-to-implement

Flujo de trabajo de diseño e implementación

Principio fundamental

Primero discutir con claridad, luego escribir código. Este flujo de trabajo fuerza la separación entre "pensar" y "hacer":

• Fase de discusión: solo diálogo, sin escribir código; todas las conclusiones se consolidan en el documento de comunicación
• Fase de diseño: se organiza el consenso en un documento de diseño, que es la única fuente de verdad
• Fase de implementación: se genera un documento de implementación basado en el diseño y se ejecutan los pasos

Si la discusión no ha llegado a una conclusión o el usuario no ha dicho explícitamente "se puede empezar", no se toca ningún código. Si siempre hay dudas, se discute hasta que ambas partes estén satisfechas.

Estructura del directorio de documentación

Se almacena fijamente en docs/design/ en la raíz del proyecto, una subcarpeta independiente por tarea:

Raíz del proyecto/
└── docs/design/
    ├── README.md              ← Visión global de todas las tareas (entrada principal para múltiples tareas, léase primero)
    ├── 01-módulo-auth/
    │   ├── 00-estado-tarea.md  ← Ancla de memoria entre contextos
    │   ├── 01-comunicacion.md
    │   ├── 02-diseno.md        ← Incluye criterios de aceptación
    │   ├── 03-implementacion.md
    │   └── 04-pruebas.md       ← Casos de prueba (generados en la fase de planificación)
    └── 02-reestructuracion-pago/
        └── ...

Reglas de nomenclatura:

• Carpeta de tarea: número de dos dígitos globalmente incremental + nombre de la tarea, ej. 01-módulo-auth, 02-reestructuracion-pago. Los números son consecutivos entre tareas, asegurando que el orden coincida con la creación.
• Documentos dentro de la tarea: prefijo fijo de fase: 00-estado-tarea / 01-comunicacion / 02-diseno / 03-implementacion / 04-pruebas. El prefijo fijo permite localizar el mismo tipo de documento en cualquier tarea de un vistazo.

Cómo determinar el número al entrar por primera vez en una tarea: mirar el número máximo de carpeta existente en docs/design/, sumar 1 para el nuevo número de tarea. Si el directorio no existe, empezar desde 01.

Primer paso de cada nueva conversación (mecanismo de memoria entre contextos)

Este flujo de trabajo puede ejecutarse a través de múltiples contextos de conversación. Para evitar tener que releer grandes bloques de código o perder la memoria en cada nueva conversación, se debe restaurar el contexto en el siguiente orden obligatorio:

1. Leer docs/design/README.md — visión global, confirmar qué tareas hay y en qué fase está cada una. Si el usuario ya ha indicado una tarea, saltar directamente a ella.
2. Leer 00-estado-tarea.md — ancla de memoria de la tarea actual, confirmar cuál es el siguiente paso.
3. Leer el documento correspondiente a la fase actual (ej. 02-diseno.md si se está en diseño, 03-implementacion.md si se está en implementación).
4. Solo leer código cuando sea necesario para verificar, no como primer medio para restaurar el contexto.

00-estado-tarea.md debe mantenerse actualizado: resumen de la tarea en una línea, fase actual, resumen de decisiones clave, pendientes y dudas, índice de documentos, registro de cambios de contexto, registro de cambios (incluye modificaciones y retrocesos, ver más abajo "Cambios durante la implementación").

Las cuatro fases del flujo de trabajo y sus documentos correspondientes

Fase 1: Discusión (salida → documento de comunicación)

Inicio: El usuario presenta un nuevo requisito, funcionalidad, módulo, o tiene dudas sobre un plan existente.

Restricciones de comportamiento:

• En esta fase solo se discute, no se escribe código de negocio.
• Cada intercambio significativo (decisión clave, alternativa rechazada, consenso alcanzado) se añade al final de 01-comunicacion.md.
• Seguimiento de preguntas pendientes: Mantener una lista de "preguntas pendientes actuales" en la parte superior de 01-comunicacion.md. Actualizarla antes de finalizar cada discusión: qué interrogantes siguen abiertos, cuáles han surgido nuevos, cuáles se han cerrado. El criterio directo para decidir si se puede pasar a la fase de diseño es si esta lista está vacía o no. Esto hace visible el proceso de convergencia de la discusión, en lugar de basarse en la sensación de que "ya se ha discutido bastante".
• La discusión es de múltiples rondas y puede abarcar varias conversaciones.
• Cuando el usuario expresa "vale", "así queda definido", "empecemos con el diseño", y la lista de preguntas pendientes está vacía, se pasa a la fase 2.

Cuándo continuar discutiendo en lugar de avanzar: Mientras haya dudas de diseño sin resolver, divergencia en la selección técnica, o límites no aclarados, se sigue consolidando en la fase 1. Es mejor preguntar una ronda más que avanzar con suposiciones poco claras hacia el diseño.

Fase 2: Diseño (salida → documento de diseño)

Inicio: La discusión ha llegado a un consenso, la lista de preguntas pendientes está vacía y el usuario acepta consolidar el plan.

Restricciones de comportamiento:

• Las conclusiones de la discusión se organizan en un 02-diseno.md estructurado. El documento de diseño es la única fuente de verdad.
• El documento de diseño debe ser lo más completo posible: debe entregar un plan determinado y ejecutable, sin dejar "pendiente" o "decidir en implementación". La integridad se garantiza con dos cosas: primero, preguntar a fondo durante la discusión; segundo, leer el código existente para confirmar todos los hechos de los que depende la implementación (forma de la interfaz, estructura de tablas, forma de invocación, etc.). La restricción de "solo discutir, no escribir código" en la fase de diseño se aplica al código de negocio; leer código existente para el diseño (investigación de diseño) no viola la restricción. En la fase de diseño, es mejor invertir más tiempo en pulir que entrar en la implementación con carencias — cualquier carencia se convertirá en retrabajo o desviación durante la implementación.
• Los criterios de aceptación son parte del diseño: el documento de diseño no solo debe escribir "qué hacer y por qué", sino también "hasta qué punto se considera que se cumple el requisito" — es decir, criterios de aceptación abstractos (a nivel de reglas, ej. "las palabras de alto riesgo deben ser bloqueadas, el artículo no se guarda"). Los criterios de aceptación definen el límite del requisito y son el último eslabón de la integridad del diseño; un documento de diseño sin criterios de aceptación equivale a no tener una definición objetiva de "terminado". Los casos de prueba concretos (a nivel de instancia) no se escriben en el documento de diseño, sino en 04-pruebas.md, generados por la fase de planificación de implementación a partir de los criterios de aceptación.
• Registro de cambios de diseño: Mantener un bloque "Registro de cambios de diseño" en el documento de diseño. Cada cambio importante se registra en una línea (fecha, qué se cambió, por qué). Es complementario a 01-comunicacion.md — la comunicación es un registro cronológico, el diseño es la conclusión, y el registro de cambios es la historia evolutiva de las conclusiones. Esto hace que la regla de "cambiar el documento de diseño, no el de implementación, cuando cambie el plan" sea realmente ejecutable sin perder el historial.
• Una vez completado el documento de diseño, actualizar 00-estado-tarea.md marcando "diseño completado, pendiente de implementación", y también actualizar la fase de la tarea en docs/design/README.md.

Fase 3: Planificación de implementación (salida → documento de implementación)

Inicio: El documento de diseño está finalizado.

Restricciones de comportamiento:

• Generar 03-implementacion.md basado en el documento de diseño, desglosando el plan en pasos ejecutables y comprobables.
• Al mismo tiempo, convertir los "criterios de aceptación" del diseño en casos de prueba concretos y generar 04-pruebas.md: los casos son la instanciación de los criterios de aceptación (ej. criterio "las palabras de alto riesgo deben ser bloqueadas" → caso "introducir texto con palabras de alto riesgo, esperar respuesta 40901, artículo no guardado"). Los casos se dividen en cuatro capas: funcional (T-F), excepción (T-EX), regresión (T-R), interfaz (T-API). El formato de numeración es T-{tipo}-{número de dos dígitos}, la plantilla está en assets/test.md.
• El documento de implementación es "cómo hacerlo", el de pruebas es "qué probar y qué esperar", el de diseño es "qué hacer y por qué". Los tres tienen responsabilidades diferentes: no copiar detalles de diseño al documento de implementación, ni incluir cambios de plan en el documento de implementación.
• El documento de implementación es una pura descomposición de pasos; cada paso es solo "implementar según tal parte del diseño", sin asumir ninguna responsabilidad de "completar el diseño". Si al desglosar los pasos se descubre que un paso requiere primero "confirmar la forma de la interfaz", "volver a escribir el diseño", "decidir el campo" para poder actuar, significa que la fase de diseño no ha terminado — en ese caso, se debe volver a la fase 2 para completar el diseño, no incluir un paso de "completar diseño" en el documento de implementación. En una frase: en el documento de implementación no debe aparecer ninguna acción del tipo "leer código para determinar el plan", solo acciones del tipo "implementar según el plan establecido".
• Las acciones de prueba en el documento de implementación solo hacen referencia al número de caso, no repiten el contenido del caso. Después de completar cada paso, lo que se debe verificar es "verificar según el caso T-XX-XX"; los casos en sí se concentran en 04-pruebas.md.
• Los pasos de implementación se dividen en pasos grandes y pasos pequeños, ambos con su propia marca de finalización independiente.
• Una vez completado el documento de implementación, actualizar 00-estado-tarea.md marcando "pendiente de implementación".

Fase 4: Implementación (ejecutar los pasos del documento de implementación)

Inicio: El usuario dice "empezar implementación", "manos a la obra", "seguir el documento".

Restricciones de comportamiento:

• Avanzar estrictamente según los pasos de 03-implementacion.md. Al completar cada paso, actualizar la marca en el documento y anotar brevemente el resultado.
• Después de completar cada paso, verificar según los casos de prueba referenciados en ese paso en 04-pruebas.md; si un caso falla, el paso no se considera completado. Localizar el problema (¿es un bug de implementación o un problema del diseño/caso en sí?; en este último caso, seguir el mecanismo de modificación/retroceso). Después de completar todos los pasos, ejecutar el conjunto de casos de regresión (T-R).
• Ante cualquier inconsistencia con el documento de diseño, detenerse: primero actualizar 02-diseno.md (incluyendo el registro de cambios), luego revisar sincrónicamente 03-implementacion.md y 04-pruebas.md (los casos cambian con el plan), y luego continuar. Nunca desviarse del plan mientras se implementa.
• Los vacíos de diseño descubiertos durante la implementación, nuevas restricciones, cambios de API, etc., se registran todos en el bloque "Registro de cambios de diseño" de 02-diseno.md, manteniendo el documento de diseño actualizado.
• Cada cambio de fase y cada hito importante deben actualizarse en 00-estado-tarea.md y docs/design/README.md.

Cambios durante la implementación: Mecanismo de modificación vs. Mecanismo de retroceso

El flujo de trabajo, nominalmente, es discusión → diseño → planificación de implementación → implementación, pero encontrar desviaciones entre el plan y la realidad durante la implementación es normal y esperado, no una anomalía — por muy completo que sea el diseño, no puede prever el 100% de los detalles de implementación.

Las desviaciones se dividen en dos categorías, de naturaleza completamente diferente, que deben distinguirse estrictamente y tratarse con sus respectivos procesos:

	Modificación	Retroceso
Esencia	El plan es correcto en general, pero tiene huecos/omisiones que hay que rellenar	Esta parte del plan está fundamentalmente equivocada y hay que empezar de cero
Plan principal	No se toca	Se derriba
Productos ya completados	No se invalidan	Se invalidan parcialmente
Frecuencia	Normal	Excepcional
Escenario típico	Campo omitido, rama omitida, valor de diccionario omitido, nuevo punto de requisito no considerado	Dirección equivocada, suposición central no se cumple, no se ajusta al negocio real

Primero determinar la categoría (la responsabilidad de la determinación se explica en cada mecanismo), luego procesar según el flujo correspondiente. Si hay duda al determinar, tender a tratarlo primero como "modificación" y confirmarlo con el usuario; solo cuando el error sea claramente fundamental se debe recurrir al "retroceso".

Mecanismo de modificación (normal, ligero, incremental)

Tres condiciones para la determinación (deben cumplirse todas para ser modificación):

• La dirección del plan principal es correcta
• No es necesario invalidar productos ya completados
• Solo es complemento/ajuste (añadir campo, rama, valor de diccionario, nuevo punto de requisito omitido, etc.)

Proceso (orden estricto, no invertible):

1. Detener la implementación actual
2. Primero actualizar el documento de diseño: añadir contenido en el bloque correspondiente del diseño y añadir una línea en el registro de cambios de diseño
3. Esperar la confirmación del usuario sobre esta modificación (no se puede decidir ni implementar por sí mismo)
4. Después de la confirmación del usuario, revisar sincrónicamente el documento de implementación
5. Continuar con la implementación

Principio clave: primero actualizar el diseño, luego implementar; el orden no puede invertirse — está prohibido "implementar primero y luego actualizar el documento de diseño", ya que eso degradaría el diseño a un registro posterior en lugar de la fuente de verdad. Incluso si solo se añade un campo, se debe seguir este proceso.

Mecanismo de retroceso (excepcional, pesado, de reinicio)

Tres condiciones para la determinación (deben cumplirse todas para ser retroceso):

• La dirección del plan principal tiene problemas
• Es necesario invalidar productos ya completados
• Es necesario volver a discutir/diseñar

Responsabilidad de la determinación: La decisión final de retroceso recae en el usuario. Cuando la IA encuentra un problema aparentemente fundamental, solo puede sugerir un posible retroceso y explicar las razones; el usuario decide finalmente si se retrocede. La IA no puede determinar el retroceso por sí misma.

Proceso:

1. Detener la implementación actual
2. La IA sugiere un posible retroceso, explicando las razones (qué parte de la dirección está equivocada, por qué no se sostiene)
3. Esperar la decisión final del usuario sobre si retroceder
4. Si el usuario confirma el retroceso, registrar una línea en 00-estado-tarea.md: desde la fase X se retrocede a la fase Y, motivo, qué productos se invalidan
5. Volver a la fase de discusión/diseño para realinear
6. El nuevo plan generado se consolida según el proceso original: nuevas preguntas van a la lista de preguntas pendientes de 01-comunicacion.md; cambios de plan van a 02-diseno.md con registro de cambios
7. Revisar sincrónicamente 03-implementacion.md

Reglas de hierro comunes a ambos mecanismos

1. Los cambios de plan siempre modifican el documento de diseño, nunca directamente el documento de implementación
2. Primero actualizar el diseño, luego implementar; el orden no puede invertirse (no se hace primero y se documenta después)
3. Cualquier cambio debe dejar huella en el documento de estado de la tarea (modificación → registro de cambios de diseño; retroceso → registro adicional de retroceso)
4. La confirmación del usuario es un punto de control obligatorio para cualquier cambio (modificación → necesita confirmación del complemento del plan; retroceso → necesita confirmación de la propia determinación)

Mentalidad: las desviaciones no son temibles; lo temible es continuar a pesar de la desviación o desviarse silenciosamente del plan. Hacer que la "modificación" sea ligera y de baja fricción (es normal que fluya), y que el "retroceso" sea prudente (el usuario debe decidir el reinicio), con ambos estandarizados y con rastro, minimiza el coste del retrabajo.

Normas de marcado de pasos en el documento de implementación

Los pasos de implementación se dividen en dos niveles: pasos grandes y pasos pequeños, ambos con su propia marca de finalización independiente. Los pasos grandes se organizan con títulos y contadores de progreso; los pasos pequeños usan casillas de verificación de cuatro estados.

Marcas de cuatro estados:

- [ ]  No iniciado
- [~] En progreso
- [x] Completado
- [!] Bloqueado (indicar motivo después)

Ejemplo de organización:

### 1. Capa de base de datos ✅ 1/3
- [x] 1.1 Crear tabla users (incluyendo script de migración)
- [~] 1.2 Crear índices
- [ ] 1.3 Escribir datos semilla

### 2. Capa de API ⬜ 0/2
- [ ] 2.1 Implementar POST /api/users
- [ ] 2.2 Integrar middleware de autenticación

Símbolos de estado de paso grande:

• ⬜ No iniciado (0/N completado)
• 🌗 En progreso (parcialmente completado)
• ✅ Completado completamente (N/N)

El formato del contador de progreso es uniforme número completado/total, colocado al final del título del paso grande. Esto permite ver tanto el progreso general como localizar exactamente en qué paso pequeño está bloqueado.

Tratamiento especial para proyectos backend

Si el proyecto actual es puramente backend (sin código frontend, o backend separado en su propio repositorio):

• El documento de diseño y el de implementación solo contienen contenido del backend, sin involucrar la implementación del frontend.
• Cualquier nueva API o cambio en una API existente (URL, método, parámetros de entrada/salida, códigos de error, requisitos de autenticación, etc.) debe tener un bloque dedicado "Lista de cambios de API" en 02-diseno.md.
• El formato de la lista de API debe permitir que los desarrolladores de frontend la usen directamente para integración. Se sugieren los siguientes campos: ruta de la API, método de solicitud, ejemplo de cuerpo de solicitud, ejemplo de respuesta exitosa, tabla de códigos de error, requisitos de autenticación, notas.
• Esta lista de API es un entregable para el frontend; debe ser autoconsistente y legible de forma independiente.
• La lista de API debe llegar a conclusiones determinadas en la fase de diseño; está prohibido posponer la decisión a la fase de implementación. Cualquier hecho que dependa del código existente para decidir (como "¿esta API es nueva o existente?", "¿la ruta se mantiene o cambia?", "¿los parámetros de entrada se alinean con alguna estructura existente?") debe ser confirmado leyendo el código existente durante la fase de diseño y escribiendo la conclusión en la lista de API. La restricción de "solo discutir, no escribir código" en la fase de diseño se aplica al código de negocio — leer código existente para confirmar la forma de una API es investigación de diseño, no implementación, y no viola la restricción. El documento de diseño no debe contener frases vagas como "depende del código existente", "confirmar en la fase de implementación", ni etiquetas como [confirmar en implementación] que legitimen la incertidumbre. La lista de API debe ser completamente determinada cuando se entrega al frontend; de lo contrario, el frontend no puede integrarse.

Criterios de aceptación y pruebas (tres niveles de responsabilidad)

Las pruebas no se improvisan en la fase de implementación; son un sistema que abarca desde el diseño hasta la implementación. Las responsabilidades de los tres niveles están estrictamente separadas:

Nivel	Soporte	Contenido	Naturaleza	Fase de producción
Regla	02-diseno.md	Criterios de aceptación abstractos	"¿Hasta qué punto se satisface el requisito?"	Diseño
Instancia	04-pruebas.md	Casos de prueba concretos	"¿Con qué entrada, qué salida se espera?"	Planificación de implementación
Acción	03-implementacion.md	Pasos + referencia a casos	"¿Qué acción hacer, contra qué caso verificar?"	Planificación de implementación

¿Por qué esta separación?: Los criterios de aceptación son el límite del requisito (pertenecen al diseño), los casos son la instanciación del límite, y la implementación es la acción de aterrizaje. Separados en tres niveles, si cambia la regla se busca en el diseño, si cambia el caso se busca en el documento de pruebas, si cambia la acción se busca en la implementación — cada uno tiene su fuente de verdad, sin contaminación mutua.

Clasificación y numeración de casos de prueba:

Prefijo	Tipo	Uso
T-F-	Caso funcional	Flujo positivo
T-EX-	Caso de excepción	Flujo inverso, límites, ramas de error
T-R-	Caso de regresión	Rutas críticas que deben probarse después de modificación/retroceso (seleccionados de F/EX para evitar que cambiar A rompa B)
T-API-	Caso de API	Correspondiente a cada API en la "Lista de cambios de API" del diseño

Todas las tareas generan obligatoriamente 04-pruebas.md: Este skill está orientado a tareas de tamaño medio a grande; los requisitos pequeños no activan el skill, por lo que no se realiza juicio de complejidad — una vez que la tarea entra en la fase de planificación de implementación, el documento de pruebas es obligatorio.

Relación modificación/retroceso con las pruebas: Después de aplicar el mecanismo de modificación o retroceso, el plan cambia → los casos se actualizan (primero cambiar los criterios de aceptación en el diseño, luego los casos de prueba), y se debe volver a ejecutar al menos el conjunto de regresión (T-R) para evitar que cambios locales causen regresión global.

Modo de extensión A: División de tareas (tareas grandes con múltiples módulos)

Cuándo activarlo: Cuando una tarea grande contiene naturalmente múltiples módulos semindependientes (ej. "sistema de revisión = filtro de palabras sensibles + revisión de imágenes + panel de revisión manual") y un solo contexto no es suficiente. Se activa cuando el usuario indica explícitamente en la fase de discusión "esta es una tarea grande, divídela en submódulos". No se juzga automáticamente el tamaño de la tarea; debe ser activado explícitamente por el usuario.

Mecanismo central: La tarea padre es responsable del diseño general + división en módulos + contratos de interfaz entre módulos + orquestación. Las tareas hijas siguen cada una su propio flujo completo de 4 fases dentro de los límites de la tarea padre.

A.1 Estructura de documentos de tareas padre e hija (anidada)

Raíz del proyecto/docs/design/
├── README.md                          ← Visión global de todas las tareas
├── 01-sistema-revision/               ← Tarea padre
│   ├── 00-estado-tarea.md             ← Usar plantilla parent-task-status.md, con lista de subtareas
│   ├── 01-comunicacion.md             ← Discusión general a nivel de tarea padre
│   ├── 02-diseno.md                   ← Arquitectura general + división de módulos + contratos de interfaz entre módulos
│   ├── 03-implementacion.md           ← Solo orquestación a nivel padre (pruebas de integración, puesta en común), no escribir detalles internos de módulos
│   ├── 04-pruebas.md                  ← Solo pruebas de integración entre módulos
│   └── subtareas/
│       ├── 01-1-filtro-palabras/      ← Tarea hija (documentos completos de 4 fases, usar plantilla normal)
│       ├── 01-2-revision-imagenes/
│       └── 01-3-panel-revision-manual/
└── 02-otras-tareas/

Las tareas hijas usan la plantilla normal (task-status / communication / design / implementation / test), sin cambios. La tarea padre usa la plantilla assets/parent-task-status.md, que añade un bloque "Lista de subtareas"; el documento de diseño de la tarea padre, además de la plantilla de diseño normal, debe incluir obligatoriamente dos bloques adicionales:

• División de módulos: enumerar en qué subtareas se divide, responsabilidades y límites de cada una
• Contratos de interfaz entre módulos: acuerdos de interfaz entre subtareas (firma de interfaz, formato de datos, forma de invocación, etc.). Esto es clave para que las subtareas puedan ejecutarse en paralelo de forma independiente; debe definirse claramente en la fase de diseño

A.2 Progresión de fases de la tarea padre (estrictamente secuencial)

1. La tarea padre primero pasa por "discusión + diseño", debe producir la división de módulos + contratos de interfaz
2. Una vez que el diseño de la tarea padre es confirmado por el usuario, se pueden iniciar las tareas hijas
3. Al iniciar las tareas hijas, ordenarlas según las dependencias: la fase de diseño de la tarea padre debe aclarar las dependencias entre subtareas (ej. "el panel de revisión manual depende de la API del filtro de palabras sensibles"), la subtarea de la que se depende debe completarse primero antes de que la dependiente pueda iniciarse
4. Cada tarea hija sigue su propio flujo completo de 4 fases (pueden ejecutarse en paralelo siempre que se cumplan las dependencias). Cómo hacer que múltiples subtareas se ejecuten en paralelo depende del framework del agente (generalmente a través de subtareas en segundo plano/asíncronas); para una implementación concreta, ver B.5
5. Una vez completadas todas las subtareas, la tarea padre realiza las "pruebas de integración entre módulos" para cerrar

¿Por qué la tarea padre y las hijas no pueden ejecutarse en paralelo?: El producto central de la tarea padre son los contratos de interfaz entre módulos, que son el requisito previo para que las subtareas sean independientes. Si las subtareas se inician antes de que el diseño de la tarea padre esté definido, inevitablemente entrarán en conflicto.

A.3 Las subtareas no pueden modificar los contratos de interfaz definidos por la tarea padre

Los contratos de interfaz son el consenso entre múltiples módulos; si cualquier subtarea los modifica por su cuenta, las demás subtareas quedarán fuera de control. Si una subtarea descubre un problema en los contratos de interfaz de la tarea padre:

• No puede modificar los contratos por sí misma
• Debe volver a la tarea padre y seguir el mecanismo de modificación: actualizar 02-diseno.md de la tarea padre (incluyendo registro de cambios) → esperar confirmación del usuario → notificar a todas las subtareas que dependen de esa interfaz → las subtareas afectadas revisan sincrónicamente sus propios documentos de diseño/implementación/pruebas

A.4 Límite de profundidad de anidamiento: solo un nivel

Padre → hijo, no se puede anidar más abajo (las subtareas no pueden tener sus propias subtareas). Razón: demasiados niveles de anidamiento hacen que las relaciones entre tareas sean extremadamente complejas; si una subtarea necesita dividirse aún más, normalmente significa que la granularidad de la división es incorrecta — esa subtarea debería planificarse como una tarea padre independiente, no incluirse en una estructura multinivel existente.

A.5 Uso de plantillas para la tarea padre

• Documento de estado de la tarea padre: usar assets/parent-task-status.md (no usar la plantilla normal task-status)
• Otros documentos de la tarea padre (comunicación/diseño/implementación/pruebas): usar la plantilla normal, pero el documento de diseño debe incluir obligatoriamente los dos bloques adicionales descritos en A.1
• Todos los documentos de las subtareas: usar la plantilla normal, sin cambios

Modo de extensión B: Implementación con dos agentes (segmentación de implementación)

Cuándo activarlo: Cuando, dentro de una sola tarea, la combinación de las fases de implementación y pruebas provoca que el contexto sea demasiado largo. Se activa cuando el usuario indica explícitamente al inicio de la fase de implementación "usar modo de dos agentes para la implementación". No se juzga automáticamente; debe ser activado explícitamente por el usuario.

Mecanismo central: La fase de implementación se divide internamente en dos etapas secuenciales — agente de implementación (escribe código según 03-implementacion.md) + agente de pruebas (verifica según 04-pruebas.md). Ambos son agentes físicamente independientes (dos contextos independientes), que se comunican a través del documento de estado de la tarea. El valor central de B es el aislamiento de contextos: el agente de implementación no carga el contexto de las pruebas, y el agente de pruebas no carga los detalles de implementación.

B.1 Límites de responsabilidad entre implementación y pruebas

• Agente de implementación: solo ejecuta los pasos de 03-implementacion.md (escribe código). Al completar, no ejecuta las pruebas él mismo, sino que declara en el bloque "Estado de segmentación de implementación" de 00-estado-tarea.md "implementación completada, versión X, lista para pruebas"
• Agente de pruebas: verifica basándose en el 03-implementacion.md y 04-pruebas.md más recientes. Su responsabilidad se limita estrictamente a "ejecutar casos, determinar fallos, informar"; no es responsable de corregir código (incluso si encuentra un bug de implementación, no lo corrige él mismo)

B.2 Manejo cuando el agente de pruebas encuentra un fallo

Cuando el agente de pruebas ejecuta un caso y falla, determina inicialmente la causa raíz del fallo (el agente de pruebas ve el comportamiento real y tiene la mayor ventaja informativa para hacer una determinación inicial):

• Determina que es un bug de implementación (el código está mal escrito, el diseño es correcto) → informar al agente de implementación, que lo corrige. Después de la corrección, debe volver al agente de pruebas para una nueva prueba de ese caso; solo si pasa se puede continuar al siguiente paso (el agente de implementación no puede declarar unilateralmente que el fallo está cerrado)
• Determina que es un bug de diseño (el código sigue el diseño, pero el diseño en sí tiene problemas) → no puede modificar el diseño por su cuenta, activar el mecanismo de modificación: detenerse → actualizar el diseño → esperar confirmación del usuario → cambiar implementación → cambiar pruebas → volver al agente de pruebas para una nueva prueba

Si la determinación es incorrecta, el usuario la corrige; pero "cambiar el diseño" tiene un gran impacto y debe ser decidido por el usuario.

B.3 Bloque de estado de segmentación de implementación

00-estado-tarea.md añade un bloque opcional (solo se rellena cuando el modo B está activado; no se rellena en modo normal):

## Estado de segmentación de implementación (solo para modo B, dejar vacío en modo normal)

- Etapa actual: implementación / pruebas
- Versión de implementación: (incrementar cada vez que el agente de implementación completa o corrige)
- Declaración de finalización de implementación: YYYY-MM-DD, el agente de implementación ha declarado que está listo para pruebas
- Progreso de pruebas:
  - Aprobados: T-F-01, T-F-02, ...
  - Fallos pendientes de corrección: T-EX-03 (bug de implementación, informado al agente de implementación), ...
  - Pendientes de nueva prueba: T-EX-03 (el agente de implementación lo ha corregido, esperando nueva prueba del agente de pruebas)

Tanto el agente de implementación como el de pruebas leen y escriben en este bloque; es su único punto de intercambio.

B.4 Combinación con A (A+B)

A y B son ortogonales y se pueden combinar: las tareas grandes se dividen en subtareas según A, y dentro de cada subtarea se divide en implementación + pruebas según B. No se necesita ningún mecanismo adicional para la combinación — porque las subtareas son tareas normales (A.1 ya explica que las subtareas usan la plantilla normal), por lo que las subtareas soportan B de forma natural. Modo de activación: después del diseño de la tarea padre y el inicio de las subtareas, cada subtarea decide en el momento de comenzar la fase de implementación si activar B o no.

B.5 Guía de orquestación de agentes

El modo B requiere dos agentes físicamente independientes (agente de implementación y agente de pruebas), que se comunican indirectamente a través del bloque "Estado de segmentación de implementación", sin comunicación directa entre ellos. Cómo hacer que se turnen depende del framework del agente que se utilice.

Independientemente del framework, se sigue el mismo patrón de orquestación general:

1. Un orquestador (puede ser el agente principal, un script de orquestación externo, o el propio usuario) lee el bloque "Estado de segmentación de implementación" para determinar la etapa actual
2. El orquestador inicia el agente de implementación, pasándole las rutas de los documentos de diseño e implementación, y le indica que avance según 03-implementacion.md y que actualice el bloque de estado al completar
3. Una vez finalizada la etapa de implementación, el orquestador inicia el agente de pruebas, pasándole la ruta del documento de pruebas, y le indica que ejecute los casos según 04-pruebas.md y que escriba los resultados (incluyendo la determinación de fallos) en el bloque de estado
4. El orquestador, basándose en los resultados de las pruebas en el bloque de estado, decide el siguiente paso: si es un bug de implementación, volver al agente de implementación para corregir y volver a probar; si es un bug de diseño, detenerse e informar al usuario para que siga el mecanismo de modificación; si todo pasa, cerrar

Puntos clave generales:

• El agente de implementación y el de pruebas construyen sus contextos de forma independiente, sin contaminación mutua — este es el núcleo del "aislamiento de contexto" del modo B
• Los dos agentes no se perciben directamente entre sí, solo se comunican indirectamente a través del documento compartido "Estado de segmentación de implementación"
• El orquestador solo hace "leer estado → determinar → asignar", sin participar en la implementación o las pruebas en sí

Referencia de implementación para clientes específicos: Las capacidades de subagentes / tareas en segundo plano / ventanas múltiples varían según el framework del agente. Este documento no se fija en una implementación concreta. Al usar ZCode, consultar assets/references/zcode-scheduling.md (cargar bajo demanda: solo leer cuando el modo B esté activado y se necesiten instrucciones operativas concretas). Otros clientes pueden referirse a la idea de ese archivo y adaptarla a sus propias capacidades.

Límite importante: el skill no fija una implementación de orquestación específica

El skill define el protocolo de intercambio (formato y semántica del bloque de estado de segmentación de implementación) y las responsabilidades de los roles (qué hace cada agente), pero no fija cómo se orquesta. Cualquier framework que pueda "leer archivos, iniciar subtareas, escribir archivos" puede implementar el modo B.

Principio de confirmación en las transiciones de fase

Las transiciones entre fases no son automáticas; requieren una señal explícita:

Condición de entrada	Condición cumplida
Entrar en discusión	(El skill se activa manualmente)
Discusión → Diseño	El usuario acepta explícitamente consolidar el plan, y la lista de preguntas pendientes está vacía
Diseño → Planificación de implementación	El documento de diseño está completo y ha sido aprobado por el usuario
Planificación de implementación → Implementación	El usuario solicita explícitamente comenzar
Implementación → Diseño (modificación)	Durante la implementación se encuentra un hueco en el plan, se detiene según el "mecanismo de modificación", se cambia el diseño y se espera la confirmación del usuario
Implementación → Discusión/Diseño (retroceso)	Durante la implementación se encuentra un error fundamental, la IA sugiere retroceso, el usuario decide después

Si no se está seguro de si se debe hacer la transición, por defecto permanecer en la fase actual y continuar discutiendo, preguntando activamente al usuario. No se debe asumir por el usuario que "el plan ya es suficientemente bueno, se puede empezar a escribir".

Uso de plantillas

Al crear un nuevo documento, leer la plantilla correspondiente del directorio assets/:

• assets/readme.md → docs/design/README.md (visión global de todas las tareas)
• assets/task-status.md → 00-estado-tarea.md (tarea normal / subtarea)
• assets/parent-task-status.md → 00-estado-tarea.md (solo para tarea padre, cuando el modo A está activado)
• assets/communication.md → 01-comunicacion.md
• assets/design.md → 02-diseno.md (incluye bloque de criterios de aceptación; la tarea padre debe incluir adicionalmente los bloques de división de módulos + contratos de interfaz)
• assets/implementation.md → 03-implementacion.md
• assets/test.md → 04-pruebas.md (generado en la fase de planificación de implementación)

Leer la plantilla, rellenar con el contenido real y escribir en la carpeta de la tarea. No inventar estructuras de documento.

Iteración del skill y documentos de tareas antiguas

El skill evolucionará continuamente, y las plantillas y normas se actualizarán, pero los documentos de tareas antiguas que ya están en uso no se migrarán automáticamente a las nuevas normas. Esto es intencionado — el objetivo es proteger la memoria existente del usuario sobre la estructura de los documentos y mantener la estabilidad del mecanismo de memoria entre contextos. La estructura de los documentos es el ancla de memoria que permite al usuario localizarse rápidamente después de cambiar de contexto; el ancla no debe deformarse con frecuencia debido a actualizaciones del skill.

Principios de manejo:

• No migrar activamente: La IA no escanea tareas antiguas por su cuenta ni las alinea con las nuevas normas, incluso si encuentra diferencias entre el formato antiguo y las nuevas normas (ej. el documento antiguo tiene un bloque "Registro de retrocesos" y la nueva norma requiere "Registro de cambios"). Como mucho, puede mencionar la diferencia en una nota durante la implementación o en el diálogo, pero no actuar por su cuenta.
• Migrar solo bajo instrucción explícita del usuario: Actuar solo cuando el usuario solicite activamente "alinear los documentos de la tarea X con las normas actuales del skill" o "migrar la tarea X al nuevo formato". La IA no decide por el usuario si una tarea antigua debe migrarse.
• Priorizar la complementación incremental: La migración por defecto solo complementa/modifica las partes que no cumplen con las nuevas normas, conservando la estructura general y el contenido del documento original, sin reescribirlo por completo. De esta manera, cuando el usuario vuelva a un contexto diferente, no necesitará releer y re-comprender todo el documento — la estructura no ha cambiado, el ancla de memoria permanece.
• Cuando el usuario solicite explícitamente una reescritura, se debe hacer una copia de seguridad del archivo original antes de generar el nuevo archivo:
  • No sobrescribir el archivo original directamente
  • El archivo de copia de seguridad debe incluir la fecha o un sufijo de versión, ej. 00-estado-tarea.md.bak.20260617
  • El nuevo archivo conserva el nombre original, conteniendo el contenido reescrito
  • El archivo original es el ancla de memoria histórica del usuario; incluso si se reescribe, se debe conservar la versión original para comparación o retroceso
• Antes de migrar/reescribir, explicar el alcance: Antes de actuar, informar al usuario qué puntos se modificarán (incremental) o qué archivos se reescribirán (completo); después de terminar, describir brevemente lo que se ha cambiado, manteniendo la expectativa.

Antipatrones (a evitar)

• ❌ Empezar a escribir código de negocio en la fase de discusión — invertir el orden.
• ❌ Escribir cambios de plan directamente en el documento de implementación sin actualizar el diseño — destruir la única fuente de verdad.
• ❌ En una nueva conversación, no leer los documentos de estado y el README, obligando al usuario a repetir el progreso — desperdiciar contexto.
• ❌ Al encontrar una desviación durante la implementación, modificar la implementación silenciosamente sin actualizar el diseño — el documento de diseño se vuelve inexacto gradualmente.
• ❌ En un proyecto backend, escribir detalles de implementación del frontend, o no reflejar los cambios de API en la lista — el frontend no tiene base para la integración.
• ❌ Avanzar automáticamente de fase sin una señal explícita — privar al usuario de su poder de decisión.
• ❌ Durante la implementación, encontrar un hueco en el plan (campo/rama/valor de diccionario omitido, etc.) y modificar directamente el documento de implementación sin actualizar el diseño ni esperar la confirmación del usuario — se debe seguir el "mecanismo de modificación": detenerse → cambiar el diseño primero → esperar confirmación → cambiar implementación → continuar.
• ❌ Durante la implementación, encontrar un error fundamental y forzar la modificación del documento de implementación, o que la IA decida el retroceso por sí misma — se debe seguir el "mecanismo de retroceso": la IA solo puede sugerir, el usuario decide, registrar el retroceso y volver a discusión/diseño para realinear.
• ❌ Marcar un paso grande como completado cuando aún faltan pasos pequeños — ambos niveles deben tener marcas independientes.
• ❌ La discusión se dispersa sin poder cerrarse, las preguntas pendientes se ven sumergidas por nuevos temas — forzar la convergencia mediante la lista de preguntas pendientes.
• ❌ En la lista de API, aparecen frases vagas como "depende del código existente", "confirmar en la fase de implementación", o etiquetas como [confirmar en implementación] que legitimen la incertidumbre — los hechos que dependen del código existente deben confirmarse leyendo el código durante la fase de diseño; la lista de API debe ser completamente determinada al entregarse, de lo contrario el frontend no puede integrarse.
• ❌ Migrar tareas antiguas o alinearlas con nuevas normas por iniciativa propia después de una iteración del skill — destruir el ancla de memoria del usuario. Migrar solo bajo instrucción explícita del usuario; por defecto, complementación incremental, no reescritura completa; si el usuario solicita una reescritura, se debe hacer una copia de seguridad del archivo original antes de generar el nuevo.
• ❌ El documento de diseño solo describe el plan sin incluir criterios de aceptación — los criterios de aceptación son el límite del requisito; sin ellos, no hay una definición objetiva de "terminado", y la aceptación durante la implementación se basa en sensaciones.
• ❌ En el documento de implementación, escribir acciones genéricas como "cubrir con pruebas unitarias XXX" sin hacer referencia a números de caso concretos — las acciones de prueba deben apuntar a casos específicos en 04-pruebas.md (ej. "verificar según T-EX-03"), de lo contrario no está claro qué se prueba ni cuál es el resultado esperado.
• ❌ Después de aplicar el mecanismo de modificación/retroceso, no volver a ejecutar los casos de regresión (T-R) — los cambios locales pueden causar regresión global; es obligatorio volver a probar las rutas críticas.
• ❌ En el modo A, iniciar las subtareas antes de que el diseño de la tarea padre esté definido (división de módulos o contratos de interfaz no producidos) — las subtareas inevitablemente entrarán en conflicto. El diseño de la tarea padre debe ser confirmado primero por el usuario.
• ❌ En el modo A, una subtarea modifica los contratos de interfaz definidos por la tarea padre por su cuenta — los contratos de interfaz son el consenso entre múltiples módulos; se debe volver a la tarea padre y seguir el mecanismo de modificación, notificando a todas las subtareas que dependen de esa interfaz.
• ❌ En el modo A, una subtarea anida otra subtarea (más de un nivel) — normalmente significa que la granularidad de la división es incorrecta; esa subtarea debería planificarse como una tarea padre independiente.
• ❌ En el modo A, la tarea padre no ordena las subtareas según sus dependencias y las lanza todas en paralelo — la dependiente se bloqueará hasta que la dependida termine; las dependencias deben definirse claramente en la fase de diseño de la tarea padre.
• ❌ En el modo B, el agente de pruebas corrige los bugs de implementación por sí mismo — las responsabilidades deben estar separadas: las pruebas solo detectan fallos, la corrección vuelve al agente de implementación; y después de la corrección, el agente de pruebas debe volver a probar; el agente de implementación no puede declarar unilateralmente el cierre.
• ❌ En el modo B, usar el mismo agente de forma secuencial para los roles de "implementación" y "pruebas" — el valor central de B es el aislamiento de contextos; deben ser dos agentes físicamente independientes, de lo contrario no hay aislamiento y B no está activado.
• ❌ En el modo B, si el agente de pruebas encuentra un bug de diseño, lo corrige por su cuenta — los cambios de diseño tienen un gran impacto; se debe activar el mecanismo de modificación y contar con la confirmación del usuario; el agente de pruebas solo puede determinar inicialmente e informar.