Saltar al contenido
Lección 4 de 12

El Contexto Es Todo — CLAUDE.md y Configuracion del Proyecto

8 min read

Por Que el Contexto Determina la Calidad

La IA es un espejo del contexto que le proporcionas. Dale contexto vago e incompleto y obtendras codigo vago e incompleto. Dale contexto preciso y estructurado y obtendras codigo que sigue tus convenciones, coincide con tus patrones y se integra sin problemas con tu base de codigo existente. La diferencia entre un desarrollador 2x y uno 5.7x a menudo se reduce a la ingenieria de contexto -- la habilidad de dar a la IA exactamente la informacion correcta para trabajar de forma autonoma.

Piensalo asi: cuando incorporas a un nuevo desarrollador a tu equipo, no le entregas una laptop y le dices "construye funcionalidades." Le das documentacion, explicas la arquitectura, le muestras las convenciones de codigo y lo guias por el proceso de despliegue. CLAUDE.md es ese documento de incorporacion para la IA.

Anatomia de un CLAUDE.md Efectivo

CLAUDE.md es un archivo markdown en la raiz de tu proyecto que Claude Code lee automaticamente al inicio de cada sesion. Sirve como memoria persistente del proyecto. Aqui esta la estructura que mejor funciona:

# Proyecto: SkyVanguard Web

## Stack Tecnologico
- Next.js 14 con App Router
- TypeScript en modo estricto
- Tailwind CSS con tema personalizado
- MDX para paginas de contenido
- Desplegado en Vercel

## Estructura de Directorios
- /src/app/ — Paginas y rutas de API (App Router)
- /src/components/ — Componentes de UI reutilizables
- /src/content/ — Archivos de contenido MDX (cursos, blog)
- /src/lib/ — Funciones utilitarias y logica compartida
- /src/styles/ — Estilos globales y configuracion de Tailwind
- /public/ — Activos estaticos

## Convenciones de Codigo
- Usar ES modules (import/export), nunca CommonJS
- Preferir server components por defecto, usar "use client" solo cuando sea necesario
- Nombrar componentes en PascalCase, utilidades en camelCase
- Usar conventional commits: feat:, fix:, refactor:, docs:, test:, chore:
- Todo el contenido soporta i18n con pares de archivos .en.mdx y .es.mdx

## Comandos
- `npm run dev` — Iniciar servidor de desarrollo
- `npm run build` — Build de produccion
- `npm run lint` — Ejecutar ESLint
- `npm test` — Ejecutar suite de tests Vitest

## Despliegue
- Push a main activa despliegue en Vercel
- Despliegues de preview en pull requests
- Variables de entorno en el dashboard de Vercel

## Estructura de Contenido
- Los cursos viven en /src/content/courses/{nombre-curso}/
- Cada curso tiene _meta.en.mdx y _meta.es.mdx para metadatos
- Las lecciones estan numeradas: 01-nombre-leccion.en.mdx, 01-nombre-leccion.es.mdx
- El frontmatter incluye: title, description, date, tags, category, order, course

Este archivo tiene aproximadamente 40 lineas y toma 5 minutos escribirlo. Ahorra horas de correcciones e iteraciones en cada sesion.

El 80/20 del Contexto

No todo el contexto es igualmente valioso. Aqui es donde el 20% de la informacion impulsa el 80% de la calidad:

Debe Tener (el 20% que mas importa)

  1. Stack tecnologico con versiones -- "Next.js 14" no solo "Next.js"
  2. Estructura de directorios -- Donde viven las cosas y patrones de nombres
  3. Convenciones de codigo -- Los patrones que la IA debe seguir
  4. Comandos clave -- Como construir, probar y desplegar

Bueno Tener

  1. Decisiones de arquitectura -- Por que elegiste ciertos patrones
  2. Problemas conocidos -- Cosas que la IA debe evitar
  3. Integraciones de terceros -- APIs y servicios en uso

Generalmente No Necesario

  1. Documentacion completa de API -- La IA puede leer el codigo
  2. Explicaciones detalladas de logica de negocio -- Mejor manejadas por tarea
  3. Decisiones historicas -- El contexto relevante va en los prompts de tarea

Sobrecargar CLAUDE.md con demasiada informacion puede realmente perjudicar el rendimiento. Mantenlo enfocado en lo que la IA necesita para escribir codigo correcto en el primer intento.

Contexto con Alcance de Directorio

Para proyectos grandes, un solo CLAUDE.md en la raiz puede no ser suficiente. Claude Code soporta archivos CLAUDE.md anidados que proporcionan contexto especifico para un subdirectorio:

proyecto/
  CLAUDE.md              # Contexto global del proyecto
  src/
    api/
      CLAUDE.md          # Patrones y convenciones especificos de API
    components/
      CLAUDE.md          # Guias de la biblioteca de componentes
    content/
      CLAUDE.md          # Reglas de formato de contenido

Ejemplo de un CLAUDE.md con alcance de directorio para un directorio de API:

# Rutas de API

