He estado usando Claude Code diariamente desde principios de 2025, y puedo decirte que el factor más importante para obtener resultados útiles no es la ingeniería de prompts ni trucos inteligentes. Es el contexto. Específicamente, es un archivo CLAUDE.md bien escrito en la raíz de tu proyecto. Este único archivo es la diferencia entre un asistente de IA que lucha contra tu base de código y uno que se siente como un desarrollador senior que ha estado en tu equipo durante meses.

Si has estado lanzando prompts a Claude Code y obteniendo resultados genéricos, incorrectos o frustrantes, esta guía es para ti. Te desglosaremos exactamente cómo estructurar tu CLAUDE.md, qué incluir, qué dejar fuera, y te compartiremos ejemplos reales de proyectos en producción que hemos entregado en Social Animal.

Tabla de Contenidos

Qué es CLAUDE.md y por qué importa

CLAUDE.md es un archivo markdown que colocas en la raíz de tu repositorio y que Claude Code lee automáticamente cada vez que inicia una sesión. Piénsalo como documentación de incorporación para tu programador en pareja de IA. Cuando un nuevo desarrollador se une a tu equipo, no solo le entregas una laptop y dices "averígüalo". Lo guías a través de la arquitectura, explicas las partes raras, señalas los puntos de peligro. CLAUDE.md hace lo mismo para Claude.

Sin él, Claude Code tiene que inferir todo a partir de tu estructura de archivos, package.json, y cualquier archivo que suceda leer. Es como pedirle a un nuevo empleado que entienda todo tu sistema leyendo archivos de código al azar. Acertará en algunas cosas, pero también hará suposiciones que desperdiciarán el tiempo de todos.

Con un CLAUDE.md sólido, he visto la precisión de finalización de tareas saltar de aproximadamente 60% a más del 90% en primeros intentos. Eso no es una mejora pequeña — es la diferencia entre el desarrollo asistido por IA siendo un multiplicador de productividad y ser un sumidero de tiempo frustrante.

Cómo Claude Code lee el contexto de tu proyecto

Claude Code tiene una jerarquía específica para cargar contexto. Entender esto importa porque afecta cómo organizas tu memoria de proyecto.

El orden de carga de contexto

  1. ~/.claude/CLAUDE.md — Tus preferencias globales (aplicadas a cada proyecto)
  2. ./CLAUDE.md — El archivo a nivel de proyecto en la raíz de tu repo
  3. ./subdirectory/CLAUDE.md — Anulaciones específicas del directorio
  4. .claude/settings.json — Permisos de herramientas específicas del proyecto y configuración
  5. Contexto de sesión — Lo que le dices a Claude en la conversación actual

El CLAUDE.md a nivel de proyecto es donde pasarás la mayor parte del tiempo. El archivo global es bueno para preferencias personales ("Prefiero componentes funcionales" o "siempre usa TypeScript strict mode"), pero el verdadero valor está en el contexto por proyecto.

Aquí está lo crucial: Claude Code lee el CLAUDE.md al inicio de cada sesión, pero también tiene espacio limitado de ventana de contexto. Si tu CLAUDE.md tiene 5.000 palabras de documentación divagante, estás quemando tokens que podrían usarse para razonamiento de código real. Sé conciso. Sé específico. Cada línea debe ganarse su lugar.

La anatomía de un excelente archivo CLAUDE.md

Después de escribir y refinar archivos CLAUDE.md en docenas de proyectos — aplicaciones Next.js, sitios Astro, integraciones de CMS headless, servicios de API — he llegado a una estructura consistente que funciona.

La estructura ideal

# Nombre del Proyecto

## Descripción general
Un párrafo explicando qué hace este proyecto y para quién.

## Stack tecnológico
Versiones exactas y frameworks.

## Arquitectura
Cómo encajan los componentes.

## Convenciones clave
Estándares de código, patrones de nombres, reglas de organización de archivos.

## Comandos comunes
Comandos de build, test, deploy y dev.

## Contexto importante
Cosas que no son obvias desde el código.

## Problemas conocidos / Trampas
Puntos de peligro a evitar.

## No hagas
Cosas explícitas que la IA nunca debe hacer.

Vamos a profundizar en cada sección.

Desglose sección por sección

Descripción general

Mantén esto en máximo 2-3 oraciones. Claude no necesita tu roadmap de producto — necesita entender el dominio para tomar decisiones contextualmente apropiadas.

