Flujo greenfield de Claude Code: del repositorio vacío al primer slice

Qué intentas evitar con un inicio greenfield

Empezar desde un repositorio vacío se siente como libertad, pero a menudo se convierte en una inercia desordenada: muchos archivos generados, una build a medias y ningún lugar claro donde poner el siguiente cambio. El objetivo del flujo greenfield de Claude Code es evitar ese caos de la primera semana.

Algunos fallos aparecen una y otra vez:

• Código que “funciona en mi máquina” porque la configuración vive en la memoria de alguien, no en scripts.
• Un árbol de carpetas que refleja el orden en que se crearon las cosas, no cómo debe crecer la app.
• Un bucle donde cada nuevo prompt reescribe elecciones anteriores, así nada se estabiliza.

Las decisiones tempranas son caras de deshacer porque todo se apila sobre ellas. Una estructura confusa se refuerza. Una build manual se transforma en diez setups distintos. Si no fijas un comando dev simple desde el principio, no podrás saber si un cambio rompió la app o solo el entorno.

Cuando en este post decimos “app en ejecución”, nos referimos a algo concreto: un comando que inicie el proyecto, imprima una salida predecible y falle de forma clara cuando falta algo. Debes poder borrar tu instalación local, clonar el repo, ejecutar ese comando y ver el mismo resultado.

Un “slice vertical” es la característica end-to-end más pequeña que demuestra que la app es real. No es un mock de UI. No es solo una tabla de base de datos. Es una línea delgada a través de todo el sistema: por ejemplo, una página con un formulario, un endpoint API que guarda datos, una escritura y lectura en la base de datos, y un resultado visible en la página.

Si puedes ejecutar la app con un comando y lanzar un slice vertical, tienes una base sobre la que iterar sin adivinanzas.

Decide el primer slice antes de generar cualquier cosa

Un primer slice claro mantiene tu repo ordenado y tus prompts enfocados. Este es el momento de decidir qué quieres demostrar de extremo a extremo, no en lo que esperas que se convierta el producto final.

Elige la historia de usuario más pequeña que pruebe que la app funciona en todo el trayecto. Un buen slice toca UI, datos y una acción real. Ejemplo: “Como usuario, puedo añadir una tarea y verla aparecer en una lista después de refrescar.” Es pequeño, pero fuerza routing, validación, almacenamiento y una pantalla básica.

Elige una plataforma objetivo para la semana 1 y cíñete a ella. Si empiezas con web, haz solo web. No añadas pantallas móviles “por si acaso”. Incluso si planeas usar una plataforma como Koder.ai más adelante, obtendrás mejores resultados si el primer slice se mantiene en una sola vía (React web, o una API en Go, o Flutter).

Define qué significa “listo para la semana 1” en términos claros:

• Se ejecuta localmente desde un clone limpio con un comando
• Una funcionalidad operativa que puedas recorrer de principio a fin
• Los errores muestran un mensaje humano (no un stack trace)
• Los datos persisten en algún sitio simple (incluso una base de datos local)

Luego escribe tres no-objetivos que protejan el alcance. Por ejemplo: sin auth, sin sistema de temas, sin jobs en background.

Una vez escritas esas decisiones, tu prompt de generación puede ser estricto: construye solo lo que soporta el slice y deja todo lo demás como TODO.

Algunas decisiones iniciales que ahorran trabajo

Antes de pedirle a Claude que genere cualquier cosa, fija un puñado de valores por defecto. Parecen pequeños, pero evitan el desastre de “renombrarlo todo después”.

Primero, decide la forma de la app. Si realmente necesitas UI en browser y un backend, comienza con dos partes claras (frontend + API) y un lugar compartido para contratos (tipos de API o un esquema simple). Si la app puede ser una web renderizada por servidor, mantenla en un solo código para que el desarrollo local sea simple.

Luego, acuerda reglas de configuración. Usa un archivo env local, mantenlo fuera de git y comete una plantilla en su lugar (por ejemplo, .env.example) con marcadores seguros y comentarios breves. Esto facilita el onboarding y reduce fugas de secretos.

Elige puertos dev por defecto y mantenlos estables. Los puertos acaban en scripts, docs y mensajes de error, así que cambiarlos después es molesto. Haz lo mismo con los nombres: carpetas, servicios y paquetes deben seguir una convención. La consistencia importa más que la “convención perfecta”.

Un conjunto simple de decisiones iniciales:

• Forma de la app: app única o frontend + API
• Config: .env local, .env.example commiteado
• Puertos: uno para web, uno para API, uno para DB (si hace falta)
• Nombres: un estilo de casing para carpetas, nombres de servicios consistentes
• Secretos: nunca en el repo, rotar si se exponen

