Casi todos empezamos un proyecto igual: abrimos el agente y le pedimos que construya. Funciona hasta la tercera sesión, cuando el agente ya no recuerda qué acordamos y empieza a rehacer cosas.
Hoy te cuento qué hago entre crear el repositorio y escribir la primera línea de código, y por qué el despliegue es de lo último que me preocupa.
Lo que veremos hoy:
De la idea al repositorio
Crea el repositorio y clónalo
La primera conversación
El tamaño decide la documentación
Inicializar el proyecto
Requisitos, roadmap y fichas
Todo en local hasta que haya algo que enseñar
Qué descarto
Tres preguntas para seguir el hilo con Claude
Hola, soy Pol Marzà, AI Product Builder y cada semana escribo una nueva edición de Con Criterio, la newsletter sobre construir productos digitales con IA, con planificación, método y sin atajos. Si te han reenviado este email, puedes suscribirte aquí:
Un pequeño recordatorio: El domingo hago un directo donde hablaré del proceso que sigo para construir cualquier proyecto. Mostraré el proceso de principio a fin en una sesión de 90 minutos. Puedes apuntarte gratis aquí.
1. De la idea al repositorio
En el envío anterior decidimos el stack con cuatro preguntas: qué es, quién lo usa y qué hace ahí, qué información guarda y quién la cambia, y quién hará la primera versión. Primero la idea, después el stack.
Hoy damos el siguiente paso: convertir esa idea en un repositorio donde el agente sabe qué construir antes de escribir nada. Para eso uso mi plantilla, project-template. Impone una regla sencilla: antes de tocar código, el agente lee la documentación del proyecto. Si está vacía, pregunta. Si está rellena, arranca con todo el contexto.
Un agente sin contexto no es más rápido. Solo se equivoca antes.
Un pequeño recordatorio: El domingo hago un directo donde hablaré del proceso que sigo para construir cualquier proyecto. Mostraré el proceso de principio a fin en una sesión de 90 minutos. Puedes apuntarte gratis aquí.
2. Crea el repositorio y clónalo
Esto lo haces tú, desde tu cuenta de GitHub:
Abre github.com/polmarza/project-template y pulsa “Use this template” y después “Create a new repository”.
Elige tu cuenta como propietaria, ponle un nombre y decide si será público o privado.
Pulsa “Create repository”.
Ahora lo traes a tu ordenador. Crea una carpeta donde guardar tus proyectos (yo la llamo GitHub), haz clic derecho sobre ella, abre una terminal y escribe:
git clone [URL de tu repositorio]Ya tienes una copia local del repositorio. De momento solo contiene la plantilla: documentos vacíos y las instrucciones para el agente.
3. La primera conversación
Abre Claude Code y selecciona la carpeta que acabas de clonar. Yo trabajo con la aplicación de escritorio, con el chat a un lado y la previsualización de la web al otro, pero funciona igual desde la terminal.
Escribe cualquier cosa para empezar. Un “hola” basta. La plantilla hace que Claude lea primero sus instrucciones, vea que la documentación está vacía y te conteste con una pregunta: qué quieres construir y para quién.
A partir de ahí le cuentas tu idea y él te hace preguntas. Aquí es donde reutilizas lo que decidiste en el envío anterior: qué es, quién lo usa, qué datos guarda y con qué stack lo vas a construir. Cuanto más claro llegues, menos preguntas habrá.
4. El tamaño decide la documentación
La plantilla trae ocho documentos, pero no todos los proyectos necesitan los ocho. Rellenar un modelo de datos para un portfolio es burocracia, y la burocracia inútil enseña a saltarse el proceso entero.
Por eso lo primero que hace Claude es clasificar tu proyecto en uno de tres tamaños:
Sitio pequeño: landing, portfolio, web de contenido. Sin cuentas de usuario.
Producto: hay usuarios, estado y datos que se guardan.
Producto con negocio detrás: además hay que cobrar, medir o justificar decisiones.
En el portfolio del envío anterior, hecho con Astro y sin base de datos, Claude lo clasifica como sitio pequeño: PRD y arquitectura obligatorios, design system recomendado, y fuera negocio, roadmap, flujos de usuario y modelo de datos.
Los documentos que no aplican se borran, no se dejan vacíos. Un archivo vacío no se distingue de uno que se olvidó rellenar. Antes de borrar, Claude te enseña la lista y espera tu confirmación.
Después rellena los que quedan, uno a uno, confirmando contigo antes de pasar al siguiente. Cada paso queda guardado con un commit en tu ordenador.
5. Inicializar el proyecto
Con la documentación completa, Claude convierte la plantilla en tu proyecto. Reescribe el README para tu producto, rellena el archivo de instrucciones del agente con el nombre, el stack y las convenciones, ajusta la licencia y las variables de entorno, borra los restos de la plantilla y deja la primera entrada del registro de cambios.
El criterio es simple: cuando termina, ningún archivo habla de la plantilla. Todo habla de tu proyecto.
En este punto todavía no hay ni una línea de código. Solo hay acuerdos escritos.
6. Requisitos, roadmap y fichas
Cada funcionalidad del PRD lleva un identificador y un criterio para comprobar que funciona. Las priorizo con el método MoSCoW:
Must: imprescindible para que el proyecto tenga sentido.
Should: importante, pero puede esperar a la segunda vuelta.
Could: deseable si hay tiempo.
Won’t: descartado para esta versión, y se dice en voz alta.
En los proyectos de tamaño producto, el roadmap ordena esas funcionalidades: primero lo imprescindible, después lo demás.
Antes de construir cualquier funcionalidad, Claude escribe su ficha: qué se construye, qué requisitos cierra y cómo se comprobará cada uno. La revisa buscando ambigüedades y casos límite, y me deja a mí resolverlos. Yo leo la ficha, la corrijo si hace falta y la apruebo.
Solo entonces Claude empieza a construir.
La ficha es el contrato. Si no está aprobada, no hay código.
Cómo construyo a partir de ahí lo veremos en el directo.
7. Todo en local hasta que haya algo que enseñar
Desplegar es publicar el proyecto en una dirección de internet. Yo no lo hago el primer día. Mientras construyo, todo vive en mi ordenador: Claude arranca un servidor local y veo cada cambio en la previsualización al momento.
Si el proyecto tiene base de datos con Supabase, Claude levanta una copia local dentro de Docker. Así los errores de la base de datos aparecen en mi ordenador y no el día que subo a producción.
Para esto necesitas Docker instalado. Lo veremos en otro envío.
Despliego cuando hay algo que se puede mostrar: una landing, la primera pantalla funcional, lo que sea que alguien pueda abrir y entender. Ese momento lo veremos con calma en un próximo envío.
8. Qué descarto
Pedir los ocho documentos siempre. El tamaño del proyecto decide cuáles. Si crece, se añaden los que faltan en ese momento.
Construir sin ficha. Ahorra diez minutos hoy y cuesta horas de rehacer después.
Desplegar antes de tener algo que enseñar. Una dirección pública con una página vacía no comprueba nada que no compruebe el servidor local.
Conectar herramientas antes de tener stack. La plantilla no configura conectores hasta que la arquitectura está decidida.
9. Tres preguntas para seguir el hilo con Claude
Mi proyecto empezó como sitio pequeño y ahora quiero añadir cuentas de usuario: ¿qué documentos me faltan y en qué orden los relleno sin rehacer lo que ya tengo?
¿Cómo escribo un criterio de aceptación comprobable para una funcionalidad de mi PRD? Dame un ejemplo con “dado, cuando, entonces” aplicado a mi proyecto.
Quiero usar Supabase en local con Docker: ¿qué necesito instalar, cómo lo arranco y cómo paso después los cambios de la base de datos a producción?
¡Nada más por hoy! Pon esto en práctica y nos vemos en el directo del domingo :)