Claude Code × Next.js: Automatiza la Configuración de Tu Proyecto

Claude Code puede scaffoldear un proyecto Next.js 16 completo — TypeScript strict, Tailwind CSS v4, shadcn/ui, ESLint, hooks pre-commit y deploy en Vercel — en menos de 10 minutos. La clave es escribir un CLAUDE.md preciso que defina tu stack y reglas desde el inicio.

Si le pides a Claude Code que "cree un proyecto Next.js," lo que recibes tiene TypeScript configurado tan libremente que escupe errores de tipo por todas partes. Esta guía cubre exactamente qué poner en CLAUDE.md para obtener el resultado que realmente quieres. Desde la estructura de CLAUDE.md hasta la automatización de create-next-app, comandos personalizados, hooks pre-commit y deploy en Vercel — todo en una sola sesión.

¿Qué Cambia Cuando Dejas que Claude Code Se Encargue de la Configuración de Next.js?

Si tuvieras que listar todo lo involucrado en arrancar un proyecto Next.js a mano, se vería algo así:

• Ejecutar create-next-app y responder todos los prompts
• Habilitar TypeScript strict mode
• Instalar y configurar Tailwind CSS v4
• Inicializar shadcn/ui
• Configurar ESLint y Prettier
• Limpiar .gitignore
• Organizar la estructura del directorio src/

Hecho manualmente, son 30 a 60 minutos de trabajo. Con Claude Code, lleva de 5 a 10.

La advertencia: Claude Code solo hace lo que le dices que haga. "Hazlo bien" o "usa mejores prácticas" no se traduce. Necesitas especificar exactamente qué configuración quieres antes de delegar algo. Para eso es CLAUDE.md.

¿Cuál Es el CLAUDE.md Mínimo que Necesitas Escribir?

El archivo CLAUDE.md en la raíz de tu proyecto es el documento de diseño que Claude Code usa para entender tu proyecto. Aquí tienes una estructura mínima pero efectiva:

# Project Name

## Tech Stack
- Next.js 16+ (App Router)
- TypeScript (strict: true)
- Tailwind CSS v4
- shadcn/ui
- ESLint + Prettier

## Directory Structure
- `src/app/` — App Router routes
- `src/components/` — UI components
- `src/lib/` — Utility functions
- `src/types/` — Type definitions

## Coding Rules
- All components must be written in TypeScript
- No `any` types allowed
- Prefer `type` over `interface`
- Default to Server Components; only add `"use client"` when necessary

## Off-Limits
- No code outside `src/`
- No CSS-in-JS (use Tailwind)
- No `console.log` in committed code

Incluso esto mejora drásticamente la calidad del código. La sección "Off-Limits" es especialmente importante — sin prohibiciones explícitas, Claude Code usará configuraciones más relajadas por defecto.

¿Cómo Ejecutas la Configuración Completa Desde create-next-app Hasta shadcn/ui?

Con CLAUDE.md listo, dale a Claude Code un prompt como este:

Create a new Next.js project.
- Project name: my-app
- Follow the tech stack defined in CLAUDE.md
- Run create-next-app and complete initialization through shadcn/ui setup

Claude Code ejecutará algo como esto:

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

En Next.js 16, TypeScript, Tailwind CSS, ESLint, App Router y Turbopack están habilitados por defecto. Los flags de arriba siguen siendo válidos y hacen tu intención explícita — importante para que Claude Code produzca output determinístico. Ejecutarlo interactivamente puede hacer que Claude Code se quede esperando input, así que siempre usa flags.

Después de la configuración, refuerza la configuración de TypeScript:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

¿Cómo Automatizas la Configuración de shadcn/ui, Tailwind v4 y ESLint?

Inicializar shadcn/ui

npx shadcn@latest init

Al instruir a Claude Code, especifica tus preferencias de estilo en CLAUDE.md de antemano:

## shadcn/ui Configuration
- style: default
- base color: slate
- CSS variables: enabled

Configuración de Tailwind CSS v4