## Descripción general
Este es el sitio de marketing para Acme Corp, una plataforma SaaS B2B para gestión de cadena de suministro. El sitio se genera estáticamente con rutas de API dinámicas para manejo de formularios y captura de leads. El contenido es administrado a través de Sanity CMS por el equipo de marketing.

Stack tecnológico

Sé exacto. No solo digas "React" — especifica la versión, el framework, la estrategia de renderizado. Esto previene que Claude sugiera patrones que funcionan en React 18 pero se rompen en React 19, o recomiende Pages Router cuando estás en App Router.

## Stack tecnológico
- **Framework**: Next.js 15.1 (App Router, RSC por defecto)
- **Lenguaje**: TypeScript 5.7 (modo strict)
- **Estilos**: Tailwind CSS v4 con configuración CSS-first
- **CMS**: Sanity v3 con vista previa en vivo
- **Deployment**: Vercel (entornos Production + Preview)
- **Gestor de paquetes**: pnpm 9.x
- **Node**: v22 LTS
- **Testing**: Vitest + Playwright
- **Gestión de estado**: Zustand (mínimo, solo para estado de UI del cliente)

Arquitectura

Aquí es donde la mayoría de personas escriben demasiado poco o demasiado. No estás escribiendo un documento de diseño de sistema. Estás dándole a Claude un modelo mental.

## Arquitectura
- `app/` — Páginas y layouts de Next.js App Router
- `app/api/` — Rutas de API (envíos de formularios, webhooks)
- `components/` — Componentes de UI compartidos (diseño atómico: atoms/, molecules/, organisms/)
- `lib/` — Funciones de utilidad, clientes de API, definiciones de tipos
- `lib/sanity/` — Cliente de Sanity, consultas (GROQ), y generación de tipos
- `content/` — Archivos MDX para posts de blog (colocados con frontmatter)
- `public/` — Activos estáticos (prefiere next/image para todas las imágenes)

Flujo de datos: Sanity CMS → consultas GROQ en lib/sanity/queries.ts → Server Components → Client Components (solo cuando se necesita interactividad)

Todas las páginas se generan estáticamente en tiempo de build excepto /blog/[slug]/preview que usa draft mode.

Convenciones clave

Esta sección ahorra más tiempo. Sin ella, Claude seguirá mejores prácticas generales que pueden entrar en conflicto con las elecciones de tu equipo.

## Convenciones clave
- Los componentes se nombran en PascalCase, un componente por archivo
- Usa named exports, nunca default exports (excepto pages/layouts)
- Todo el fetching de datos ocurre en Server Components — nunca uses useEffect para data fetching
- Los tipos de respuesta de API viven en lib/types/ y se auto-generan desde el schema de Sanity
- Usa utilidad `cn()` (lib/utils.ts) para fusión condicional de clases, no template literals
- Error boundaries envuelven cada sección de página importante, no toda la página
- Todo el manejo de formularios usa react-hook-form + esquemas de validación zod
- Los mensajes de commit siguen Conventional Commits (feat:, fix:, chore:)

Comandos comunes

Esto parece básico, pero Claude Code realmente ejecuta estos comandos. Si no conoce los correctos, adivinará, y frecuentemente adivinará mal.

## Comandos comunes
- `pnpm dev` — Inicia servidor de desarrollo (puerto 3000)
- `pnpm build` — Build de producción
- `pnpm lint` — Verificación de ESLint + Prettier
- `pnpm test` — Ejecuta pruebas unitarias de Vitest
- `pnpm test:e2e` — Ejecuta pruebas E2E de Playwright
- `pnpm sanity:typegen` — Regenera tipos de Sanity después de cambios de schema
- `pnpm db:migrate` — Ejecuta migraciones de Drizzle ORM

Contexto importante

Esto es para lo que Claude no puede descubrir leyendo tu código. Lógica de negocio, restricciones externas, cosas que tomaría 30 minutos a un revisor humano explicar.

## Contexto importante
- Usamos ISR (revalidate: 3600) para todas las páginas de CMS. Nunca uses `force-dynamic` a menos que sea absolutamente necesario.
- El webhook de Sanity en /api/revalidate maneja revalidación bajo demanda — no añadas lógica de revalidación manual.
- La optimización de imágenes va a través del CDN de Sanity (cdn.sanity.io), no next/image para contenido de CMS.
- La autenticación es manejada por Clerk — nunca construyas flujos de autenticación personalizados.
- El endpoint /api/leads tiene rate limiting vía Upstash Redis. No elimines el middleware de rate limit.