Ejemplo: eliges web en el puerto 3000 y api en el 8080. Tu plantilla de env incluye API_URL=http://localhost:8080 y DATABASE_URL=.... Cuando Claude genere scripts y docs después, todo encajará en lugar de desviarse.

Cómo pedirle a Claude Code que mantenga la estructura

Empieza pidiendo un scaffold ejecutable, no “la app completa”. El camino más rápido a salida desordenada es solicitar características antes de tener dónde ponerlas.

Sé explícito sobre la estructura. Pide un layout de carpetas con comentarios cortos que expliquen qué va en cada sitio y qué no. Eso fuerza decisiones desde el principio en vez de dispersar archivos.

Una forma simple de mantener disciplina es establecer reglas en el prompt:

• Genera primero el esqueleto runnable más pequeño (página de hola, endpoint de salud, o una pantalla).
• Propón una estructura de carpetas y explica cada carpeta en 1 frase.
• Añade scripts que funcionen en una máquina limpia (install, dev, test, build) y declara prerequisitos.
• Mantén los cambios en un solo PR y lista exactamente qué archivos se crearán o editarán.
• Para tras scaffolding y dime cómo ejecutarlo.

Aquí tienes un prompt que puedes reutilizar y adaptar:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Luego mantén el ciclo corto. No pidas cinco cambios a la vez. Genera un cambio pequeño, ejecútalo, pega el error exacto (o el éxito) y pide una corrección mínima. Ese ritmo de generar-ejecutar-ajustar mantiene el proyecto predecible y hace más difícil que la estructura se desvíe.

Paso a paso: de repo vacío a un esqueleto ejecutable

Comienza con una promesa: cualquiera puede clonar el repo y ejecutar un comando para ver algo funcionando. Eso te da una base estable antes de pedirle a una IA que añada características reales.

Crea el repo y escribe un README tiny mientras todo está fresco. Mantenlo práctico: prerequisitos, el comando dev único y cómo ejecutar tests (aunque los tests estén vacíos por ahora).

Luego, escoge un layout top-level que coincida con la forma de la app que elegiste.

Si vas a construir múltiples piezas desplegables (por ejemplo, frontend + API), un layout tipo workspace ayuda:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Si construyes una sola app, mantenlo más simple y evita niveles extra hasta que los necesites.

Ahora añade las guardas mínimas para que el código se mantenga consistente. Elige un formateador y un linter, acepta sus valores por defecto y añade un único archivo de configuración para cada uno. El objetivo es diffs limpios, no reglas perfectas el primer día.

Haz la experiencia de desarrollador predecible con un comando que siempre funcione desde la raíz del repo. Aquí tienes una forma simple:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Antes de generar otra cosa, ejecuta ese comando dev, confirma que sale limpio (o arranca un servidor placeholder), y luego haz tu primer commit solo con el scaffolding. Si un compañero (o tú en el futuro) puede reproducir el setup desde cero, estás listo para construir el primer slice.

Una estructura de carpetas que puedas mantener

Una buena estructura greenfield hace dos cosas: te ayuda a encontrar código rápidamente y le da a Claude menos espacio para inventar nuevos patrones cada vez que pides un cambio. El objetivo no es la perfección. Es la estabilidad.

Si trabajas dentro de una sola app (o dentro de apps/<name>/), un layout interno simple suele aguantar bien:

• src/ código de la app (features, piezas compartidas, puntos de entrada)
• config/ configuración no secreta
• tests/ tests de alto nivel que se leen como comportamiento de usuario
• scripts/ scripts auxiliares (setup dev, reset de DB, tareas de release)
• docs/ notas breves y checklists que realmente mantengas

Dentro de src/, separa código de features del código compartido en función de patrones de cambio. El código de feature cambia a menudo y debería vivir cerca. El código compartido debe ser aburrido y reutilizable.

Una regla práctica: pon pantallas UI, handlers y lógica específica de feature bajo src/features/<featureName>/.... Pon cosas como logging, clientes API, componentes de design system y utilidades genéricas bajo src/shared/.... Si un helper solo tiene sentido para una feature, mantenlo en esa feature aunque parezca reusables. Muévelo cuando tengas un segundo uso real.

Los nombres de carpetas deben describir propósito, no tecnología. “features” y “shared” siguen siendo útiles aunque cambie tu stack. Evita nombres como “misc” o “new”.

