Cómo construimos Cuatro con IA, agentes y GitHub
Cuatro no se está construyendo con un único prompt ni con una IA trabajando sola. Hoy usamos un sistema donde personas, agentes de IA, GitHub y pruebas trabajan juntos para convertir una idea en una función real, verificarla y llevarla con más orden hasta producción.
La parte importante no es que una IA pueda escribir código. Es que pueda entrar a un proyecto grande, entender sus reglas, trabajar sin romper otras áreas y dejar suficiente evidencia para que otra persona pueda revisar lo que hizo.
Cómo funciona hoy
De una idea a un cambio real
Idea
Una persona define el problema, el resultado esperado y las restricciones importantes.
Contexto
El agente recibe las reglas, la arquitectura y decisiones previas del proyecto.
Plan
Antes de cambiar código se identifica qué partes del producto deben modificarse.
Construcción
La IA ayuda a implementar cambios en la app, la web, el servidor o los datos.
Pruebas
El cambio se valida con tests automáticos y evidencia de que realmente funciona.
Pull request
GitHub reúne el cambio, su explicación, los checks y el feedback.
Revisión
Personas y herramientas automáticas detectan errores, riesgos o inconsistencias.
Decisión humana
El equipo decide si el cambio está listo para integrarse y publicarse.
Ver cómo se traduce esto técnicamente
En el repositorio, ese flujo combina varias capas y herramientas concretas:
- React Native + Expo para la aplicación móvil y Next.js para la web.
- tRPC para conectar la interfaz con lógica del servidor usando contratos tipados.
- Supabase/PostgreSQL para datos, autenticación y reglas de acceso.
- AGENTS.md, CLAUDE.md y documentación compartida para dar contexto consistente a los agentes.
- Branches y worktrees para aislar tareas concurrentes.
- Vitest, Playwright y Maestro para validar lógica, web y flujos móviles.
- GitHub Actions y pull requests para concentrar checks, evidencia y revisión.
GitHub también funciona como memoria del proyecto
Una conversación con una IA puede terminar, pero el proyecto no debería perder lo aprendido. Por eso las decisiones importantes se convierten en documentación, reglas, scripts y automatizaciones dentro del repositorio en GitHub, y herramientas como Claude Code las leen al iniciar cada sesión. Así una nueva sesión no necesita depender de que alguien recuerde exactamente lo que se habló días antes.
Ver cómo guardamos ese contexto
- AGENTS.md funciona como punto de entrada para agentes que necesitan entender las reglas generales del repositorio.
- CLAUDE.md adapta esas reglas al flujo de Claude Code.
- docs/agents-workflows/** conserva políticas y procedimientos que deben ser compartidos entre herramientas.
- .claude/** y .agents/** contienen comandos y skills especializados.
- Los PRs conservan el diff, los checks, los comentarios de review y el historial de decisiones de cada cambio.
No guardamos conversaciones privadas, tokens ni archivos sensibles como memoria del sistema. Lo que se versiona es la regla, el aprendizaje o la automatización que vale la pena reutilizar.
Un ejemplo real: agregar una función de inscripción
Una función aparentemente sencilla como permitir que alguien se inscriba a un torneo terminó tocando muchas partes del producto. Hubo que actualizar la base de datos y sus reglas de seguridad, enseñar al servidor cómo registrar o retirar jugadores, reflejar esos estados en la app móvil y la web, manejar la lista de espera y comprobar que todo funcionara de principio a fin.
Ver cómo se resolvió técnicamente
En esa feature, el trabajo técnico incluyó:
- Migraciones de PostgreSQL para ajustar el modelo de inscripción y datos relacionados.
- Políticas RLS en Supabase para controlar qué registros puede leer o modificar cada usuario.
- Procedimientos tRPC para join, withdraw y re-join, además del manejo de waitlist.
- Actualizaciones optimistas en la app para reflejar acciones inmediatamente y revertirlas si el servidor falla.
- El mismo estado de inscripción llevado a mobile y web para evitar comportamientos distintos entre plataformas.
- Fixtures y datos de prueba para reproducir escenarios como cupo lleno, retiro y reingreso.
- Playwright en web y Maestro en mobile para recorrer el flujo completo como lo haría una persona.
Lo que una sola función puede tocar
Reglas
Definir qué pasa cuando alguien entra, sale o queda en lista de espera.
Datos
Guardar correctamente la inscripción y proteger quién puede verla o modificarla.
Servidor
Aplicar esas reglas y devolver resultados claros a la interfaz.
App móvil
Mostrar acciones, estados de carga y cambios inmediatos para el jugador.
Web
Mantener el mismo comportamiento para quien usa Cuatro desde el navegador.
Integración
Conectar enlaces, datos de prueba y otras piezas que dependen de la función.
Pruebas
Recorrer el flujo completo y comprobar escenarios normales y de borde.
Revisión
Dejar evidencia en GitHub antes de integrar el cambio.
Claude y Codex dentro del sistema actual
Usamos herramientas de IA para tareas diferentes: explorar el repositorio, proponer un plan, implementar, diagnosticar fallos o revisar cambios. No las tratamos como programadores aislados. Cada agente trabaja con contexto compartido y deja su trabajo en superficies que el resto del equipo puede inspeccionar.
Ver un poco más del setup de agentes
- Las instrucciones compartidas evitan repetir reglas críticas en cada prompt.
- Los worktrees permiten que dos tareas trabajen sobre checkouts separados del mismo repositorio.
- El ownership de un PR ayuda a evitar que dos sesiones modifiquen el mismo cambio al mismo tiempo.
- Los handoffs documentan qué hizo una sesión, qué validó y qué queda pendiente.
- Los checks exact-head buscan que la evidencia corresponda exactamente al código que se está revisando.
La IA no se queda en el código
El mismo enfoque también llegó a la comunicación de Cuatro. El contenido que hemos producido para redes sociales, especialmente Instagram, se ha desarrollado con apoyo de herramientas de IA: desde investigar qué historia vale la pena contar hasta explorar el concepto, redactar el copy, estructurar carruseles y producir piezas visuales o de video.
Eso nos permite tratar marketing y producto como partes del mismo sistema. Una nueva función puede convertirse en una historia para redes usando información real del producto, capturas verificadas y las mismas reglas de marca, en lugar de empezar cada publicación desde una hoja en blanco.
Ver cómo se produce ese contenido
La capa de contenido combina investigación, generación y controles de fidelidad:
- La IA puede ayudar a investigar el tema, encontrar el ángulo, proponer el guion y reducir una idea compleja a mensajes que funcionen en un carrusel o Reel.
- Los lineamientos de marca, referencias visuales y assets viven en fuentes compartidas para que una pieza no dependa sólo de lo que recuerde una sesión.
- Las capturas reales de Cuatro son la primera fuente cuando una publicación muestra el producto; si una pantalla debe recrearse para animarla, tiene que reproducir fielmente la implementación actual.
- Para video usamos HyperFrames (framework open source para crear, previsualizar y renderizar composiciones de video basadas en HTML) y convertir esas composiciones en piezas MP4.
- El flujo de video puede combinar capturas del producto, medios generados, audio, composición y revisión antes del render final.
- Las piezas para Instagram siguen guías de formato, zonas seguras y exportación, además de una revisión humana antes de publicarse.
Usar IA para marketing no significa inventar una versión más bonita del producto. Si una pieza muestra una pantalla de Cuatro, la app real y su estado actual siguen siendo la fuente de verdad.
Cómo llegamos hasta aquí: problemas que obligaron a cambiar el proceso
El setup actual no apareció completo desde el primer día. Fue creciendo porque trabajar con IA a escala empezó a revelar problemas que no existen cuando sólo se usa un chatbot para una tarea aislada.
La evolución del workflow
Sesiones aisladas
Al principio, demasiado conocimiento podía quedarse dentro de una conversación y perderse para la siguiente.
Contexto versionado
La solución fue mover reglas y aprendizajes importantes al propio repositorio.
Trabajo en paralelo
Con más agentes aparecieron choques entre tareas, ramas y sesiones concurrentes.
Ownership y worktrees
Se introdujeron reglas para separar trabajo y reducir interferencias entre agentes.
Más automatización
Se añadieron reviews, checks y loops automáticos para encontrar problemas antes.
Nuevos cuellos de botella
Algunas automatizaciones útiles también podían generar espera o complejidad innecesaria.
Simplificación
El proceso empezó a retirar gates que ya no aportaban suficiente valor.
Estado actual
Conservamos contexto, pruebas y automatización, pero con decisiones humanas explícitas sobre qué merece seguir existiendo.
Un ejemplo de esa evolución: AI reviewing AI
Durante un tiempo experimentamos con Codex como una revisión obligatoria dentro del proceso de pull requests. Ayudó a descubrir problemas reales y generó aprendizajes que terminaron convertidos en mejores reglas y pruebas. Pero también podía añadir espera al proceso.
El 17 de septiembre de 2026 dejamos de usar Codex como requisito obligatorio para avanzar. No porque la revisión con IA no sirva, sino porque una buena infraestructura también debe poder simplificarse cuando una pieza deja de justificar su costo.
Ver qué cambió en ese proceso
- Codex llegó a formar parte de loops automatizados de revisión de pull requests.
- El sistema distinguía feedback accionable, estado del PR y sesiones que todavía estaban trabajando.
- Con el tiempo, el review obligatorio pasó a comportarse como un gate adicional de admisión.
- Ese gate se retiró en septiembre de 2026; los checks, la revisión humana y otras señales automáticas continuaron.
- La lección quedó en el repositorio: automatizar también implica medir cuándo conviene desautomatizar.
Cuando escribir código es más rápido, comprobarlo importa todavía más
- TypeScript ayuda a detectar incompatibilidades antes de ejecutar la aplicación.
- Los tests comprueban reglas y escenarios importantes de forma automática.
- Playwright recorre flujos reales de la web.
- Maestro hace lo mismo en la aplicación móvil.
- Las capturas de pantalla permiten revisar cambios visuales.
- GitHub Actions reúne estas verificaciones antes de integrar un cambio.
Ver la capa de validación con más detalle
- Type-check y lint detectan contratos rotos y problemas estructurales.
- Vitest cubre lógica enfocada y regresiones rápidas.
- Playwright ejecuta journeys reales dentro del navegador.
- Maestro automatiza flujos de la app en simulador o dispositivo.
- Los PRs con cambios de UI pueden exigir screenshots y evidencia visual vinculada al head revisado.
- GitHub Actions conecta estas verificaciones al pull request para que el resultado no dependa sólo de una revisión manual.
La IA puede acelerar mucho la escritura de código. Eso mueve el cuello de botella: ya no basta con producir cambios rápido; hay que entender bien el problema, demostrar que el cambio funciona y asegurarse de que no rompió algo que ya existía.
Qué decisiones siguen siendo humanas
Las herramientas pueden proponer, implementar y revisar, pero decidir qué construir, qué riesgo aceptar, cuándo publicar un cambio y qué experiencia queremos ofrecer sigue siendo responsabilidad del equipo. En Cuatro intentamos separar una idea clave: que una IA tenga capacidad para hacer algo no significa que automáticamente tenga autoridad para hacerlo.
Lo que hemos aprendido
- Dar buen contexto a la IA importa más que escribir un prompt espectacular.
- Los aprendizajes importantes deben quedar dentro del proyecto para poder reutilizarse.
- Trabajar en paralelo sólo ayuda cuando cada tarea tiene límites claros.
- La IA funciona mejor cuando recibe feedback rápido y verificable.
- Automatizar un proceso incorrecto sólo permite equivocarse más rápido.
- Una buena automatización también debe poder retirarse cuando deja de aportar valor.
- Mientras más rápido se construye, más importantes se vuelven las pruebas y la evidencia.
Por qué esto también forma parte de Cuatro
Cuatro es una aplicación para organizar y vivir torneos de pádel, pero también es el resultado de experimentar con una forma distinta de construir software. Queremos que cada nueva sesión aproveche lo que aprendió la anterior y que diferentes herramientas puedan colaborar sin perder el contexto del producto.
El objetivo no es eliminar a las personas del proceso. Es hacer que un equipo pequeño pueda explorar ideas, detectar errores y construir con mayor velocidad sin renunciar a la calidad. La historia del setup importa precisamente porque muestra que llegar ahí también implicó equivocarse, ajustar reglas y eliminar cosas que dejaron de servir.