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

Le pedí a Claude Code que "creara un proyecto Next.js," y lo que recibí tenía TypeScript configurado tan libremente que escupía errores de tipo por todas partes. Este es el registro de cómo descubrí exactamente qué poner en CLAUDE.md para obtener el resultado que realmente quería.

"La IA generó código descuidado" es un problema que se soluciona con mejores instrucciones. Este artículo recorre todo, desde escribir CLAUDE.md, hasta el scaffolding automatizado con create-next-app, comandos personalizados, hooks pre-commit y desplegar 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
• 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 15+ (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 "@/*"

La clave aquí es que Claude Code pase flags explícitos a create-next-app. Ejecutarlo interactivamente puede hacer que Claude Code se quede esperando input.

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)

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.