Tu asistente de codificación IA abre tu repo por primera vez. Escanea la estructura de archivos, dependencias, tal vez un README. Luego sugiere una configuración de router que rompe tu sistema de layout existente, importa un paquete que deprecaste hace tres sprints, y escribe tests en un estilo que tu equipo abandonó el año pasado. El asistente no es tonto — está ciego. Claude Code, Cursor, Copilot, Cody — cada AI pair-programmer choca con la misma pared: no puede leer el contexto de tu equipo únicamente del historial de commits. Un único archivo CLAUDE.md en la raíz de tu proyecto cambia eso. Es la diferencia entre un asistente que lucha contra tus convenciones y uno que las extiende como un senior dev que lleva meses enviando código contigo. Pero la mayoría de equipos escriben archivos CLAUDE.md que la IA realmente no puede usar.

Si has estado lanzando prompts a Claude Code y obteniendo resultados genéricos, incorrectos o frustrantes, esta guía es para ti. Te desglosare exactamente cómo estructurar tu CLAUDE.md, qué incluir, qué dejar fuera, y compartiré ejemplos reales de proyectos en producción que hemos enviado 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 que Claude Code lee automáticamente cada vez que inicia una sesión. Piénsalo como documentación de onboarding para tu pair programmer IA. Cuando un nuevo desarrollador se une a tu equipo, no solo le pasas una laptop y dices "descúbrelo". Los guías a través de la arquitectura, explicas las partes raras, señalas las minas terrestres. CLAUDE.md hace lo mismo para Claude.

Sin él, Claude Code tiene que inferir todo de tu estructura de archivos, package.json, y todos los archivos que sucede leer. Es como pedirle a un nuevo empleado que entienda todo tu sistema leyendo archivos fuente aleatorios. Acertará algunas cosas, pero también hará suposiciones que desperdician 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. 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 el 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 de directorio
  4. .claude/settings.json — Permisos de herramientas específicos 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ía de tu tiempo. El archivo global es bueno para preferencias personales ("prefiero componentes funcionales" o "siempre usa TypeScript strict mode"), pero el valor real 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 de ventana de contexto limitado. Si tu CLAUDE.md tiene 5,000 palabras de documentación divagada, 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 Archivo CLAUDE.md Excelente

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 las piezas.

## Convenciones Clave
Estándares de codificación, patrones de nombres, reglas de organización de archivos.

## Comandos Comunes
Build, test, deploy, y comandos dev.

## Contexto Importante
Cosas que no son obvias del código.

## Problemas Conocidos / Trampas
Minas terrestres 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 a máximo 2-3 oraciones. Claude no necesita tu roadmap de producto — necesita entender el dominio para que pueda 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 gestionado 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 evita 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 first CSS
- **CMS**: Sanity v3 con vista previa en vivo
- **Despliegue**: Vercel (Entornos Production + Preview)
- **Gestor de Paquetes**: pnpm 9.x
- **Node**: v22 LTS
- **Testing**: Vitest + Playwright
- **Gestión de Estado**: Zustand (minimal, solo para estado IA en cliente)

Arquitectura

Esto 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 IA compartidos (diseño atómico: atoms/, molecules/, organisms/)
- `lib/` — Funciones de utilidad, clientes de API, definiciones de tipo
- `lib/sanity/` — Cliente de Sanity, queries (GROQ), y generación de tipos
- `content/` — Archivos MDX para posts de blog (colocalizados con frontmatter)
- `public/` — Activos estáticos (preferir next/image para todas las imágenes)

Flujo de datos: Sanity CMS → GROQ queries 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 compilación excepto /blog/[slug]/preview que usa modo draft.

Convenciones Clave

Esta sección ahorra la mayoría del tiempo. Sin ella, Claude seguirá mejores prácticas generales que pueden conflictuar con las decisiones de tu equipo.

## Convenciones Clave
- Los componentes se nombran PascalCase, un componente por archivo
- Usa exportaciones nombradas, nunca exportaciones por defecto (excepto pages/layouts)
- Toda obtención de datos ocurre en Server Components — nunca uses useEffect para obtención de datos
- Los tipos de respuesta de API viven en lib/types/ y se auto-generan del esquema de Sanity
- Usa la utilidad `cn()` (lib/utils.ts) para fusión de clases condicionales, no literales de plantilla
- Los límites de error envuelven cada sección de página importante, no la página completa
- Todo 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 sabe los correctos, adivinará, y a menudo adivinará mal.

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

Contexto Importante

Esto es para las cosas que Claude no puede descubrir leyendo tu código. Lógica de negocio, restricciones externas, cosas que tomarían a un revisor humano 30 minutos para 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 pasa por la CDN de Sanity (cdn.sanity.io), no next/image para contenido de CMS.
- La autenticación es manejada por Clerk — nunca construyas flujos de auth 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 con ellas.

