Proyecto educativo — no apto para producción sin validación técnica. Leer disclaimer
OVERVIEW
Hay un momento que todo vibe coder recuerda: la primera vez que una app que construiste le responde algo inteligente a alguien. Este proyecto es ese momento.
Vas a construir un chatbot web con una personalidad completamente definida por ti — puede ser un sommelier de vinos sarcástico, un filósofo estoico que responde preguntas de programación, o un asistente de viajes obsesionado con destinos off-the-beaten-path. La IA hace el trabajo pesado; tú defines quién es.
Al terminar tendrás una aplicación web deployada en Vercel, con interfaz de chat en tiempo real, historial de conversación en el navegador, y una URL que puedes compartir con cualquier persona. No es un tutorial genérico de "hola mundo" — es una app con identidad propia que refleja tu criterio creativo.
El secreto del proyecto está en el system prompt: un bloque de texto donde le dices a Claude exactamente quién es, cómo habla, qué sabe y qué límites tiene. Dominar esa técnica es la base de casi todo lo que vas a construir después en el mundo de la IA.
TECH STACK
THE PROBLEM
Cuando alguien empieza en vibe coding, el primer obstáculo no es técnico: es la parálisis de no saber por dónde empezar. Los tutoriales muestran código aislado, pero nadie te enseña a construir algo completo, desplegado, con una URL real que puedas mostrar.
Además, la mayoría de los ejemplos de "chatbot" son aburridos — un assistant genérico sin carácter. Un chatbot con personalidad es infinitamente más interesante de construir, más fácil de explicar en una entrevista, y mucho más memorable para quien lo usa.
Este proyecto resuelve los dos problemas a la vez: te da un camino claro de principio a fin, y el resultado final tiene carácter propio.
PROPOSED SOLUTION
Usuario escribe un mensaje en el frontend
El frontend envía el historial de conversación a `/api/chat`
La API route llama a Anthropic con el system prompt + historial
La respuesta se devuelve al frontend con streaming para que aparezca en tiempo real
MVP FEATURES
RELEASE PHASE: v0.1-ALPHA// CÓMO EJECUTARLO
PASOS SUGERIDOS
Crear el proyecto base: Pedile a Claude Code que genere un proyecto Next.js con TypeScript y Tailwind. Descripción: "crea un proyecto Next.js 14 con App Router, TypeScript y Tailwind CSS".
Instalar el SDK de Anthropic: `npm install @anthropic-ai/sdk`. Pedile a Claude Code que cree el archivo `.env.local` con la variable `ANTHROPIC_API_KEY`.
Crear la API route de proxy: Pídele que cree `/app/api/chat/route.ts`. Describe que debe recibir un array de mensajes y un system prompt, llamar a la API de Claude con streaming, y devolver la respuesta como stream.
Definir la personalidad: Antes de tocar el frontend, escribe en papel quién es tu chatbot. Nombre, backstory, forma de hablar, temas que domina, cosas que le disgustan. Esto va a ser tu system prompt.
Crear el componente de chat: Pídele a Claude Code un componente React con el historial de mensajes, el input, y la lógica de llamada a la API. Describe la UI que imaginas.
Conectar streaming: Pídele que implemente el consumo del stream en el frontend usando `ReadableStream`. Es el paso más técnico, pero Claude Code lo maneja muy bien.
Agregar polish: Botón de limpiar, indicador de loading, scroll automático al último mensaje, estilos que reflejen la personalidad del bot.
Deploy en Vercel: Conectar el repo de GitHub a Vercel, configurar la variable de entorno `ANTHROPIC_API_KEY`, y deployar.
Compartir: Manda la URL a alguien y mira su reacción cuando chatea con tu bot.
LO QUE VAS A APRENDER
Cómo funciona la arquitectura de una app de IA: frontend, API proxy, y LLM
Qué es un system prompt y cómo usarlo para controlar el comportamiento de un modelo
Cómo manejar streaming de respuestas en Next.js
Por qué nunca se expone una API key en el cliente y cómo evitarlo con una API route
El ciclo completo de vibe coding: describir → generar → iterar → deployar
Variables de entorno y cómo manejar secretos en desarrollo y producción
Deploy en Vercel desde cero
HERRAMIENTAS
PUNTO DE PARTIDA SUGERIDO
Claude Code + Claude Sonnet 4.5
TAMBIÉN FUNCIONA CON
El método importa más que la herramienta. Elige la que ya conoces.
Seguridad
La API key de Anthropic vive únicamente en variables de entorno del servidor — nunca en el código del cliente ni en el bundle de JavaScript (cualquier `NEXT_PUBLIC_` prefix la expone al navegador)
Validar y sanitizar el input del usuario antes de enviarlo al LLM: longitud máxima, caracteres permitidos, detección de intentos de inyección de instrucciones
Implementar rate limiting básico en la API route para evitar que un usuario abuse de tu cuota (por ejemplo, máximo 20 requests por minuto por IP)
Sanitizar el output del LLM antes de renderizarlo en el DOM si usas `dangerouslySetInnerHTML` — el modelo puede devolver HTML malicioso si el usuario lo indujo
Rendimiento
Limitar el historial de conversación que se envía al LLM: guardar los últimos N mensajes (por ejemplo 20), no el historial completo desde el inicio de la sesión
Implementar streaming correctamente sin acumular todos los chunks en memoria antes de mostrarlos — cada chunk debe llegar al DOM a medida que se recibe
Evitar re-renders innecesarios en el componente de chat: el historial de mensajes no debería re-renderizar mensajes anteriores cada vez que llega un nuevo chunk
Agregar un timeout a la llamada a la API para no dejar al usuario esperando indefinidamente si el modelo no responde
Arquitectura y Estructura
Separar el system prompt en un archivo de configuración independiente (por ejemplo `config/personality.ts`) — no hardcodearlo dentro del handler de la API route
No mezclar lógica de UI con llamadas a la API: el componente de chat no debería llamar directamente a Anthropic, sino a tu propia API route como proxy
Manejar explícitamente los errores de la API de Anthropic: rate limit (429), timeout, y errores de autenticación (401) con mensajes claros al usuario en lugar de pantallas rotas
Definir tipos TypeScript para los mensajes de la conversación en lugar de usar `any` — el SDK de Anthropic exporta los tipos necesarios
Antes de publicar (MVP Checklist)
Verificar que `ANTHROPIC_API_KEY` está configurada en las variables de entorno de Vercel (no solo en `.env.local`)
Confirmar que `ANTHROPIC_API_KEY` no aparece en ningún commit del historial de git con `git log -S "ANTHROPIC_API_KEY"`
Probar que el streaming funciona correctamente en el deploy de Vercel (no solo en desarrollo local)
Verificar que el botón de limpiar el historial vacía correctamente el estado y el bot responde como si fuera una conversación nueva
Confirmar que el bot responde en el idioma y con la personalidad definida en el system prompt, no en inglés genérico
// FASES DE DESARROLLO
Fase 1 — Setup (30 min):
Crear el proyecto base, instalar dependencias, configurar la API key como variable de entorno. No escribas ninguna lógica de chat todavía.
Fase 2 — API proxy (1-2 horas):
Crear la route que conecta el frontend con el LLM. Probarla con un cliente HTTP (curl o Postman) antes de tocar la UI.
Fase 3 — Sistema de personalidad (1-2 horas):
Escribir el system prompt de tu chatbot. Este paso no es técnico — es creativo. Dedica tiempo real aquí, es lo que diferencia tu proyecto.
Fase 4 — Frontend (2-4 horas):
Construir el componente de chat: input, historial de mensajes, streaming. Conectarlo a la API del paso 2.
Fase 5 — Polish y deploy (1-2 horas):
Estados de carga, scroll automático, botón de reset. Deploy en Vercel.
¿Agente o modo chat?
Para este proyecto, modo agente (Claude Code, Cursor Agent, Copilot Workspace) es la mejor opción. El agente puede crear archivos, instalar dependencias y ejecutar el servidor local sin que cambies de contexto. Si usas m
¿TUI o editor?
Claude Code (TUI): Ideal si te sientes cómodo en la terminal. Puedes describir cada fase y dejar que el agente trabaje en el proyecto completo.
Cursor o Windsurf (IDE): Mejor si prefieres ver los archivos mientras se generan. El modo Agent de Cursor es equivalente en capacidad.
GitHub Copilot: Mejor para asistencia línea a línea que para generar el proyecto completo desde cero.
// PROMPT INICIAL SUGERIDO
Vamos a construir juntos una aplicación de chatbot con Next.js, App Router y TypeScript. Antes de escribir una línea de código, necesito que me hagas las preguntas necesarias para definir bien el scope del proyecto: qué personalidad tendrá el bot, qué stack exacto usaremos, si hay preferencias de UI, qué funcionalidades son MVP y cuáles son opcionales. Una vez tengamos el scope claro, construye la aplicación. A medida que implementes cada decisión técnica (estructura de archivos, elección de patrones, manejo del streaming, etc.), explícame brevemente por qué tomaste esa decisión y qué alternativas existían. Quiero entender lo que se construye, no solo que funcione. Requisitos base: - API route en /app/api/chat/route.ts como proxy hacia [tu LLM preferido] - Recibe un array de mensajes y un system prompt, devuelve respuesta con streaming - Componente de chat con historial de mensajes, input y stream en tiempo real - System prompt que define la personalidad del bot: [describe aquí quién es tu chatbot] - API key desde variables de entorno, nunca hardcodeada
¿LISTO PARA CONSTRUIRLO?
Abre tu herramienta de Vibe Coding favorita y empieza a construir.