Construir con Claude Code · No-code Handbook

En 2026 la forma de construir producto digital ha cambiado. Ya no se trata de elegir entre "no-code" o "código": con Claude Code y el ecosistema MCP, una sola persona con criterio de producto puede llevar una idea desde el PRD hasta producción —con base de datos, autenticación, tests y despliegue continuo— en una fracción del tiempo que costaba antes.

Este capítulo es la guía del proceso: las fases que seguimos cuando construimos un proyecto complejo de verdad, no una demo. Es deliberadamente práctico y sirve de base para el siguiente capítulo, donde entramos en la spec-driven development y en cómo usamos nuestras propias skills para llevar este proceso más allá.

El entorno y el MCP

Antes de escribir una línea de código, dejamos el terreno listo. Creamos las cuentas que vamos a necesitar —GitHub, Supabase y Vercel— y preparamos el entorno local: Node LTS, un editor con Claude Code y la CLI de Supabase con Docker. Y conectamos los conectores MCP que hacen el resto posible.

¿Qué es el MCP? MCP (Model Context Protocol) es un estándar que conecta la IA con herramientas externas —tu base de datos, un navegador, tu repositorio—. Sin MCP, la IA solo trabaja con lo que le pegas en el chat y adivina el resto; con MCP se conecta de verdad a esas herramientas y actúa sobre ellas: consulta tu base de datos real, controla un navegador, lee tu código.

Cada integración es un conector. En esta guía usamos dos: el de Supabase (la base de datos) y el de Playwright (testear en un navegador real). Piénsalo como darle manos y ojos a la IA: deja de trabajar a ciegas.

El PRD: decidir qué construir antes de tocar código

El PRD (Product Requirements Document) es el documento donde decides qué vas a construir antes de escribir nada. En un primer proyecto complejo, es lo que separa un build enfocado de improvisar durante semanas. No tiene que ser largo: tiene que ser claro. Es tu contrato con la IA — sin él, Claude Code rellena los huecos por su cuenta; con él, construye lo que de verdad quieres.

Qué tiene que llevar tu PRD:

El problema y para quién. Qué dolor resuelves y a qué usuario. Una o dos frases.
Funcionalidades, priorizadas. Lo imprescindible para la v1 separado de lo que es "más adelante". Aquí se gana o se pierde el foco.
Modelo de datos inicial. Qué entidades tienes (usuarios, proyectos, pagos…) y cómo se relacionan. Esto marca tu esquema de Supabase.
Flujos principales. Registro, login y la acción central de tu app.

Este PRD es el primer artefacto del proceso. En el siguiente capítulo veremos cómo lo convertimos en specs ejecutables con nuestras propias skills.

Una carpeta, un proyecto

Creamos una carpeta nueva solo para este proyecto y abrimos Claude Code dentro de ella. A partir de ahí, esa carpeta es su límite: lee, crea y edita archivos ahí dentro y no toca nada de fuera. La carpeta funciona como recordatorio físico del alcance: un proyecto, una carpeta, sin mezclar. Es el error clásico dejar la IA suelta en el escritorio o en tu home, donde puede tocar cosas que no debe.

mkdir ~/Desktop/mi-proyecto
cd ~/Desktop/mi-proyecto
claude   # abre Claude Code acotado a esta carpeta

Dentro metemos el PRD.md y un CLAUDE.md con las reglas del proyecto (stack, convenciones, qué no tocar). Claude Code los carga como contexto en cada sesión y se mantiene dentro de los raíles.

Arquitectura y estructura del repo

Nuestro stack por defecto: React + TypeScript con Vite, Tailwind y shadcn/ui para la interfaz, y Supabase como backend (BaaS). Organizamos las carpetas por producto o funcionalidad, no metemos todo en /components: cuando el proyecto crece, esa estructura es la diferencia entre iterar rápido o pelearte con tu propio código.

Prompt para Claude Code Arranca un proyecto nuevo con Vite usando React y TypeScript, instala las dependencias e inicializa shadcn/ui. Organiza las carpetas por producto o funcionalidad, no metas todo en /components.

Variables de entorno

Nada hardcodeado, nunca. Los secretos van en .env.local (incluido en .gitignore) y versionamos un .env.example con los nombres de las variables sin valores. Usamos el prefijo VITE_ para lo que se expone al frontend. En producción, esas variables se configuran en el panel de Vercel.

# .env.example
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=

Supabase por MCP: datos, auth, storage y migraciones

Esta fase es crítica. Aquí no nos peleamos con la CLI: trabajamos por MCP. Con el conector MCP de Supabase, Claude Code habla directamente con tu proyecto —lee el esquema, consulta y modifica tablas, revisa las políticas y te propone y aplica migraciones sin que copies nada a mano—. Tú describes el cambio en lenguaje natural ("añade una tabla proyectos con RLS por usuario") y la IA lo traduce a una migración versionada.