Mantén docs/ pequeño. Un buen inicio es docs/checklists.md con unas pocas líneas: cómo ejecutar, cómo testear, cómo añadir una carpeta de feature y qué significa “done”.

Scripts de build que hagan el proyecto predecible

Un repo parece real cuando cualquiera puede ejecutar los mismos comandos y obtener el mismo resultado. Los scripts son guardarraíles: reducen las conjeturas, mantienen los cambios pequeños y hacen obvio cuando algo se rompe.

Empieza con un conjunto pequeño de comandos y mantenlos aburridos. Si alguien nuevo se une (o vuelves en dos semanas), no deberían necesitar flags especiales o pasos ocultos.

Aquí tienes una base simple que puedes adaptar a cualquier stack:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Haz que el script dev sea la vía feliz. Debe iniciar la app, imprimir dónde está corriendo y mantener logs legibles. Si el servidor no puede arrancar, falla rápido con un mensaje claro (env var faltante, puerto en uso, DB inalcanzable).

El script build debe siempre crear un directorio de salida limpio. Borra la salida anterior primero y luego produce artefactos nuevos. Eso evita bugs extraños causados por archivos de ayer.

Para tests, separa checks rápidos de checks lentos. Los tests rápidos corren en cada cambio (unit tests, type checks). Los tests completos incluyen integraciones y se ejecutan antes del merge.

Mantén el estilo consistente con un comando. Una regla simple: format arregla cosas, lint señala problemas.

Finalmente, añade una comprobación smoke que valide lo básico antes de perder tiempo debuggeando:

• Variables de entorno requeridas están definidas (y no vacías)
• Los puertos elegidos están libres
• La app puede arrancar y responder a una petición simple
• La conexión a la base de datos funciona (si se usa)
• El output de build existe tras build

Construye el primer slice vertical

Tu primer slice vertical debe demostrar que la app funciona end-to-end, no solo que la UI luce bien. Eso significa una pequeña funcionalidad que toque pantalla, lógica y algún tipo de almacenamiento, aunque sea temporal.

Elige algo aburrido y útil, como “Añadir una nota” o “Crear una tarea”. Manténlo lo bastante pequeño para terminar en una sesión, pero completo para que puedas interactuar y ver un cambio de estado real.

Un buen slice tiene cuatro partes: una ruta o pantalla, un formulario, una acción de guardado y una visualización. Ejemplo: una página “Nueva Tarea” con un input de título, un botón Guardar que llama a una función y una lista que muestra las tareas guardadas.

Empieza con una store placeholder para moverte rápido. Un array en memoria, un archivo JSON local o un stub simple está bien. La clave es crear el límite que luego reemplazarás. Si hoy tu código llama a taskRepository.save(task), cambiar a una base de datos real después será un cambio pequeño, no una reescritura.

Mantén la UI sencilla. Omite debates de design system, estados vacíos y animaciones.

Checks de aceptación que puedes hacer en dos minutos:

• La página se abre sin errores
• Puedes escribir un valor y pulsar Guardar
• El nuevo ítem aparece inmediatamente
• Al recargar se observa el comportamiento esperado (persistido si es almacenamiento real, reiniciado si es falso)
• El input inválido se gestiona (título vacío muestra un mensaje y no se guarda)

Hazlo lo suficientemente estable para iterar

Tras tener un esqueleto ejecutable y un slice, el objetivo cambia: haz que las roturas sean obvias y las correcciones rápidas. Aquí es donde muchos inicios greenfield se vienen abajo, no porque la feature sea dura, sino porque pequeños cambios empiezan a provocar sorpresas.

Fija una barra de estabilidad pequeña que cumplas cada vez que añades un slice:

• Un test smoke que pruebe que la app arranca y la ruta/pantalla principal se renderiza
• Un test smoke que golpee el slice end-to-end (aunque use una DB de pruebas)
• Mensajes de error claros que un usuario normal entienda (no stack traces)
• Logs de dev que expliquen qué pasó sin imprimir secretos
• Dependencias mínimas, versiones fijadas, upgrades intencionados

Ejemplo concreto: tu primer slice permite crear un “Proyecto” y verlo en una lista. Añade un test que arranque el servidor, llame al endpoint de creación, luego obtenga la lista y verifique que aparece el nuevo ítem. Si falla, debe fallar de forma clara con un mensaje útil, como “Create Project endpoint returned 500”, no un muro de salida.

Para el manejo de errores, quédate con un pequeño conjunto de respuestas consistentes. Errores de validación devuelven un mensaje corto (“Name is required”) y el campo. Errores inesperados devuelven “Algo salió mal. Inténtalo de nuevo.” Guarda los detalles para los logs.

