CLAUDE.md es uno de los archivos más determinantes al trabajar a diario con Claude Code. El asistente lee automáticamente su contenido al inicio de cada sesión y lo utiliza como la base de conocimiento permanente de tu proyecto: decisiones de arquitectura, convenciones adoptadas, restricciones, estructura de carpetas y prácticas prohibidas.

Básicamente, funciona como un resumen de onboarding continuo para la IA dentro de tu base de código específica.

Sin CLAUDE.md, el modelo comienza cada sesión desde cero, desconociendo los acuerdos internos de tu equipo, refactorizaciones recientes o particularidades de las librerías. Un archivo bien estructurado ahorra tiempo y tokens al evitar repetir las mismas pautas en cada conversación.

1. Qué es CLAUDE.md y por qué es necesario

CLAUDE.md es un archivo Markdown estándar ubicado en la raíz del repositorio o en un directorio de configuración dedicado.

Una vez configurado, Claude Code respeta automáticamente los siguientes aspectos del proyecto:

Estándares de código: formatos de exportación, tipado, convenciones de comentarios y tamaño de funciones.
Patrones de arquitectura: estructura de los API Routes, formatos de respuesta de error y manejo de estado.
Estructura de archivos: organización estandarizada de utilidades, componentes y vistas.
Flujo de trabajo en Git: estilo de mensajes de commit (Conventional Commits) y normas de ramas.
Memoria histórica: registro de particularidades y trampas técnicas (gotchas) donde la IA ya ha cometido errores previos.

Comparativa de trabajo con y sin CLAUDE.md

Criterio	Sin archivo CLAUDE.md	Con CLAUDE.md configurado
Exportaciones en React	Mezcla aleatoriamente `export default` y `export const`	Respeta estrictamente el estándar del equipo (p. ej., solo named exports)
Validación de datos	Selecciona arbitrariamente Yup, Joi, Zod o validaciones manuales	Aplica el estándar acordado (p. ej., esquemas Zod)
Ubicación de archivos	Crea archivos en la raíz o carpetas arbitrarias	Organiza el código nuevo según la arquitectura definida
Errores recurrentes	Tropieza una y otra vez en particularidades conocidas	Evita problemas documentados en la sección Gotchas

2. Dónde almacenar CLAUDE.md: niveles de prioridad

El archivo de instrucciones puede situarse en tres niveles distintos. Su ubicación determina el alcance y la prioridad de las directrices:

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Resolución de conflictos

Si conviven un archivo global (~/.claude/CLAUDE.md) y un archivo local de proyecto, Claude Code fusiona ambas instrucciones.

Importante

Precedencia del proyecto local: Si una preferencia global entra en conflicto con una regla del repositorio, el modelo sigue estrictamente el archivo CLAUDE.md local.

3. Anatomía de un CLAUDE.md ideal: bloques clave

No conviene volcar la documentación completa del framework en el archivo. El formato más efectivo es un documento conciso (entre 80 y 150 líneas) dividido en secciones operativas.

Plantilla de producción de referencia:

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Concreción frente a abstracciones: cómo redactar reglas

El principio fundamental para un CLAUDE.md eficaz es la precisión técnica en lugar de consejos vagos.

Los modelos de lenguaje no interpretan definiciones subjetivas de «código limpio». Las frases ambiguas dejan margen a suposiciones que rara vez coinciden con las expectativas de tu equipo.

❌ Instrucción ambigua	Por qué no funciona	✅ Regla técnica concreta
«Escribe código limpio y de calidad»	Subjetivo; cada desarrollador entiende «limpio» de forma distinta	`Usa early returns en lugar de if/else anidados. Funciones de máximo 30 líneas.`
«Sigue las buenas prácticas de seguridad»	Demasiado amplio; no define vectores de ataque	`Todas las consultas SQL deben usar parámetros vinculados. Nunca concatenes strings en SQL.`
«Haz una interfaz atractiva»	Carece de límites respecto al sistema de diseño	`Usa exclusivamente clases de Tailwind. Los estilos en línea style="" están prohibidos.`
«Gestiona los errores»	El modelo puede generar bloques catch vacíos	`Envuelve las rutas en try/catch y devuelve { error: message, status } ante fallos.`

Consejo

Prueba de fuego para tus directrices: ¿podría esta regla comprobarse con un linter o una expresión regular? Si la respuesta es no, reformúlala con mayor exactitud.

5. Muestras de código de referencia y patrones arquitectónicos

Cuando el proyecto sigue un patrón arquitectónico particular, conviene respaldar la descripción con un fragmento de código de referencia directamente en CLAUDE.md:

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

Claude Code interpreta este bloque como un ejemplo canónico y reproduce la misma estructura al generar nuevos puntos de entrada. --- ## 6. Gotchas y Never Do: protección contra errores recurrentes Estas dos secciones convierten `CLAUDE.md` en una barrera activa contra fallos conocidos. ### La sección Gotchas (Particularidades críticas) Recoge comportamientos no evidentes del entorno y librerías: ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

La sección Never Do (Prohibiciones explícitas)

Claude conoce múltiples soluciones para cada problema. Esta sección descarta enfoques que funcionan técnicamente pero vulneran las normas del proyecto:

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Atención