Lo que el MCP de Supabase le da a la IA:

Leer tu esquema y tablas reales, sin que le pegues capturas ni SQL.
Escribir y aplicar migraciones versionadas por ti.
Revisar y proponer políticas RLS antes de que se te olviden.
Consultar datos y diagnosticar errores contra la base real.

El esquema se sigue gestionando siempre con migraciones (nunca a mano en el dashboard) para que local, staging y producción sean idénticos.

Desarrollo asistido: capturas como contexto

Con Supabase conectado por MCP, la IA consulta tus tablas y te ayuda con queries y migraciones sin que copies el contexto a mano. Y le pasamos capturas como contexto visual —de Figma o de la UI actual— para generar e iterar pantallas: describir por texto da resultados genéricos; una captura da algo alineado con lo que de verdad buscas.

Un design system propio

Ten tu propio design system —tokens de color, tipografía y espaciado— y no dejes que el look por defecto de la IA defina tu producto. Usamos Figma como referencia y como fuente de las capturas que le pasamos a la IA. El branding es parte del trabajo: es lo que le da identidad coherente a todo. (Este mismo handbook es un ejemplo: se construyó aplicando nuestro propio sistema de marca, no el estilo por defecto.)

Testing con Playwright vía MCP

Con Playwright vía MCP, la IA controla un navegador real: navega, rellena formularios y valida los flujos críticos —registro, login, la acción principal de tu app— antes de mergear. Tests que se escriben y se ejecutan solos, sobre la app de verdad.

Aquí entran dos piezas: el conector MCP de Playwright (el que conectaste en la primera fase y le da a la IA el control de un navegador real) y Playwright dentro del repo (los tests que quedan guardados y se ejecutan solos). Lo segundo no lo instalas a mano: se lo pides a Claude Code.

Prompt para Claude Code Instala y configura Playwright en el proyecto para tests end-to-end, con los navegadores necesarios. Crea un primer test que valide el flujo de registro y login usando el conector MCP de Playwright, y déjalo listo para ejecutarse.

GitHub: ramas y pull requests

Una rama por feature, commits pequeños y frecuentes, y un pull request para agrupar y revisar los cambios antes de mergear a main. main siempre estable, historial claro y fácil de seguir.

El flujo, de local a main:

Rama nueva por feature.
Commits en local, pequeños y frecuentes.
Pull Request para revisar el conjunto.
Merge a main.

Deploy y entornos

Deploy automático: conectas el repo a Vercel y cada merge a main publica en producción. Trabajamos con tres entornos, cada uno con su propia instancia de Supabase y sus propias variables. Las migraciones son las que mantienen los tres esquemas idénticos.

Entorno	Frontend	Base de datos
Local	`npm run dev`	Supabase local + `.env.local`
Staging	Preview de Vercel (por PR)	Proyecto Supabase de staging
Producción	Rama `main` en Vercel	Proyecto Supabase de producción

Documentar y compartir

Graba un vídeo o testimonio del proyecto funcionando y documenta el proceso como caso de uso. Es la mejor forma de consolidar lo aprendido — y de enseñar lo que has construido.

El checklist del proceso

Si te llevas una sola cosa de este capítulo, que sea esta lista. Es el proceso entero, de principio a fin:

Cuentas listas y MCP conectado (Supabase + Playwright).
PRD escrito con la IA y guardado como PRD.md.
Carpeta del proyecto creada; Claude Code acotado a ella (+ CLAUDE.md).
Stack definido y carpetas organizadas por producto.
.env.local + .env.example, nada hardcodeado.
Supabase por MCP: auth, storage y RLS activado.
Cambios de esquema solo vía migraciones (escritas por la IA).
Desarrollo con IA usando capturas como contexto.
Design system propio definido.
Flujos críticos testeados con Playwright.
Ramas + PRs → merge a main.
Deploy automático con local/staging/prod separados.
Vídeo/testimonio grabado.

Del proceso a la spec

Este proceso es el esqueleto: te dice qué fases atraviesa un proyecto y en qué orden. Pero la parte que de verdad marca la diferencia es cómo le das a la IA un contexto lo bastante preciso como para que construya lo correcto a la primera.

Ahí es donde entra la spec-driven development. En el siguiente capítulo te contamos cómo convertimos el PRD en specs ejecutables y cómo usamos nuestras propias skills para que Claude Code trabaje con nuestro método, nuestras convenciones y nuestro criterio de producto — no con los suyos por defecto.