Trampas conocidas

Cada proyecto tiene cosas raras. Ponlas aquí para que Claude no tropiece.

## Trampas conocidas
- El renderizador de portable text de Sanity tiene un bug con listas anidadas en v3.2. Usamos un serializador personalizado en components/portable-text/list-fix.tsx
- Tailwind v4 no soporta la directiva `@apply` en archivos CSS módulo — usa clases inline en su lugar
- Los rewrites en vercel.json para /docs/* hacen proxy a nuestro sitio de docs de Mintlify. No modifiques estos sin verificar con el equipo.
- Las variables de entorno con prefijo NEXT_PUBLIC_ son las únicas disponibles del lado del cliente. Nunca expongas secretos de API de esta forma.

La sección "No hagas"

Esta es posiblemente la sección más importante. Las instrucciones negativas son increíblemente efectivas con modelos de IA.

## No hagas
- No instales nuevas dependencias sin preguntar primero
- No uses tipo `any` — encuentra o crea tipos apropiados
- No crees nuevas rutas de API para cosas que pueden hacerse en Server Components
- No modifiques los archivos del schema de Sanity sin confirmar el plan de migración
- No uses `"use client"` a menos que el componente genuinamente necesite APIs del navegador o manejadores de eventos
- No escribas archivos CSS — todo son clases de utilidad de Tailwind
- No hardcodees strings que deberían venir del CMS

Ejemplos reales de CLAUDE.md

Ejemplo: Sitio de marketing Next.js

Esta es una versión simplificada de un CLAUDE.md que usamos en proyectos de cliente, particularmente cuando se construyen sitios Next.js con backends de CMS headless.

# Sitio de marketing de Acme

## Descripción general
Sitio web de marketing para Acme (acme.com). Construido con Next.js 15, estilizado con Tailwind v4, contenido desde Sanity CMS. Objetivo: LCP sub-2s en todas las páginas.

## Stack tecnológico
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## Arquitectura
App Router con RSC. Todo el data fetching en server components vía consultas GROQ en lib/sanity/queries.ts. Client components solo para elementos interactivos (modales, formularios, carruseles).

Páginas: / (inicio), /about, /pricing, /blog, /blog/[slug], /contact

## Convenciones
- Solo named exports (excepto page.tsx/layout.tsx)
- Componentes: PascalCase, uno por archivo
- cn() para fusión de clases
- Esquemas Zod para toda validación de formularios
- Sin useEffect para data fetching. Nunca.

## Comandos
pnpm dev | pnpm build | pnpm lint | pnpm test

## No hagas
- Añadas "use client" sin justificación
- Instales paquetes sin preguntar
- Uses default exports para componentes
- Modifiques sanity/schema/ sin confirmar migración
- Uses tipo any

Ejemplo: Sitio de contenido Astro

Para proyectos Astro, el CLAUDE.md se ve un poco diferente porque el paradigma de arquitectura es diferente.

# Blog técnico — Astro

## Descripción general
Blog de desarrolladores con 500+ artículos. Static-first, cero JS por defecto. MDX para contenido con componentes personalizados.

## Stack tecnológico
Astro 5.x | MDX | Tailwind v4 | Desplegado en Cloudflare Pages | Content Collections v2

## Arquitectura
src/content/ — Artículos MDX con frontmatter validado con Zod
src/components/ — Componentes Astro (cero JS) e islas React (interactivos)
src/layouts/ — Layouts base
src/pages/ — Enrutamiento basado en archivos

## Reglas clave
- Por defecto usa componentes Astro (.astro). Solo usa React para islas que necesiten interactividad.
- client:visible para componentes interactivos below-fold
- client:idle para componentes interactivos no críticos
- Nunca uses client:load a menos que sea absolutamente necesario
- Todas las imágenes usan el componente Image de Astro con width/height apropiados
- El feed RSS se auto-genera desde content collection — no construyas lógica de feed manual

## No hagas
- Añadas componentes React cuando un componente Astro funcionaría
- Uses directiva client:load
- Omitas dimensiones de imagen (causa CLS)
- Modifiques el schema de content collection sin actualizar frontmatter existente

Errores comunes que arruinan tu contexto de IA

He revisado muchos archivos CLAUDE.md en este punto. Aquí están los patrones que consistentemente llevan a resultados malos.

Error Por qué daña Solución
Demasiado largo (2000+ palabras) Quema tokens de ventana de contexto, la info clave se pierde Mantén bajo 800 palabras. Vincula a docs externas para análisis profundos.
Demasiado vago ("usamos React") Claude llena los vacíos con suposiciones Sé específico: versiones, patrones, herramientas exactas
Sin instrucciones negativas Claude hace cosas "razonables" que rompen tus convenciones Siempre incluye una sección "No hagas"
Copy-pasting de README.md Los READMEs son para humanos, no contexto de IA Escribe CLAUDE.md desde cero con framing específico para IA
Incluyendo datos sensibles Claves de API, secretos en archivos de contexto Nunca pongas secretos en CLAUDE.md. Referencia .env.example en su lugar
Nunca actualizarlo El proyecto evoluciona, el archivo de contexto no Revisa CLAUDE.md cada sprint o refactor mayor
Instrucciones contradictorias "Usa server components" + ejemplos con useEffect fetching Que una persona sea dueña del archivo, revisa por consistencia

CLAUDE.md vs otros archivos de contexto de IA

Claude Code no es la única herramienta de IA que lee archivos de contexto de proyecto. Así se ve el panorama en 2025:

Archivo Herramienta Auto-lectura Alcance
CLAUDE.md Claude Code Sí, al inicio de sesión A nivel de proyecto
.cursorrules Cursor Sí, al abrir archivo A nivel de proyecto
.github/copilot-instructions.md GitHub Copilot Sí, en Copilot Chat A nivel de repo
.windsurfrules Windsurf (Codeium) Sí A nivel de proyecto
AGENTS.md OpenAI Codex CLI Sí A nivel de proyecto
.ai/context.md Convención personalizada No (referencia manual) Varía

La buena noticia: la mayoría del contenido es transferible. Si escribes un CLAUDE.md sólido, convertirlo a .cursorrules o copilot-instructions.md toma unos 5 minutos. La estructura e información son las mismas — solo cambian el nombre del archivo y el formato menor.

Si tu equipo usa múltiples herramientas de IA (y muchos lo hacen en 2025), considera mantener una única fuente de verdad y genera los archivos específicos de herramienta desde ella. Un simple script de build puede copiar tu archivo de contexto maestro a todos los lugares correctos.

Patrones avanzados para proyectos grandes

Archivos CLAUDE.md anidados

Para monorepos o bases de código grandes, puedes colocar archivos CLAUDE.md en subdirectorios. Claude Code leerá el más específico para el directorio en el que estés trabajando.

project/
├── CLAUDE.md              # Contexto global del proyecto
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Contexto específico de app web
│   └── api/
│       └── CLAUDE.md      # Contexto específico de API
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Contexto del design system

El CLAUDE.md raíz cubre arquitectura compartida y convenciones. Cada archivo anidado añade especificidades para ese paquete.

Contexto dinámico con /compact

El comando /compact de Claude Code resume la conversación actual y libera espacio de contexto. Para sesiones largas, he encontrado un patrón que funciona bien:

  1. Comienza con CLAUDE.md cargado automáticamente
  2. Trabaja en una característica
  3. Ejecuta /compact cuando el contexto se ponga pesado
  4. Continúa — Claude retiene el contexto de CLAUDE.md más un resumen comprimido

Contexto compartido por equipo vs Personal

Mantenemos CLAUDE.md en control de versión (debe ser commiteado). Pero los desarrolladores individuales también usan ~/.claude/CLAUDE.md para preferencias personales:

# Preferencias personales
- Prefiero nombres de variables verbosos sobre abreviaturas
- Muéstrame el razonamiento antes de escribir código
- Cuando sugieras cambios, muestra el diff completo del archivo
- Uso VS Code con keybindings de Vim (no sugieras atajos específicos del IDE)

Esta separación mantiene el archivo del equipo limpio y enfocado en hechos del proyecto mientras deja que los individuos personalicen su experiencia.

Midiendo el impacto

¿Cómo sabes que tu CLAUDE.md está funcionando? Aquí hay métricas que rastreamos internamente:

  • Precisión de primer intento: ¿Con qué frecuencia la primera respuesta de Claude necesita cero correcciones? Un buen CLAUDE.md consigue esto por encima del 80%.
  • Violaciones de convención: Cuenta cuántas veces Claude rompe tus estándares de código. Debería tender hacia cero.
  • Preguntas de contexto: Si Claude sigue preguntando "¿qué framework es este?" o "¿debería usar App Router?", a tu CLAUDE.md le falta información.
  • Frecuencia de deshacer: Con qué frecuencia tienes que rechazar o revertir cambios de Claude. Menor es mejor.

Un equipo en una startup de tamaño medio reportó reducir su tiempo promedio de tarea asistida por IA de 12 minutos a 4 minutos después de invertir una hora en su CLAUDE.md. Esa es una mejora de 3x desde un único archivo.

Si estás construyendo un proyecto con nosotros a través de nuestros servicios de desarrollo de CMS headless, incluimos un CLAUDE.md personalizado como parte de cada entrega de proyecto. Es así de importante para la velocidad de desarrollo continuo.

Preguntas frecuentes

¿Qué es CLAUDE.md y dónde va? CLAUDE.md es un archivo markdown colocado en la raíz de tu repositorio de proyecto. Claude Code lo lee automáticamente al inicio de cada sesión para entender la arquitectura, convenciones, stack tecnológico y restricciones de tu proyecto. Piénsalo como un documento de incorporación escrito específicamente para tu asistente de codificación de IA.

¿Cuánto tiempo debe tener un archivo CLAUDE.md? Apunta a 300-800 palabras. Los archivos más cortos pierden contexto crítico, pero cualquier cosa sobre 1.000 palabras comienza a consumir tu ventana de contexto — espacio que se usa mejor para razonamiento de código real. Sé conciso y específico. Cada oración debe ganarse su lugar. Si necesitas más profundidad, vincula a documentación externa en lugar de incrustarla.

¿Debo hacer commit de CLAUDE.md al control de versión? Absolutamente. CLAUDE.md debe tratarse como cualquier otra documentación de proyecto — versionada, revisada, y mantenida actualizada. Todo tu equipo se beneficia del comportamiento consistente de IA. Las preferencias personales van a ~/.claude/CLAUDE.md en su lugar, que permanece local en la máquina de cada desarrollador.

¿Cuál es la diferencia entre CLAUDE.md y .cursorrules? El contenido es casi idéntico — ambos proporcionan contexto de proyecto a una herramienta de IA de codificación. La diferencia es cuál herramienta los lee. CLAUDE.md es para Claude Code (herramienta CLI de Anthropic), mientras que .cursorrules es para Cursor IDE. Si usas ambas herramientas, mantén una única fuente de verdad y cópiala a ambos archivos, ajustando para cualquier formato específico de herramienta.

¿Cuál es la sección más importante de un CLAUDE.md? La sección "No hagas". Las instrucciones negativas son desproporcionadamente efectivas con modelos de IA. Decirle a Claude qué evitar — no uses tipos any, no añadas "use client" innecesariamente, no instales nuevos paquetes sin preguntar — previene los errores más comunes y frustrantes. Una buena lista de prohibiciones ahorra más tiempo que páginas de instrucciones positivas.

¿Puedo usar CLAUDE.md para proyectos no de código? Sí. CLAUDE.md funciona para cualquier proyecto donde interactúes con Claude Code. He visto unos efectivos para repos de documentación, proyectos de infraestructura como código, e incluso tuberías de análisis de datos. El principio es el mismo: dale a Claude el contexto que necesita para tomar buenas decisiones sobre tu proyecto específico.

¿Con qué frecuencia debo actualizar mi CLAUDE.md? Revísalo en cada refactor mayor y al menos una vez por sprint. Si actualizas una versión de framework, cambias una dependencia clave, o adoptas una nueva convención, actualiza el archivo inmediatamente. El contexto obsoleto es peor que ningún contexto porque activamente engaña a la IA. Algunos equipos añaden una revisión de CLAUDE.md a su checklist de PR para cambios de infraestructura.

¿Funciona CLAUDE.md con Claude en la web (claude.ai)? No. CLAUDE.md es específicamente leído por Claude Code, la herramienta de codificación basada en CLI. Si estás usando Claude a través de la interfaz web o API, necesitarías pegar el contexto manualmente o usar la característica de Projects para adjuntarlo como un archivo de conocimiento. La carga automática de Claude Code es lo que hace el archivo tan poderoso — cero fricción, cada sesión.