## Trampas Conocidas
- El renderizador de texto portable 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 de CSS módulo — usa clases inline en su lugar
- Los rewrites de vercel.json para /docs/* proxyean a nuestro sitio de docs de Mintlify. No modifiques estos sin consultar al equipo.
- Las variables de entorno prefijadas con NEXT_PUBLIC_ son las únicas disponibles en 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 IA.

## NO Hagas
- No instales nuevas dependencias sin preguntar primero
- No uses tipo `any` — encuentra o crea tipos propios
- No crees nuevas rutas de API para cosas que pueden hacerse en Server Components
- No modifiques archivos de esquema 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 clientes, particularmente al construir sitios Next.js con backends de CMS headless.

# Sitio de Marketing Acme

## Descripción General
Sitio de marketing para Acme (acme.com). Construido con Next.js 15, estilizado con Tailwind v4, contenido de 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. Toda obtención de datos en componentes de servidor vía queries GROQ en lib/sanity/queries.ts. Componentes de cliente solo para elementos interactivos (modales, formularios, carruseles).

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

## Convenciones
- Exportaciones nombradas solo (excepto page.tsx/layout.tsx)
- Componentes: PascalCase, uno por archivo
- cn() para fusión de clases
- Esquemas Zod para toda validación de formularios
- No useEffect para obtención de datos. Nunca.

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

## NO Hagas
- Añade "use client" sin justificación
- Instala paquetes sin preguntar
- Usa exportaciones por defecto para componentes
- Modifiques archivos sanity/schema/ sin confirmar migración
- Usa 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 de Tecnología — Astro

## Descripción General
Blog de desarrollador 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 a Cloudflare Pages | Content Collections v2

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

## Reglas Clave
- Por defecto a componentes Astro (.astro). Solo usa React para islas que necesitan 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 propios
- El feed RSS auto-genera de la colección de contenido — no construyas lógica de feed manual

## NO Hagas
- Añade componentes React cuando un componente Astro funcionaría
- Usa directiva client:load
- Omitas dimensiones de imagen (causa CLS)
- Modifiques el esquema de colección de contenido sin actualizar frontmatter existente

Errores Comunes Que Destruyen Tu Contexto IA

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

Error Por Qué Duele Solución
Demasiado largo (2000+ palabras) Quema tokens de ventana de contexto, info clave se pierde Mantén bajo 800 palabras. Enlaza a docs externas para inmersiones profundas.
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 README.md READMEs son para humanos, no contexto de IA Escribe CLAUDE.md desde cero con framing específico de 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 actualizándolo 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 IA

Claude Code no es la única herramienta IA que lee archivos de contexto de proyecto. Aquí está cómo se ve el panorama en 2026:

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

Las buenas noticias: 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 el nombre de archivo y formato menor difieren.

Si tu equipo usa múltiples herramientas IA (y muchos lo hacen en 2026), considera mantener una única fuente de verdad y generar 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 codebases 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 sistema de diseño

El CLAUDE.md raíz cubre arquitectura compartida y convenciones. Cada archivo anidado añade específicos 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 pone 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 versiones (debería ser comprometido). Pero desarrolladores individuales también usan ~/.claude/CLAUDE.md para preferencias personales:

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

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

Midiendo el Impacto

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

  • Precisión de primer intento: ¿Con qué frecuencia la primera respuesta de Claude no necesita 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 codificación. Debería tender hacia cero.
  • Preguntas de contexto: Si Claude sigue preguntando "¿qué framework es este?" o "¿debería usar App Router?", tu CLAUDE.md está perdiendo información.
  • Frecuencia de deshacer: Con qué frecuencia tienes que rechazar o revertir cambios de Claude. Más bajo 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 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 tan importante para la velocidad de desarrollo continuo.

FAQ

¿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 de tu proyecto, convenciones, stack tecnológico, y restricciones. Piénsalo como un documento de onboarding escrito específicamente para tu asistente de codificación IA.

¿Qué tan largo debería ser un archivo CLAUDE.md?

Aiméa a 300-800 palabras. Archivos más cortos pierden contexto crítico, pero algo sobre 1,000 palabras comienza a comerse tu ventana de contexto — espacio mejor usado para razonamiento de código real. Sé conciso y específico. Cada oración debería ganarse su lugar. Si necesitas más profundidad, enlaza a documentación externa en lugar de incrustarla.

¿Debería comprometer CLAUDE.md a control de versiones?

Absolutamente. CLAUDE.md debería ser tratado como cualquier otra documentación de proyecto — versionado, revisado, y mantenido actualizado. Todo tu equipo se beneficia del comportamiento consistente de IA. Las preferencias personales van en ~/.claude/CLAUDE.md en su lugar, que se mantiene local a la máquina de cada desarrollador.

¿Cómo es CLAUDE.md diferente de .cursorrules?

El contenido es casi idéntico — ambos proporcionan contexto de proyecto a una herramienta de codificación IA. La diferencia es qué herramienta lo 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 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-código?

Sí. CLAUDE.md funciona para cualquier proyecto donde interactúas con Claude Code. He visto unos efectivos para repos de documentación, proyectos de infraestructura-como-código, e incluso pipelines 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 debería 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 función Projects para adjuntarlo como archivo de conocimiento. La carga automática de Claude Code es lo que hace el archivo tan poderoso — cero fricción, cada sesión.