Usar IA para escribir una función ya no resulta especialmente novedoso. Lo difícil empieza un nivel más arriba: darle contexto suficiente para que entienda un repositorio, convertir una intención de producto en cambios coherentes, verificar esos cambios y dejar el proyecto mejor preparado para la siguiente tarea.
PuzzleHub nos da un campo de pruebas especialmente exigente. Hay muchas experiencias parecidas en la superficie, pero con reglas, algoritmos y problemas de UX diferentes. La IA puede producir código a enorme velocidad; precisamente por eso necesitamos un sistema que evite confundir volumen con progreso.
La velocidad solo se convierte en progreso cuando el ciclo puede corregirse.
De pedir código a delegar trabajo
La diferencia aparece cuando una tarea deja de ser «escribe esta función» y pasa a ser «resuelve este problema dentro de este producto». El agente tiene que inspeccionar código existente, encontrar patrones, decidir qué reutilizar, implementar y comprobar que el cambio no rompe otras áreas.
Eso exige mejores instrucciones. Una tarea útil explica el resultado esperado, pero también las fronteras: qué no se debe cambiar, qué componentes sirven de referencia, qué comportamiento hay que conservar y cómo sabremos que la implementación es aceptable.
La IA trabaja mejor cuando el proyecto puede explicar por sí mismo cómo quiere ser modificado.
Documentación que también es infraestructura
Arquitectura, convenciones y decisiones ya no son documentación «para algún día». Se convierten en contexto operativo. Si un agente debe redescubrir en cada sesión por qué existe una capa, cómo se estructura un juego o qué estándar visual seguimos, pagamos una y otra vez el mismo coste.
Por eso estamos acercando tareas, especificaciones y documentación al repositorio y a nuestro sistema de trabajo. El objetivo no es escribir más documentos, sino conservar las decisiones que reducen ambigüedad futura.
- un objetivo observable, no solo una idea;
- contexto suficiente para encontrar la zona correcta del repositorio;
- restricciones explícitas y precedentes que respetar;
- criterios de validación técnicos y de producto;
- un alcance que permita revisar el diff con sentido.
Git como memoria verificable
Ramas, commits y pull requests encajan especialmente bien con este modelo. Cada agente puede producir una unidad de cambio delimitada. El historial permite comparar enfoques, revisar qué se tocó y volver atrás si una propuesta resulta peor que el estado anterior.
Git aporta algo que una conversación no ofrece: evidencia concreta. Podemos discutir una intención durante mucho tiempo, pero al final el diff dice qué ocurrió realmente.
Delegar y enrutar no son lo mismo
A medida que probamos más herramientas hemos necesitado distinguir dos operaciones. Delegar significa repartir una parte del trabajo dentro del flujo que ya estamos utilizando. Enrutar significa enviar la tarea a otro agente o herramienta externa, con sus propias capacidades y limitaciones.
La diferencia parece semántica hasta que aparecen permisos, entornos aislados, acceso al repositorio o visibilidad del proceso. Un agente externo puede ser excelente resolviendo una tarea y, aun así, resultar poco útil si no puede recibir el contexto necesario o devolver cambios de forma revisable.
La IA acelera también los errores
En puzzles esto se ve con claridad. Un generador puede producir cientos de tableros visualmente plausibles y estar fundamentalmente mal: soluciones múltiples, dificultad artificial, patrones repetitivos o casos límite que bloquean el juego.
Cuanto más rápida es la implementación, más importante se vuelve construir mecanismos independientes que puedan contradecirla. Solvers, validadores, tests, límites de tiempo y comprobaciones estructurales son el equivalente técnico de preguntar «¿cómo sabes que esto funciona?».
El criterio de producto sigue siendo el cuello de botella
Hay decisiones que un test no captura. Un tablero puede ser correcto y aburrido. Una interfaz puede cumplir todos los requisitos y sentirse torpe. Un catálogo puede contener setenta juegos y seguir sin ayudar a elegir ninguno.
Ahí la IA sirve para explorar más alternativas y llegar antes a algo evaluable, pero la decisión final sigue necesitando criterio. De hecho, la velocidad hace ese criterio más importante: ahora podemos producir diez variantes donde antes hacíamos una, así que elegir bien pesa más que generar.
Especialización: investigar, construir, revisar
No esperamos que un único agente sea siempre la mejor opción. Estamos experimentando con roles diferentes: investigación para entender algoritmos o competencia; implementación para modificar el repositorio; revisión para buscar fallos y contradicciones; y agentes externos para tareas donde aportan capacidades específicas.
La especialización también reduce un riesgo conocido: que quien ha construido una solución sea el único que la evalúa. Una segunda mirada, humana o automática, puede partir de una pregunta distinta y encontrar problemas que el implementador ya ha normalizado.
Lo que no ha funcionado también cuenta
Permisos insuficientes, sistemas de archivos de solo lectura, herramientas externas que no llegan a ejecutarse, falta de visibilidad sobre un subagente o contextos demasiado grandes son problemas reales. No son anécdotas separadas del desarrollo asistido por IA: son parte de su infraestructura.
Documentarlos importa porque la imagen idealizada —un enjambre de agentes trabajando solo— oculta el trabajo más interesante: diseñar un sistema donde esos agentes puedan colaborar de manera predecible.
Qué queremos aprender con PuzzleHub
No buscamos demostrar que «la IA puede hacer una web». Eso sería una conclusión demasiado pequeña. Queremos descubrir qué organización permite mantener un producto cada vez mayor sin que la velocidad destruya coherencia, y qué tareas merece la pena automatizar por completo frente a cuáles necesitan una conversación continua con una persona.
El resultado visible son juegos, categorías, rediseños y nuevas funciones. Debajo hay otro producto en construcción: nuestro propio flujo de ingeniería. Cada tarea nos enseña algo sobre documentación, contexto, autonomía, revisión o límites.
Por eso lo contamos en el Journal. Devlog, en este caso, no consiste solo en enseñar lo que sale bien. Consiste en dejar registro de cómo cambia nuestra manera de construir mientras construimos.