El logging es más útil cuando responde: qué petición, qué usuario (o anónimo), qué falló y dónde. En dev, incluye un id de petición y tiempos, pero evita volcar tokens, contraseñas, claves API o payloads completos por defecto.

Añade una comprobación de salud tiny. En web, puede ser un endpoint /health que devuelva ok. En móvil, puede ser un estado “Connected” que pase a “Offline” si la app no alcanza el backend. Es una señal rápida antes de debuggear lo equivocado.

Trampas comunes al usar IA en proyectos greenfield

La forma más rápida de malgastar un inicio greenfield es pedirle al modelo una app completa y ejecutarla más tarde. Las grandes generaciones ocultan pequeños errores: dependencias faltantes, rutas de import incorrectas, scripts que asumen herramientas que no tienes. Trata cada output como algo que deberías poder ejecutar en minutos.

Otra trampa es diseñar la arquitectura perfecta antes de tener una feature. Debatir nombres de carpetas se siente productivo, pero sin un slice real no puedes saber qué es incómodo. Una estructura simple que soporte un camino funcional vence a una ingeniosa que no has probado.

El drift de comandos también es común. La IA añade una nueva forma de arrancar el servidor, tú añades otra para tests y pronto nadie sabe cuál es “el” comando. Si un compañero clona el repo y pregunta “¿Cómo corro esto?”, ya estás pagando interés.

Errores que causan más rework:

• Generar múltiples servicios, pantallas y configs de una vez en lugar de construir una ruta runnable primero
• Introducir auth, pagos, estilizado complejo y un modelo de datos completo antes de que la primera feature funcione end-to-end
• Dejar instrucciones de setup en el chat en lugar de scripts (o un README único)
• Olvidar una plantilla de env limpia, de modo que la siguiente máquina no pueda arrancar sin adivinanzas

Un ejemplo simple: generas una app “completa” con login, theming y billing, pero la primera ejecución falla porque falta una clave secreta y no hay .env.example. Pasas una hora arreglando setup en vez de aprender si la feature es útil.

Sé honesto: un comando runnable, una feature pequeña, una plantilla de env, y luego expande.

Lista rápida antes de empezar a iterar

Antes de añadir “una feature más”, asegúrate de que el proyecto sea fácil de retomar mañana (o por otra persona). La velocidad no es el objetivo por sí sola. La predictibilidad sí.

• Ejecución con un comando: un dev nuevo puede copiar una plantilla de env, poner los pocos valores requeridos y arrancar la app con un solo comando. Si necesita pasos extra (setup de DB, migraciones, seed), captura todo en un script.
• Scripts cubren lo básico: comandos claros para dev, test, build y un smoke check rápido.
• Estructura obvia: el layout cuenta la historia (código app, config, scripts, tests) sin leerse todo el repo.
• Camino demo del slice vertical: puedes describir la demo en una frase, como “crear un ítem, verlo en una lista, refrescar, sigue ahí”.
• Punto de rollback: antes de cambios grandes, tienes un punto seguro al que volver (un commit limpio, un tag o un snapshot/rollback).

Si algún ítem falla, arréglalo ahora. Ajustar scripts y nombres es barato cuando el repo es pequeño.

Próximos pasos: convierte el flujo en un hábito repetible

Un inicio greenfield solo paga si puedes repetirlo. Tras tu primer slice vertical funcionando end-to-end, congela las partes buenas en una pequeña plantilla: mismos patrones de carpetas, mismos nombres de scripts y la misma forma de conectar UI, API y datos.

Trata tu primer slice como una implementación de referencia. Cuando empieces el slice #2, copia la forma, no el código. Si el slice #1 tiene una ruta, un handler, una capa de acceso a datos y una prueba básica, el slice #2 debe seguir el mismo camino.

Mantén la planificación ligera. Una nota de una página basta para los próximos 2–3 slices: objetivo y acción del usuario por slice (una frase), los datos necesarios, las comprobaciones de “done” y los riesgos a probar temprano.

Luego haz del mantenimiento un hábito. Una vez a la semana, haz una pasada corta de limpieza: ajusta scripts, actualiza el README con nuevos pasos de setup y refresca tu .env.example para que el onboarding siga siendo fácil.

Si prefieres un bucle de construcción centrado en chat, Koder.ai (koder.ai) es una opción que soporta modo planificación, snapshots y rollback, y puede exportar código fuente cuando quieras llevar el proyecto a otro lugar.

El objetivo es un flujo que puedas ejecutar sin pensar: planifica 2–3 slices, construye uno, estabiliza, repite.