🐘🐟 Patrón de Desarrollo Elefante y Pez Dorado (Elephant & Goldfish Pattern)
📌 Resumen
- 🐘 Elefante (Coordinador, es decir, tú): Tiene una memoria global. Se encarga de comunicar, escribir las especificaciones CUJ, asignar tareas y revisar los resultados. No escribe código ni ejecuta pruebas.
- 🐟 Pez Dorado (Codificador / Probador / Revisor): Subagente sin estado, sin carga histórica. Solo trabaja según la CUJ y se destruye al terminar, evitando la contaminación del contexto.
🚦 Paso 0: Decide si esta tarea debe seguir este proceso
Esta es la primera decisión, no la omitas.
| Tipo de tarea | ¿Sigue este proceso? |
|---|---|
| Nueva funcionalidad o módulo | ✅ |
| Modificar el comportamiento de una función existente | ✅ |
| Refactorización que implica cambios en interfaces externas | ✅ |
| Corrección de errores que requiere cambios en la lógica | ✅ |
| Actualización pura de documentación (README, comentarios) | ❌ |
| Formateo de código / lint | ❌ |
| Actualización de versión de dependencias (sin cambios de comportamiento) | ❌ |
| Ajustes de configuración | ❌ |
| Hotfix urgente (error crítico ya en producción) | ❌ Reparar directamente, luego debe agregar validación del Probador |
Por defecto si no estás seguro: cambios ≤ 10 líneas y que no alteren ningún comportamiento externo observable → no seguir el proceso.
❌ Cuando no sea aplicable, actúa según las reglas existentes del proyecto, no menciones este Skill y no escribas CUJs solo para seguir el proceso.
🎯 Principios fundamentales
- Estándar del Pez Dorado: Un subagente completamente nuevo (Pez Dorado), basándose únicamente en el documento CUJ, debe poder completar de forma independiente el flujo completo: explicación → implementación → pruebas. Si no se logra, la especificación no es lo suficientemente buena, no es que la IA no sea lo suficientemente inteligente.
- Separación estricta de roles: Quien escribe el código (Codificador) no puede corregir su propio examen (Probador / Revisor).
- Especificación + Pruebas: La CUJ define "qué se quiere", las pruebas demuestran "se ha obtenido". Sin ambos, la CUJ se degrada a un documento para humanos, no a un contrato ejecutable para el Pez Dorado.
- Confía en el script, no solo en el Markdown: Usa
scripts/validate_cuj.pypara una verificación objetiva, no confíes en que "se siente bien".
🚀 Proceso
Paso 1: Carga la documentación de referencia según sea necesario
No lo leas todo de una vez. Carga según la necesidad real del momento. Este es el punto clave de la revelación progresiva:
| ¿Cuándo leer? | ¿Qué leer? |
|---|---|
| Antes de desplegar un Pez Dorado (obligatorio) | references/dispatch-prompts.md |
| No estás seguro de si un rol puede hacer algo | references/role-separation.md |
| No estás seguro del nivel de detalle de la CUJ o la validación falla constantemente | references/cuj-workflow.md |
| Cuando empieces a escribir una CUJ | assets/cuj-template.md (formato)assets/cuj-001-user-login.md (estándar de calidad) |
| La herramienta que usas no tiene mecanismo de subagentes | references/role-separation.md (tabla de equivalencias entre herramientas) |
Paso 2: Escribe la CUJ
- Sigue el formato de la plantilla, guarda en el directorio
cuj/del proyecto, con nombrecuj-XXX-descripción-breve.md - El
iden el frontmatter debe coincidir con el prefijo del nombre del archivo (ver Gotchas) - Si hay ambigüedad en los requisitos, acláralos antes de escribir — el mecanismo de aclaración está en el paso 2 de
cuj-workflow.md(fuera del alcance de este Skill)
Paso 3: Valida la CUJ (verificación objetiva)
python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/
- Código de salida 0 para pasar al Paso 4
- Si no es 0 → corrige la CUJ según el mensaje de error, vuelve a ejecutar hasta que pase, no lo saltes
- Después de pasar, aún debes hacerte la pregunta del Pez Dorado — el script verifica la estructura, esta pregunta verifica la usabilidad
Paso 4: Despliega el Pez Dorado y converge
Antes de desplegar, lee obligatoriamente la lista "❌ No incluir" en references/dispatch-prompts.md. La separación de roles se rompe más a menudo en el momento del despliegue.
Ejecuta en orden, no en paralelo, no combines roles:
- 4a. Desplegar Codificador — Dale solo la ruta de la CUJ y las rutas de los archivos a modificar, sin historial de conversación
- 4b. Desplegar Probador (subagente independiente) — Dale solo los criterios de aceptación y los casos de prueba de la CUJ, no le des la explicación de implementación ni el resumen de resultados del Codificador
- 4c. Si la prueba falla — Pasa el mensaje de error a un nuevo Pez Dorado Codificador para corregirlo, luego vuelve a 4b para volver a probar. No dejes que el mismo Codificador lo repare repetidamente, eso equivale a que se corrija su propio examen
- 4d. Desplegar Revisor (subagente independiente, opcional) — Dale solo las rutas del código y los criterios de aceptación, no le des los resultados del Probador
- 4e. Coordinador consolida — Actualiza el
statusde la CUJ, informa al usuario los resultados reales
Condición de convergencia: Cada criterio de aceptación tiene una prueba correspondiente y todas pasan.
Límite de fallos: Si el bucle 4b ↔ 4c de una misma CUJ se ejecuta 3 veces sin converger → deja de reparar a ciegas,
vuelve al Paso 2 para revisar si la CUJ tiene problemas (especificaciones contradictorias, criterios de aceptación no comprobables, requisitos previos faltantes).
⚠️ Gotchas
Hechos del entorno que no conoces y te pueden hacer tropezar:
- El
iddebe coincidir con el prefijo del nombre del archivo —id: cuj-001debe corresponder acuj-001-*.md, si no coincide se considera fallo directo - El modo directorio solo escanea
cuj-*.md— Si el nombre está mal escrito (por ejemplocju-001-x.md), se listará como "Omitido" en lugar de "Fallo", al revisar la salida, presta atención a la lista de omitidos - El umbral de contenido de bloque varía según el idioma — 10 caracteres para chino/japonés/coreano, 30 caracteres para alfabetos occidentales, se evalúa bloque por bloque.
Puedes sobrescribir con
--min-section-chars N - El script de validación requiere Python 3.12+, incluso si el proyecto en sí no es un proyecto Python
- "Omitido" no es igual a "Pasado" — Mira el número de "Pasados" en la línea de resumen, no solo si hay un ✅ impreso
- El script solo valida la estructura, no la semántica — "It should work correctly" es estructuralmente igual a un criterio de aceptación concreto, puede pasar el script. El script es el suelo, el punto de control de la prueba del Pez Dorado es el techo
🛑 Anti-Racionalización y Banderas Rojas
Ámbito de aplicación: Las siguientes reglas solo son válidas cuando se sigue este proceso para desarrollo de funcionalidades, no son reglas fijas en todo momento. Las comprobaciones de operación, validación previa al despliegue y hotfixes urgentes se rigen por las reglas existentes del proyecto. Si al importar hay conflicto con las normas existentes del proyecto, resuelve por ámbito, no sobrescribas mutuamente.
- ❌ Absolutamente prohibido que el Coordinador escriba personalmente cambios de más de 10 líneas, o ejecute comandos de prueba.
- ❌ Absolutamente prohibido copiar el contexto de implementación del Codificador al Probador. El Probador debe probar de forma independiente según los criterios de aceptación de la CUJ en un contexto limpio.
- ❌ Absolutamente prohibido asumir que la prueba pasa solo porque el script de validación imprime ✅ — verifica el número de "Pasados" en la línea de resumen.
- ❌ Absolutamente prohibido modificar la prueba o relajar los criterios de aceptación para que la prueba pase. El fallo de la prueba es información valiosa.
Para más excusas comunes y sus refutaciones, consulta la tabla de Anti-Racionalización en references/role-separation.md.
🔲 Límites de responsabilidad
Este Skill solo se encarga del mecanismo Elefante y Pez Dorado en sí, no cubre todo el ciclo de vida del desarrollo:
| Fase | Este Skill | Descripción |
|---|---|---|
| ① Definir requisitos | Fuera del alcance | Responsabilidad humana |
| ② Aclarar requisitos | Fuera del alcance (definir contrato) | Cada herramienta lo gestiona por su cuenta, ver paso 2 de cuj-workflow.md |
| ③ Generar CUJ | ✅ Núcleo | Plantilla CUJ + validate_cuj.py |
| ④ Desarrollo | ✅ Núcleo | Separación de cuatro roles + plantilla de prompt de despliegue |
| ⑤ Post-mortem | Fuera del alcance | Mecanismos nativos de cada herramienta (por ejemplo, memoria de Claude Code) |
Un Skill hace solo una cosa. La aclaración de requisitos y el aprendizaje continuo tienen skills independientes maduros que se pueden combinar, reinventar la rueda no tiene valor.
⚙️ Requisitos previos
| Elemento | Requisito |
|---|---|
scripts/validate_cuj.py, scripts/install.py | Python 3.12+ (sin dependencias de terceros) |
| Autoevaluación del Skill | pytest |
Los anteriores son requisitos de ejecución del Skill en sí, no están relacionados con la pila tecnológica del proyecto que usa este Skill.