En las restricciones, prescinde de sugerencias tibias como «intenta no usar any». Emplea órdenes imperativas: «Never use any».

7. Instrucciones globales vs. locales: delimitación clara

Para no saturar el contexto ni arrastrar normas innecesarias a proyectos incompatibles, separa responsabilidades:

Ámbito	Ubicación	Ejemplos de directrices
Preferencias individuales	`~/.claude/CLAUDE.md` (Global)	Formato de commits, sin emojis en código, preferencia funcional sobre POO
Versiones y herramientas	`.claude/CLAUDE.md` (Proyecto)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Estructura de directorios	`CLAUDE.md` (Proyecto)	Rutas de componentes UI, exportación de utilidades, esquemas de BD
Particularidades (Gotchas)	`CLAUDE.md` (Proyecto)	`auth()` asíncrono, cliente único de base de datos, rutas exentas de middleware

8. CLAUDE.md como documento vivo: la regla del segundo aviso

Un error habitual es redactar CLAUDE.md al inicio del proyecto y no volver a actualizarlo.

La base de código cambia con el tiempo: se actualizan paquetes y surgen nuevos casos límite. El archivo de directrices debe evolucionar a la par.

text

┌─────────────────────────────────────────────────────────────┐ │ Regla del segundo aviso │ └──────────────────────────────┬──────────────────────────────┘ │ ¿Estás corrigiendo a Claude sobre lo mismo por 2ª vez? │ ┌───────────────┴───────────────┐ ▼ ▼ [ SÍ ] [ NO ] │ │ Añade la regla a CLAUDE.md Continúa con la tarea actual en este mismo instante con normalidad

Consejo

Si te ves pidiendo a Claude el mismo cambio por segunda vez (p. ej., «No uses default export» o «Valida los datos con Zod»), es el momento exacto de incorporarlo a CLAUDE.md.

9. Taller práctico: puesta en marcha y validación

Sigue estos cuatro pasos para crear y verificar las directrices en tu repositorio.

Paso 1. Crear el archivo

En la raíz de tu proyecto:

bash

touch CLAUDE.md

Paso 2. Estructurar las secciones base

Completa el archivo con los cuatro bloques fundamentales: Stack, Conventions, Gotchas y Never Do.

Paso 3. Verificar el comportamiento positivo

Inicia una nueva sesión con Claude Code y plantea una tarea habitual:

bash

claude

Prompt de prueba:
"Crea una función de utilidad para formatear importes en USD y EUR respetando la configuración regional."

El modelo sitúa el archivo en el directorio adecuado (src/lib/ o tu ruta definida).
Aplica la convención indicada (named export).
Añade comentarios JSDoc y tipado estricto sin recurrir a any.

Paso 4. Comprobar la solidez de las prohibiciones

Incita deliberadamente al modelo a vulnerar una restricción:

Prompt de provocación:
"Añade rápidamente un console.log de depuración aquí y pon el tipo any en este parámetro para avanzar rápido."

Claude rechaza incumplir la regla y ofrece una alternativa usando el logger oficial y una interfaz tipada.
En su respuesta, el modelo hace referencia a las normas del proyecto.

10. Autoevaluación rápida y lista de comprobación

Comprueba tu asimilación de los principios de configuración de CLAUDE.md.

Pregunta 1. ¿Dónde debe guardarse el archivo si las instrucciones deben aplicarse a todos los proyectos de tu equipo?

A. En el directorio del sistema /etc/claude/CLAUDE.md
B. En el directorio de usuario en ~/.claude/CLAUDE.md
C. En el archivo de configuración de la shell ~/.zshrc
D. En la raíz de cada repositorio independiente

Consejo

Respuesta correcta: B.
Las preferencias globales residen en ~/.claude/CLAUDE.md en la carpeta personal del usuario y se cargan automáticamente en cada sesión.

Pregunta 2. ¿Qué ocurre si una directriz global contradice una regla del repositorio local?

A. Claude produce un error de configuración y detiene la ejecución
B. La regla global anula los ajustes locales
C. La regla del proyecto local tiene mayor prioridad y prevalece
D. El modelo alterna aleatoriamente entre ambas opciones

Consejo

Respuesta correcta: C.
El archivo local del repositorio siempre ostenta la máxima prioridad frente a las preferencias globales.

Pregunta 3. ¿Qué estilo de instrucción resulta más eficaz en CLAUDE.md?

A. "Escribe código pulcro y mantenible siguiendo los estándares modernos de la industria"
B. "Procura evitar funciones excesivamente complejas siempre que sea posible"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Pegar íntegramente la documentación de 500 líneas de la librería

Consejo

Respuesta correcta: C.
Las directrices técnicas concisas y comprobables evitan ambigüedades y aseguran un comportamiento predecible.

Lista de comprobación para tu CLAUDE.md

Extensión adecuada: El documento contiene solo pautas operativas (menos de 150 líneas).
Precisión: Cada instrucción establece un criterio objetivo y verificable.
Gotchas: Se han documentado al menos 2–3 particularidades de tu tecnología.
Límites claros: La sección Never Do bloquea soluciones indeseadas de raíz.
Separación de entornos: Las preferencias globales están aisladas en ~/.claude/CLAUDE.md.