## Patrones
- Todas las rutas exportan GET, POST, PUT, DELETE como funciones nombradas
- Usar esquemas zod para validacion de solicitudes
- Retornar NextResponse.json() con formato de error consistente
- Incluir middleware de rate limiting en endpoints de mutacion

## Formato de Error
{
  "error": "Mensaje legible para humanos",
  "code": "CODIGO_LEGIBLE_PARA_MAQUINA",
  "status": 400
}

## Autenticacion
- Usar getServerSession() de next-auth
- Proteger todas las rutas excepto /api/public/*

Cuando Claude Code trabaja en el directorio src/api/, lee tanto el CLAUDE.md raiz como el local. Esto le da conocimiento general del proyecto mas convenciones especificas de API.

Manteniendo el Contexto Actualizado

Un CLAUDE.md desactualizado es peor que no tener CLAUDE.md porque ensena a la IA patrones obsoletos. Construye el habito de actualizarlo:

Disparadores de actualizacion:

  • Despues de agregar una nueva dependencia importante
  • Despues de cambiar la estructura de directorios
  • Despues de establecer una nueva convencion
  • Despues de cambiar el proceso de build o despliegue
  • Despues de resolver un problema recurrente causado por contexto desactualizado

Un enfoque practico es agregar actualizaciones de CLAUDE.md a tu definicion de "hecho" para funcionalidades importantes. Desplegaste un nuevo patron de API? Actualiza las convenciones de API. Migraste la base de datos? Actualiza la seccion de comandos.

# Haz las actualizaciones de CLAUDE.md parte de tu flujo de trabajo
claude "Acabamos de migrar de Prisma a Drizzle ORM. Actualiza CLAUDE.md
       para reflejar las nuevas herramientas de base de datos, comandos
       y patrones."

La Ventana de Contexto: Entendiendo los Limites

Claude Code tiene una ventana de contexto que contiene toda la conversacion mas los archivos del proyecto que lee. A medida que las sesiones crecen, el contexto mas antiguo se comprime o se descarta. Entender esto te ayuda a trabajar mas efectivamente:

Gestionando sesiones largas:

# Cuando el contexto se hace grande, compacta la conversacion
/compact

# Esto resume el historial de la conversacion, liberando espacio
# de contexto para nuevo trabajo mientras preserva decisiones clave

Estrategias para eficiencia de contexto:

  • Mantén CLAUDE.md conciso -- se lee en cada interaccion
  • Usa /compact despues de completar una funcionalidad importante antes de empezar la siguiente
  • Para sesiones muy largas, considera iniciar una nueva sesion con una descripcion clara de lo que ya se logro
  • Referencia archivos especificos por ruta en lugar de pegar su contenido en la conversacion

Ejemplo Real: Un CLAUDE.md de Produccion

Aqui hay una version condensada de un CLAUDE.md que permite a Claude trabajar autonomamente en un proyecto real de Next.js con internacionalizacion, modo oscuro y gestion de contenido:

# SkyVanguard Web

## Stack
Next.js 14, TypeScript strict, Tailwind CSS, MDX, Vercel

## Estructura
/src/app/[locale]/ — rutas i18n (en, es)
/src/components/ — Componentes compartidos
/src/content/courses/ — Archivos MDX de cursos
/src/content/blog/ — Archivos MDX de blog
/src/lib/i18n.ts — Utilidades de traduccion
/src/styles/globals.css — Tailwind base + estilos personalizados

## Convenciones
- Server components por defecto, "use client" cuando sea necesario
- Solo ES modules, solo async/await
- Conventional commits (feat:, fix:, refactor:)
- Todo el contenido bilingue: pares .en.mdx + .es.mdx
- Variante dark: de Tailwind para modo oscuro (next-themes)

## Frontmatter de Contenido
Cursos: title, description, date, tags, category, order, course
Blog: title, description, date, tags, category
Meta: title, description, date, tags, category, level

## Comandos
dev: npm run dev
build: npm run build
lint: npm run lint

Esto son 25 lineas. Le da a Claude todo lo que necesita para crear nuevos cursos, agregar funcionalidades, corregir bugs y mantener consistencia en todo el proyecto. Cuando ves a un desarrollador entregando 12 proyectos en una semana, este tipo de configuracion de contexto es la infraestructura invisible que lo hace posible.

Ejercicio Practico

Antes de pasar a la siguiente leccion, crea o actualiza tu CLAUDE.md:

  1. Empieza con tu stack tecnologico y versiones
  2. Documenta tu estructura de directorios
  3. Lista tus 3-5 convenciones de codigo mas importantes
  4. Agrega los comandos para build, test y deploy
  5. Incluye cualquier patron de contenido o nombres de archivos

Pruebalo iniciando una nueva sesion de Claude Code y pidiendole crear una funcionalidad pequena. Si las convenciones son correctas en el primer intento, tu contexto esta funcionando. Si necesita correcciones, agrega esas correcciones a CLAUDE.md para que no vuelvan a ocurrir.