v4 funciona diferente a v3. En lugar de tailwind.config.ts, la configuración vive directamente en tu archivo CSS.

/* src/app/globals.css */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.5 0.2 250);
  --font-sans: "Inter", sans-serif;
}

Sin una nota explícita en CLAUDE.md, Claude Code frecuentemente generará archivos de configuración estilo v3. Añade una instrucción clara:

## Tailwind CSS
- Version: v4
- Configuration goes in globals.css under @theme
- Do not create tailwind.config.ts

Configuración de ESLint

// eslint.config.mjs
import { dirname } from "path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({ baseDirectory: __dirname });

export default [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    rules: {
      "@typescript-eslint/no-explicit-any": "error",
      "@typescript-eslint/no-unused-vars": "error",
    },
  },
];

¿Cómo Eliminas el Trabajo Repetitivo con Slash Commands Personalizados?

Claude Code soporta slash commands personalizados. Solo coloca un archivo markdown en .claude/commands/ y estará disponible inmediatamente.

Comando de Generación de Componentes

<!-- .claude/commands/component.md -->
# Generate Component

Create a component named $ARGUMENTS following these rules:
- File: `src/components/$ARGUMENTS.tsx`
- Write in TypeScript
- Match shadcn/ui styling conventions
- Include a Props type definition
- Also generate a Storybook story file (.stories.tsx)

Para usarlo, escribe /component Button en el chat de Claude Code. Listo.

Comando de Generación de Páginas

<!-- .claude/commands/page.md -->
# Generate Page

Create a page for $ARGUMENTS following App Router conventions:
- Create `src/app/$ARGUMENTS/page.tsx`
- Implement as a Server Component
- Include metadata export
- Also generate loading.tsx

Convierte tus patrones más usados en comandos y deja de reescribir las mismas instrucciones cada sesión.

¿Cómo Automatizas Hooks pre-commit y Formateo de Código?

Mantén la calidad del código consistente ejecutando verificaciones automatizadas antes de cada commit.

Configuración de Husky + lint-staged

npm install -D husky lint-staged
npx husky init

Configura .husky/pre-commit:

#!/usr/bin/env sh
npx lint-staged

Añade la configuración de lint-staged a package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,md,json}": [
      "prettier --write"
    ]
  }
}

Para que Claude Code configure esto, añade a CLAUDE.md:

## Automation
- pre-commit: run ESLint and Prettier via husky + lint-staged
- Also check for TypeScript build errors in pre-commit

Configuración de Prettier

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

¿Cómo Completas el Despliegue en Vercel en una Sola Sesión?

Una vez que la configuración está lista, puedes hacer que Claude Code se encargue del despliegue en Vercel también.

Empieza instalando la CLI de Vercel:

npm install -g vercel

Luego dale a Claude Code esta instrucción:

Deploy the current project to Vercel.
- Project name: my-app
- Framework: Next.js
- Use default build settings
- Pull environment variables from .env.local

El comando de despliegue es sencillo:

vercel --prod

Si tienes variables de entorno, añádelas vía dashboard o CLI:

vercel env add NEXT_PUBLIC_API_URL production

Vincula el repositorio de GitHub y cada push a main disparará un despliegue automático a partir de ese momento.

¿Cuáles Son los Patrones de Fallo Comunes y Cómo los Evitas?

CLAUDE.md No Se Está Cargando

CLAUDE.md en la raíz del proyecto se carga automáticamente cuando Claude Code inicia. Sin embargo, si lanzas Claude Code desde un subdirectorio, puede que no se detecte. Siempre inicia claude desde la raíz del proyecto.

Instrucciones Vagas Producen Código Fuera de Objetivo

Frases como "hazlo bonito" o "sigue las mejores prácticas" no se traducen en comportamiento consistente. Escribe instrucciones específicas: "implementar como Server Component en TypeScript strict mode, sin tipos any."

El Contexto Se Desvanece en Sesiones Largas

