Construir un SaaS con un agente de código: un flujo práctico

Empieza por un resultado observable

Un agente de código puede producir una interfaz de aspecto convincente antes de que hayas decidido qué debe hacer. Empieza por un pequeño resultado de usuario: un usuario conectado edita su perfil, lo guarda y ve el nombre guardado tras recargar. Eso da a la implementación y a la revisión un objetivo concreto.

Incluye en el brief el comportamiento actual, el comportamiento esperado y los casos de fallo que importan. Nombra el módulo existente que posee el trabajo. Una petición de añadir edición de perfil debería apuntar a la capa de autenticación en lugar de dejar que el agente invente un segundo almacén de usuarios. Mantén las credenciales fuera de prompts y capturas — un apps/web/.env.local pegado o una cookie de sesión pasa a formar parte del registro de la conversación.

Un brief viable suena así: «En la pantalla de cuenta, permite que un usuario conectado edite su nombre visible y lo vea tras recargar. El módulo de auth posee el registro de usuario; no añadas una tabla. Un nombre vacío, o una petición que nombre el registro de otro usuario, debe rechazarse. Demuéstralo con pnpm test y un guardado manual a un ancho estrecho.» Cinco frases y la mayor parte de las conjeturas desaparece.

• El resultado visible para el usuario, redactado de forma que puedas comprobarlo en la app en ejecución.
• El archivo o módulo que posee el comportamiento hoy — y las zonas que deben quedar intactas.
• Al menos un caso de fallo: un intento no autenticado, una entrada inválida o una petición repetida.
• La comprobación que lo demuestra — un comando de test, un fixture o un recorrido manual explícito.

Haz que el repositorio se explique solo

Documenta cómo ejecutar la app, qué comprobaciones son deterministas y dónde se hace valer la propiedad. En supastack, AGENTS.md consigna el límite del espacio de trabajo y .ai/ las decisiones a nivel de archivo. Esas notas son más útiles cuando explican al siguiente contribuyente — humano o agente — por qué existe una implementación, no solo qué archivos cambiaron. La guía de configuración de agentes muestra cómo expone el kit ese material, y la guía de instalación local es el recorrido que el agente seguirá de verdad.

Pide al agente que lea el código relevante antes de modificar. Un cambio estrecho suele necesitar la interfaz, su frontera de servidor y los tests alrededor de esa frontera. Cargar todo el repo es menos útil que entender los pocos lugares que deciden si el nuevo comportamiento es correcto: la comprobación de propiedad, el esquema, el permiso.

Cuando una función toca configuración, nombra el archivo en lugar de transcribirlo — «añade la clave a apps/web/.env.local» mantiene los secretos en disco. La misma disciplina aplica a los paneles de proveedores: describe el destino, no pegues la credencial.

Trabaja en cambios pequeños y revisables

Los agentes son más fiables cuando un cambio tiene un solo dueño y un solo resultado comprobable. «Añade edición de perfil» es revisable; «mejora el área de cuenta» invita a refactors que nadie pidió. Si una función se descompone en un cambio de esquema, una frontera de servidor y una pantalla, ejecútalos como briefs separados que dejen el build en verde cada uno.

Haz commit o un punto de control antes de cada ejecución del agente. Una base limpia convierte una mala salida en un diff borrado en lugar de un ejercicio de arqueología, y da a tu revisión un antes y un después estables que comparar.

Revisa un cambio completo cada vez

Escribe una comprobación de aceptación antes de cambiar el comportamiento. Para la edición de perfil, cubre una actualización válida y un intento no autorizado. Construye la implementación mínima que satisfaga esos casos, luego inspecciona la interacción real con texto realista y un viewport estrecho.

Revisa el diff tanto como el resultado. Busca lógica de negocio duplicada, manejo de excepciones demasiado amplio y nuevas dependencias que resuelven un problema que el stack existente ya cubre. Ejecuta las comprobaciones del proyecto y registra lo que establecen. Un fixture de navegador puede verificar una interacción de formulario; no puede establecer que la base de producción o un proveedor externo esté bien configurado.

Cada comando responde a una pregunta distinta. pnpm test ejerce el comportamiento contra adaptadores fake y locales deterministas, pnpm check cubre lint, typecheck y formato, y pnpm build saca a la superficie los errores de integración que solo aparecen al empaquetar. Juntos son el suelo de la revisión — la checklist de lanzamiento cubre lo que aún debe demostrarse en el entorno real.

pnpm test
pnpm check
pnpm build

Cuando el agente se equivoca

Cuando un resultado sale mal, resiste apilar prompts de seguimiento sobre un mal diff. Vuelve al punto de control, ajusta el brief en torno a lo que se malinterpretó — normalmente una restricción no dicha o un dueño ausente — y ejecuta de nuevo. Cada reintento debe aportar información nueva, no solo nueva urgencia.

Un fallo persistente suele significar que el brief presupone contexto que el repositorio no contiene. Si el agente sigue inventando un segundo lugar donde guardar usuarios, la corrección es una frase en AGENTS.md sobre dónde vive la identidad, no un tono más firme. Actualiza el documento y reintenta la tarea — la guía de agentes es donde el kit guarda este flujo.

Preguntas frecuentes sobre flujos con agentes

Algunas preguntas surgen siempre que un fundador empieza a confiar trabajo real de producto a un agente de código.

• ¿Puede un agente de código construir un SaaS entero por sí solo? — Puede montar las partes visibles rápido, pero las duraderas — autorización, ciclo de vida de facturación, aislamiento de datos — siguen necesitando un brief, una comprobación y una revisión. La velocidad sin ese bucle se convierte en rehacer trabajo.
• ¿Qué tamaño debe tener una tarea para un agente de código? — Lo bastante pequeña para verificar el resultado en la app en ejecución en minutos: un resultado visible para el usuario, un módulo dueño, una comprobación de aceptación.
• ¿Qué no debe entrar nunca en un prompt? — Secretos de proveedores, cookies de sesión, el contenido de .env.local y datos de clientes. Nombra los archivos y deja que la herramienta los lea en local en lugar de copiar valores a un registro de chat.
• ¿El código escrito por un agente cambia cómo reviso? — La revisión se desplaza de escribir a leer: inspecciona el diff buscando lógica duplicada, manejo de excepciones demasiado amplio y dependencias que vuelven a resolver un problema que el stack ya cubre.
• ¿Qué tests importan más para la salida de un agente? — Los que fijan la propiedad y el comportamiento de fallo: peticiones no autorizadas, entrada inválida y envíos repetidos, no solo el camino feliz que muestra la demo.