¿Qué hace Constructor de Aplicaciones?
Una forma repetible de llevar una idea a una aplicación web desplegada, probada y segura, en cualquier pila tecnológica. Se destiló a partir de la construcción de un proyecto real de principio a fin (una arena de debate de IA: Next.js, Drizzle, Better Auth, Vercel, Turso, QStash, Vitest, Playwright), incluyendo todos los errores cometidos en el camino. El núcleo (este archivo, profiles/, reference/) es independiente de la pila; lo que es específico de un producto o marco de trabajo vive en stacks/ y solo lo leen los proyectos que lo usan. Síguelo; no improvises el proceso.
Comienza aquí (cada sesión)
- Encuentra el estado del proyecto. Si
docs/plan.mdexiste, léelo primero: registra el perfil, las decisiones tomadas y el hito actual. Continúa desde allí; no vuelvas a preguntar cuestiones ya resueltas. - Elige el perfil (solo proyectos nuevos). Pregunta una vez, en lenguaje sencillo:
"¿Quieres involucrarte en las decisiones técnicas (código, hosting, bases de datos), o debería encargarme yo de eso y solo preguntarte sobre lo que la aplicación hace y cómo se ve?"
- Involucrado → lee
profiles/technical.md - Sin intervención → lee
profiles/guided.mdRegistra la respuesta endocs/plan.mdbajo "Cómo trabajamos". El perfil decide cómo preguntas y explicas; el proceso y el estándar de calidad a continuación son los mismos para ambos.
- Involucrado → lee
- Lee las notas de pila que el proyecto usa (ver "Notas de pila" más abajo).
- Lee
reference/process.mdy sigue sus fases en orden. Carga las demás referencias cuando una fase las mencione, no todas de una vez.
Notas de pila
stacks/ contiene un archivo por tecnología: pasos de configuración, problemas y soluciones aprendidas en proyectos reales.
- Cuáles leer: la sección "Cómo trabajamos" del plan las enumera ("Notas de pila: nextjs, vercel, …").
Lee exactamente esas al inicio de cada sesión. También revisa los manifiestos del proyecto (
package.json,vercel.json,docker-compose.yml…) y el sistema operativo del usuario: si usan algo con una nota que el plan no menciona, léela y agrégala a la lista. Los proyectos nuevos eligen sus notas cuando la pila se define (fase 2 del proceso). - Hazlo inolvidable: el archivo de instrucciones del proyecto (
CLAUDE.mdoAGENTS.md, cargado en cada sesión) indica leerdocs/plan.mdy sus notas de pila al inicio de cada sesión, sea cual sea la solicitud. De lo contrario, una sesión que nunca active esta habilidad nunca verá la lista. La habilidad vive fuera del repositorio, así que redáctalo para que degrade de forma elegante: el plan es autónomo; las notas de pila se leen solo "si la habilidad app-builder está instalada". - Antes de adoptar un nuevo servicio o librería, verifica si existe una nota.
- Dónde va una nueva lección: si solo es válida al usar un producto, va en la nota de ese producto (crea una si no existe:
stacks/<producto>.md, comenzando con "Cargar cuando…"). Si es válida en cualquier lugar, va enreference/en términos genéricos, con el producto como ejemplo y un puntero a su nota. Ejemplo: "reintentar una vez cuando un servicio remoto cierra una conexión inactiva" está enreference/lessons.md; el envoltorio de fetch de libSQL que lo implementa está enstacks/turso-libsql.md. - Las notas registran hechos fechados (límites, listas de modelos, precios) en el momento en que se aprendieron: vuelve a verificarlos.
Auditoría de un proyecto existente
Cuando se te pida aplicar esta habilidad a un proyecto que ya existe (o después de un gran cambio), no reinicies el proceso; audita e informa:
- Compara
docs/plan.mdcontemplates/plan.mdy enumera las secciones faltantes. - Recorre
reference/quality-gates.mdsección por sección (seguridad, resiliencia, rendimiento con mediciones reales y Lighthouse, lista de verificación de UI, accesibilidad en ambos temas, operaciones y cuotas). - Busca en el código los antipatrones de
reference/lessons.mdy de las notas de pila del proyecto. - Formula las preguntas iniciales que el proyecto nunca respondió (por ejemplo, ciclo de vida de cuentas, abuso de cuotas).
- Informa las brechas clasificadas (brechas reales, brechas del plan, baja prioridad, lo que ya está bien), con soluciones. Las brechas que el propietario rechace van a la tabla de "Riesgos aceptados" del plan. No cambies nada hasta que el propietario esté de acuerdo.
No negociables (ambos perfiles)
- Fases e hitos: trabaja a través de las fases en
reference/process.md, construyendo en pequeños hitos que cada uno termine ejecutable, probado, demostrado y confirmado antes de que comience el siguiente. Acuerda la lista de hitos con el usuario al inicio y mantenla actualizada endocs/plan.md. - La aplicación funciona como se espera: cada hito termina ejecutable, demostrado en un navegador real, con el resultado mostrado al usuario.
- Resiliencia: cada dependencia externa y proceso de larga duración tiene una respuesta planificada a "¿qué pasa si falla?" (caído, lento, con límite de tasa, bloqueado a mitad de camino, entregado dos veces), registrada en la tabla de modos de fallo del plan, manejada en código, visible para los usuarios en lenguaje sencillo y probada.
- Rendimiento: objetivos acordados (por ejemplo, las páginas responden en menos de un segundo cerca de la audiencia), medidos después del despliegue; sin trabajo obviamente ineficiente (consultas sin índice, sondeos innecesarios, cargas útiles sobredimensionadas).
- Calidad: cada hito pasa los controles de
reference/quality-gates.md(lint, tipos, pruebas unitarias, pruebas de extremo a extremo, compilación, CI, la lista de verificación de revisión de UI). No se deja abierto ningún defecto mayor conocido. - Seguridad: la lista de verificación de seguridad en
reference/quality-gates.mdse cumple en cada hito, no como una pasada final. - Diseño mantenible: las reglas de negocio viven en módulos simples y sin marco de trabajo con pruebas unitarias; los servicios externos están detrás de costuras pequeñas (un archivo para intercambiar); el plan y el README se mantienen actualizados.
- Pruebas en el nivel adecuado: pruebas unitarias para reglas, pruebas de navegador de extremo a extremo para flujos de usuario, un simulacro por script para cualquier servicio externo de pago o lento (modelos de IA, pagos).
- Costo bajo control: el presupuesto del usuario es explícito en el plan; cualquier cosa que pueda costar dinero tiene un tope, un nivel gratuito sin tarjeta asociada o la propia clave del usuario.
- Los secretos nunca pasan por el chat: el usuario coloca los secretos en
.env.localy en el panel de hosting por sí mismo, o una integración de marketplace los inyecta (verreference/third-party-setup.md). - Verifícalo tú mismo primero: después de un cambio o despliegue, verifica el resultado tú mismo (el navegador, los registros de la plataforma de hosting y el estado del despliegue a través de su CLI, un script de sondeo) antes de informar o pedir al usuario que lo mire. Pide al usuario solo lo que necesita de él: iniciar sesión, secretos, dinero, aprobaciones. Verificar la producción tú mismo es cómo salen a la luz errores ocultos.
- Informes honestos: di qué se verificó y cómo, qué no, y qué falló. Nunca afirmes una comprobación que no hayas ejecutado.
- Verifica hechos que cambian: los precios, los límites del nivel gratuito, las APIs de librerías y las versiones se verifican contra fuentes actuales (documentos en
node_modules, páginas oficiales) antes de confiar en ellos, y se citan las fuentes.
Archivos en esta habilidad
| Archivo | Úsalo para |
|---|---|
profiles/technical.md | Cómo trabajar con un propietario técnico: qué preguntar, qué decidir y anunciar |
profiles/guided.md | Cómo trabajar con un propietario no técnico: lenguaje, opciones, instrucciones paso a paso |
reference/process.md | Las fases, desde el inicio hasta la entrega, con lo que cada una debe producir |
reference/quality-gates.md | Definición de terminado, estrategia de pruebas, listas de verificación de resiliencia, rendimiento, seguridad y revisión de UI |
reference/stack-defaults.md | Pila y arquitectura por defecto, niveles de presupuesto, cuándo desviarse |
reference/environment.md | Verificación previa al vuelo y configuración de permisos que eliminan la mayoría de las interrupciones |
reference/third-party-setup.md | Cuentas, secretos y configuración de hosting/base de datos/cola con trabajo manual mínimo |
reference/lessons.md | Errores concretos ya encontrados y sus soluciones, en términos independientes de la pila. Ojea antes de cada hito |
templates/plan.md | Esqueleto para el archivo docs/plan.md del proyecto |
Notas de pila (léelas solo cuando el proyecto las use):
| Archivo | Cubre |
|---|---|
stacks/nextjs.md | Next.js App Router, Cache Components, proxy, route handlers, server actions, formularios de React 19, servidor de desarrollo |
stacks/vercel.md | Hosting de Vercel: regiones, variables de entorno y redespliegues, CLI, registros, configuración de compilación |
stacks/turso-libsql.md | SQLite/libSQL con Drizzle, Turso: configuración, migraciones, fetch remoto, conexiones inactivas muertas |
stacks/better-auth.md | Better Auth: confirmación de correo electrónico, restablecimiento de contraseña, vinculación de cuentas, problemas de sesión |
stacks/upstash-qstash.md | Upstash QStash: servidor de desarrollo local, firmas, retrasos, programaciones, cuota |
stacks/ai-providers.md | SDK de IA de Vercel, Groq, Google AI Studio, OpenRouter (flujo de conexión, modelos gratuitos), Ollama |
stacks/gmail-smtp.md | Envío de correos electrónicos de cuenta a través de Gmail sin un dominio |
stacks/playwright.md | Pruebas de extremo a extremo con Playwright: selectores, páginas ocultas, simulacros locales |
stacks/github.md | Repositorio de GitHub, CI de Actions, inicio de sesión con GitHub |
stacks/google-oauth.md | Inicio de sesión con Google: proyecto de Cloud, pantalla de consentimiento, marca, un cliente para local y producción |
stacks/windows.md | Desarrollo en Windows: Smart App Control, PowerShell, Docker, CLIs |