En sesiones más largas, Claude Code puede parecer "olvidar" reglas establecidas al principio. Verifica si las reglas de CLAUDE.md se siguen cumpliendo, y si notas desviación, di explícitamente: "Por favor revisa esto para seguir las reglas en CLAUDE.md."

Archivos Existentes Siendo Sobrescritos

Claude Code edita archivos proactivamente. Si hay archivos que no quieres que toque, dilo explícitamente en CLAUDE.md:

## Do Not Edit
- `src/styles/design-tokens.css` — design token definitions (do not modify)
- `.env.local` — environment variables (read-only reference)

Artículos Relacionados

• Claude Code × Docker: Configura tu Entorno de Desarrollo — Proyectos Next.js sobre Docker
• Claude Code × TypeScript: Generación de Código Type-Safe — Patrones de componentes Next.js con tipos seguros
• Claude Code: Guía Práctica de Generación de Tests — Automatización de tests después del setup
• Gestión de Contexto en Claude Code: Patrones de Diseño para CLAUDE.md — Técnicas avanzadas de CLAUDE.md
• Claude Code × Prisma: Auto-Genera APIs desde Tu Esquema — Automatización full-stack después del scaffolding
• Claude Code Cheatsheet de Comandos — Referencia completa de comandos integrados y personalizados
• Errores Comunes con Claude Code × Next.js App Router — Evita las trampas después de configurar tu proyecto

FAQ

¿Claude Code soporta Next.js 16 con Turbopack de forma nativa?

Sí. Next.js 16 habilita Turbopack por defecto tanto para desarrollo como para builds de producción. Cuando Claude Code ejecuta create-next-app@latest, el proyecto generado usa Turbopack automáticamente — no se necesitan flags adicionales.

¿Puedo reutilizar una plantilla de CLAUDE.md en varios proyectos?

Por supuesto. Mantén una plantilla base con tu stack tecnológico preferido, reglas de código y estructura de directorios. Cópiala en cada proyecto nuevo y ajusta las secciones específicas. Es la forma más rápida de obtener output consistente de Claude Code en todos tus repositorios.

¿Qué pasa si Claude Code genera configuración de Tailwind v3 en vez de v4?

Esto ocurre cuando CLAUDE.md no especifica la versión de Tailwind explícitamente. Añade una instrucción clara: "Tailwind CSS v4 — la configuración va en globals.css bajo @theme, no crear tailwind.config.ts." Claude Code sigue las reglas explícitas sobre sus defaults de entrenamiento. Revisa la guía de migración de Tailwind CSS v4 para la lista completa de diferencias v3 → v4.

¿Cómo evito que Claude Code sobrescriba archivos que quiero proteger?

Añade una sección "Do Not Edit" a tu CLAUDE.md listando los archivos y directorios protegidos. Claude Code respeta estos límites siempre que se declaren explícitamente. Para mayor seguridad, también puedes usar un archivo .claudeignore para excluir archivos del contexto de Claude Code por completo.

¿Es seguro dejar que Claude Code ejecute vercel --prod directamente?

Claude Code pide permiso antes de ejecutar comandos shell que afectan sistemas externos. Puedes revisar el comando antes de aprobarlo. Dicho esto, para deploys en producción, muchos equipos prefieren conectar su repositorio de GitHub con Vercel y dejar que los pushes a main disparen deploys automáticamente — así mantienes un historial de despliegues trazable y evitas deploys accidentales.

Conclusión

Tres cosas marcan la diferencia al automatizar la configuración de Next.js con Claude Code:

1. Comunica la intención con precisión a través de CLAUDE.md: Define tu stack tecnológico, estructura de directorios y reglas estrictas
2. Elimina el trabajo repetitivo con comandos personalizados: Convierte patrones comunes en slash commands reutilizables
3. Aplica calidad con hooks pre-commit: Automatiza las verificaciones mecánicas antes del code review

Los 30 minutos que inviertes en escribir un CLAUDE.md sólido se recuperan en cada sesión posterior. Guárdalo como plantilla y ajústalo por proyecto — ese es el flujo de trabajo que realmente escala.