¡Deja de dejar que Claude escriba código a ciegas! Un archivo de configuración eleva la precisión un 10%

Cuando usas Claude Code en un proyecto existente, a veces interpreta mal el stack: en un proyecto React aparecen patrones de Vue, la documentación dice TypeScript y el resultado es JavaScript puro. CLAUDE.md es el archivo de configuración en la raíz del proyecto pensado para evitar ese desajuste de contexto.

En un backend Node me pasó lo siguiente: Claude reescribió middleware basado en Koa como si fuera Express y toda la cadena dejó de funcionar. En las pruebas de Anthropic, un CLAUDE.md bien configurado suele elevar la precisión de codificación un 5%-10%. Estas 7 prácticas las fui afinando después de tropezar; cada sección incluye ejemplos que puedes copiar tal cual.

Qué es CLAUDE.md

En pocas palabras, CLAUDE.md es un archivo Markdown en la raíz del proyecto que guía a Claude Code sobre cómo entender tu proyecto. Es similar a .editorconfig o README.md, pero con un objetivo más concreto: decirle a la IA cómo ayudarte a escribir código.

El mecanismo es directo: cuando usas Claude Code en el proyecto, lee este archivo automáticamente. Aunque la documentación oficial habla de carga automática, la experiencia de la comunidad recomienda ejecutar /init una vez para asegurarte de que la IA ya «leyó» tu configuración. El contenido se carga en la memoria de contexto y afecta toda la generación de código y las sugerencias posteriores.

Aquí entra una característica clave: Claude Code admite configuración jerárquica:

project-root/
├── CLAUDE.md              # Configuración global (todo el proyecto)
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # Configuración específica del frontend
└── backend/
    └── .claude/
        └── CLAUDE.md     # Configuración específica del backend

Puedes definir reglas generales en la raíz y sobrescribir reglas concretas en submódulos. Por ejemplo, React en frontend y Node.js en backend, cada uno con su propia configuración.

Cuatro principios clave

Antes de escribir CLAUDE.md, recuerda estos cuatro principios. Al principio no los tuve en cuenta y escribí un archivo «épico» de más de 300 líneas; el rendimiento de Claude empeoró.

1. Concisión: el principio de las 100 líneas

Sinceramente, esto lo aprendí a base de errores. CLAUDE.md no es un README; no hace falta un tratado.

¿Por qué ser conciso? Técnicamente, la ventana de contexto de Claude es grande, pero CLAUDE.md consume cuota de tokens. Cuanto más largo sea el archivo, menos tokens quedan para analizar código real. Según Arize AI, los archivos de menos de 100 líneas funcionan mejor.

❌ Ejemplo incorrecto (verboso y repetitivo):

# Introducción del proyecto
Este es un proyecto frontend basado en React. Usamos React para construir la interfaz.
React es una librería JavaScript desarrollada por Facebook... (200 palabras más sobre React)
# Stack tecnológico
Nuestro stack incluye:
- React - Es nuestro framework de UI, versión 18.2...
- TypeScript - Lo usamos para comprobación de tipos...

✅ Ejemplo correcto (directo y compacto):

# Stack tecnológico
- React 18.2 (Hooks primero, evitar componentes Class)
- TypeScript (modo estricto)
- TailwindCSS (utilities primero)
# Convenciones de código
- Componentes funcionales + Hooks personalizados
- Desestructuración de props
- Preferir const, evitar let

¿Ves la diferencia? La segunda versión transmite la misma información (o más) con mucho menos ruido.

2. Especificidad: habla claro, sin vaguedades

Suena simple, pero es fácil fallar.

❌ Ejemplo incorrecto (demasiado vago):

# Estilo de código
- Mantener el código limpio
- Seguir mejores prácticas
- Cuidar el rendimiento

Eso equivale a no escribir nada. ¿Qué es «limpio»? ¿Qué son «mejores prácticas»? La IA no puede ejecutarlo.

✅ Ejemplo correcto (concreto y verificable):

# Estilo de código
- Una función no debe superar 50 líneas; si lo hace, dividirla
- Las llamadas API deben incluir manejo de errores y estado loading
- En listas renderizadas, siempre usar key con ID, no index
- Evitar ternarios anidados; usar if/else o early return

Ahora la IA sabe qué hacer. Cada regla es explícita y comprobable.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

3. Iterabilidad: no tengas miedo de cambiarlo

He visto desarrolladores escribir CLAUDE.md al inicio del proyecto y no tocarlo en seis meses. El proyecto migró de Vue 2 a Vue 3 y el archivo seguía diciendo «usar Options API».

Actualización rápida con #: una de mis técnicas favoritas. En Claude Code, pulsa # para referenciar y editar CLAUDE.md al vuelo. Si la IA no se comporta como esperas, corrige la configuración de inmediato.

Escenario real: la semana pasada Claude generaba código con axios, pero el equipo ya había unificado fetch + un wrapper propio. Pulsé # y añadí una línea en CLAUDE.md:

# Peticiones HTTP
- Usar siempre el fetch encapsulado en `src/utils/request.ts`
- Prohibido axios o fetch nativo directo

Después de guardar, Claude no volvió a cometer ese error.

4. Compartir en equipo: incluirlo en control de versiones

Muchos lo pasan por alto. CLAUDE.md debe ir al repositorio Git, con la misma importancia que .gitignore.

¿Por qué? Porque representa el consenso de codificación del equipo. Si cada uno tiene una versión distinta, la IA generará estilos diferentes para cada persona y el caos es inevitable.

# No ignorar CLAUDE.md en .gitignore
# ❌ Incorrecto
*.md
# ✅ Correcto
*.md
!CLAUDE.md
!README.md

Y revisa los cambios de CLAUDE.md en Code Review. Si alguien modifica la configuración, todo el equipo debe enterarse.

"La configuración debe ser concisa y específica; menos de 100 líneas funciona mejor. Cada regla debe ser ejecutable y verificable."

Los 5 módulos que debes incluir

Este es el mínimo viable que resumo tras usar CLAUDE.md en proyectos reales. Sin estos módulos, el archivo aporta poco.

1. Declaración del stack tecnológico

Lista explícitamente frameworks, librerías y versiones. Es lo más básico.

# Stack tecnológico
**Frontend**
- Next.js 14 (App Router)
- React 18 (Server Components primero)
- TypeScript 5.2
- Tailwind CSS 3.4
**Backend**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

Fíjate en las versiones. Sin ellas, Claude puede usar APIs antiguas. Next.js 13 y 14 difieren mucho en routing; no especificar versión es arriesgado.

2. Estructura del proyecto

Explica cómo organizas los archivos para que la IA los coloque donde corresponde.

# Estructura del proyecto
src/
├── app/              # Rutas de páginas Next.js
├── components/       # Componentes UI reutilizables
│   ├── ui/          # Componentes base (Button, Input)
│   └── features/    # Componentes de negocio (UserCard, OrderList)
├── lib/             # Utilidades y hooks
├── services/        # Capa de llamadas API
└── types/           # Definiciones TypeScript
# Convención de nombres
- Componentes: PascalCase (UserProfile.tsx)
- Utilidades: camelCase (formatDate.ts)
- Constantes: UPPER_SNAKE_CASE (API_BASE_URL)

Con esto, Claude sabe que un nuevo componente de tarjeta de usuario va en components/features/UserCard.tsx, no en cualquier carpeta.

3. Comandos habituales

A menudo se ignora, pero es muy útil.

# Comandos de desarrollo
npm run dev          # Servidor de desarrollo (localhost:3000)
npm run build        # Build de producción
npm run test         # Ejecutar tests Jest
npm run lint         # Comprobación ESLint
npm run type-check   # Comprobación de tipos TypeScript
# Base de datos
npx prisma studio    # GUI de base de datos
npx prisma migrate dev  # Ejecutar migraciones

¿Por qué incluirlos? A veces Claude necesita verificar código o ejecutar tests; los comandos correctos evitan muchos problemas.

4. Convenciones de estilo de código

Aquí está lo importante: sé lo bastante específico.

# Convenciones de código
## Componentes React
- Componentes funcionales + Hooks; prohibidos componentes Class
- Tipos de props encima del componente, usar interface en lugar de type
- Orden interno: definición de props → función del componente → export
## Gestión de estado
- Estado local: useState/useReducer
- Estado del servidor: TanStack Query
- Estado global: Zustand (evitar Context)
## Manejo de errores
- Llamadas API siempre con try-catch
- Errores visibles al usuario con toast
- console.error en desarrollo, reporte a Sentry en producción

5. Flujo de trabajo y restricciones

Indica qué puede y qué no puede hacer la IA.

# Flujo de trabajo
- Nueva funcionalidad: tipos primero → componente → tests
- Corregir bug: test de reproducción → fix → verificar tests
# Restricciones
- ❌ No modificar `/prisma/schema.prisma` (requiere revisión del equipo)
- ❌ No instalar dependencias nuevas (discutir en review de package.json)
- ❌ No modificar `/lib/auth/*` (lógica de autenticación sensible)
- ✅ Libre modificación de código de negocio en `/components` y `/app`

Evita que la IA «ayude de más» y toque código crítico por error.

7 técnicas prácticas que multiplican el efecto

Técnica 1: usar SHOULD/MUST para prioridades

No todas las reglas tienen el mismo peso. Usa palabras clave para distinguir prioridades.

# Prioridad de reglas
**MUST (obligatorio)**
- MUST usar TypeScript en modo estricto
- MUST añadir manejo de errores a todas las APIs
**SHOULD (recomendado)**
- SHOULD componentes de menos de 200 líneas
- SHOULD extraer lógica repetida a Hooks personalizados
**COULD (opcional)**
- COULD añadir comentarios JSDoc

Esta técnica viene de documentos RFC. Tras usarla, Claude cumple las reglas «MUST» con mucha más rigidez.

Técnica 2: aprovechar el comando /init

Aunque la documentación dice que CLAUDE.md se carga solo, recomiendo ejecutar /init cada vez que abras el proyecto.

Tú: /init
Claude: Configuración cargada. Stack actual: React 18 + TypeScript...

Es como «refrescar» la memoria de la IA. Tras modificar CLAUDE.md, /init hace que el cambio surta efecto de inmediato.

Técnica 3: el código de ejemplo vale más que mil palabras

En lugar de describir reglas, muestra ejemplos.

❌ Solo texto:

- Las funciones API deben incluir tipos, manejo de errores y estado loading

✅ Con código de ejemplo:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

# Convención de llamadas API
Referencia:
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
Todas las funciones API siguen este patrón: tipo de retorno + try-catch + log de errores

Tras ver el ejemplo, el código generado se acerca mucho a lo que esperas.

Técnica 4: configuración en capas (imprescindible en Monorepo)

Si tu proyecto es un Monorepo, usa configuración jerárquica.

monorepo-root/
├── CLAUDE.md                    # Global: convenciones comunes, flujo Git
├── apps/
│   ├── web/
│   │   └── .claude/CLAUDE.md   # Web: React + Next.js
│   └── mobile/
│       └── .claude/CLAUDE.md   # Móvil: React Native
└── packages/
    └── shared/
        └── .claude/CLAUDE.md   # Paquete compartido: utilidades TS puras

CLAUDE.md raíz (convenciones globales):

# Convenciones generales del Monorepo
- Usar pnpm como gestor de paquetes
- Configuración TypeScript unificada heredada de tsconfig.json raíz
- Commits según Conventional Commits
# Flujo de trabajo
- Ejecutar `pnpm install` antes de modificar código
- Ejecutar `pnpm run lint` en todos los paquetes antes de commit

apps/web/.claude/CLAUDE.md (específico del frontend):

# Configuración de la aplicación web
Hereda convenciones raíz; configuración adicional:
- Stack: Next.js 14 + React 18
- Estilos: Tailwind CSS
- Estado: Zustand

Claude lee primero la raíz y luego la subconfiguración según tu directorio de trabajo. No repites convenciones comunes en cada subproyecto.

Técnica 5: contraste con ❌ y ✅

Tanto humanos como IA aprendemos bien con contrastes.

# Convención de actualización de estado
❌ Incorrecto: mutar state directamente
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
user.age = 31; // ¡Error! mutación directa del objeto
\`\`\`
✅ Correcto: actualización inmutable
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
setUser(prev => ({...prev, age: 31}));
\`\`\`

El contraste hace las reglas evidentes y acelera el aprendizaje de Claude.

Técnica 6: documentar patrones de error frecuentes

Anota errores habituales del equipo para que la IA los evite.

# ⚠️ Errores frecuentes y cómo evitarlos
## 1. Olvidar limpiar efectos secundarios
❌ Código problemático:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  // ¡Sin cleanup!
}, []);
\`\`\`
✅ Forma correcta:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer); // limpiar timer
}, []);
\`\`\`
## 2. Dependencias faltantes
Si ESLint avisa de dependencias faltantes, no desactives la regla: añade la dependencia o optimiza con useCallback/useMemo

Con esto, Claude evita activamente esas trampas al generar código.

Técnica 7: enlazar a documentación detallada

CLAUDE.md debe ser breve, pero puede apuntar a docs extensas.

# Documentación detallada
- [Guía de diseño API](./docs/api-guidelines.md) - Estándares RESTful
- [Guía de componentes](./docs/component-guide.md) - División y reutilización
- [Normas de testing](./docs/testing.md) - Unitarios e integración

Mantiene CLAUDE.md conciso y permite profundizar cuando haga falta. Claude puede seguir esos enlaces para más contexto.

5 trampas que más cuesta evitar

Trampa 1: archivo demasiado largo con todo metido

El error más común de principiantes: meter README, docs de API y lógica de negocio en CLAUDE.md.

Problema: consume demasiados tokens y diluye lo importante.

Solución: mantenerlo en menos de 100 líneas; solo lo que la IA necesita al codificar.

Trampa 2: nunca actualizar la configuración

El proyecto evoluciona; CLAUDE.md queda congelado.

Problema: reglas obsoletas generan código incorrecto.

Solución: actualizar tras cada refactor importante y revisar cambios en el PR.

Trampa 3: olvidar el control de versiones

Añadir CLAUDE.md a .gitignore o no subirlo al repositorio.

Problema: cada miembro con reglas distintas y estilos inconsistentes.

Solución: incluirlo en Git y revisarlo como cualquier otro código.

Trampa 4: reglas demasiado genéricas

Escribir «mantener código limpio» o «seguir mejores prácticas».

Problema: la IA no puede ejecutarlo; es como no escribir nada.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Solución: cada regla debe ser concreta, verificable y ejecutable.

Trampa 5: filtrar información sensible

Meter claves API o contraseñas de base de datos en CLAUDE.md.

Problema: el archivo va al repositorio y expone secretos.

Solución: describir cómo configurar, no los valores reales.

❌ Incorrecto
\`\`\`markdown
# Configuración de base de datos
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
\`\`\`
✅ Correcto
\`\`\`markdown
# Variables de entorno
- DATABASE_URL: leer de .env.local, formato en .env.example
- API_KEY: desde variable de entorno; en local, contactar al equipo para clave de prueba
\`\`\`

3 casos reales de proyectos

Caso 1: proyecto frontend React

Configuración simplificada de un ecommerce frontend que mantengo:

# Proyecto ecommerce frontend
## Stack tecnológico
- Next.js 14.0 (App Router)
- React 18.2
- TypeScript 5.2
- Tailwind CSS 3.4
- Zustand (estado)
- TanStack Query (estado del servidor)
## Estructura
src/
├── app/          # Rutas de páginas
├── components/   # Componentes
│   ├── ui/      # Componentes base
│   └── features/ # Componentes de negocio
├── lib/         # Utilidades
└── services/    # Llamadas API
## Convenciones
- Componentes: funcionales + Hooks
- Estado: useState local, Zustand global, TanStack Query servidor
- Estilos: utilities Tailwind; layouts complejos como componentes
- Errores: try-catch obligatorio en APIs
## Comandos
npm run dev      # Servidor de desarrollo
npm run build    # Build de producción
npm run lint     # Lint
## Restricciones
- No modificar /lib/auth/* (autenticación)
- No instalar paquetes nuevos (discutir en equipo)

Resultado: la estructura de componentes que genera Claude coincide con la que escribo a mano; ahorro mucho tiempo de ajuste.

Caso 2: proyecto backend Node.js

Configuración de una API Express:

# API de gestión de pedidos
## Stack tecnológico
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15
- Zod (validación)
## Estructura
src/
├── routes/       # Definición de rutas
├── controllers/  # Lógica de negocio
├── services/     # Operaciones de base de datos
├── middleware/   # Middleware
└── utils/        # Utilidades
## Convenciones
- Toda API: validación (Zod) + manejo de errores + logging
- Operaciones DB solo en capa services
- Controllers solo request/response, sin lógica de negocio
- async/await, evitar callbacks
## Ejemplo API
\`\`\`typescript
// controllers/order.controller.ts
export async function createOrder(req: Request, res: Response) {
  try {
    const data = orderSchema.parse(req.body); // validación Zod
    const order = await orderService.create(data);
    logger.info('Order created', { orderId: order.id });
    res.json({ success: true, data: order });
  } catch (error) {
    logger.error('Create order failed', error);
    res.status(500).json({ success: false, error: 'Internal error' });
  }
}
\`\`\`
## Comandos
npm run dev       # Desarrollo (nodemon)
npm run build     # Compilación TypeScript
npm test          # Tests Jest
npx prisma studio # GUI de base de datos

Resultado: los endpoints que genera Claude incluyen validación Zod y manejo de errores; la calidad sube de forma clara.

Caso 3: arquitectura Monorepo

Proyecto full stack en Monorepo:

CLAUDE.md raíz:

# Monorepo full stack
## Arquitectura
- pnpm workspaces
- apps/: aplicaciones
- packages/: paquetes compartidos
## Convenciones generales
- TypeScript modo estricto
- ESLint + Prettier unificados
- Commits Conventional Commits
## Comandos
pnpm install           # Instalar todas las dependencias
pnpm run dev           # Arrancar frontend y backend
pnpm run lint          # Lint en todos los paquetes
pnpm --filter web dev  # Solo aplicación web

apps/web/.claude/CLAUDE.md:

# Configuración web
Hereda convenciones raíz
- Next.js 14 + React
- Puerto: 3000
- Detalle en CLAUDE.md raíz

apps/api/.claude/CLAUDE.md:

# Configuración API
Hereda convenciones raíz
- Express + Prisma
- Puerto: 4000
- Detalle en CLAUDE.md raíz

Resultado: Claude cambia de contexto según el directorio: React en frontend, Express en backend.

Conclusión: optimiza tu CLAUDE.md desde hoy

Tras estas 7 técnicas, ya tienes una idea clara de cómo escribir CLAUDE.md. Recuerda tres puntos:

1. Mantén la concisión — menos de 100 líneas, solo lo necesario
2. Sé específico — cada regla ejecutable y verificable
3. Actualiza con frecuencia — el proyecto cambia, la configuración también

En mi experiencia, un buen CLAUDE.md eleva la eficiencia de la IA al menos un 30%. No hace falta escribirlo todo de una vez: empieza por el stack y añade una regla cada vez que la IA se equivoque.

Abre tu proyecto y crea o mejora tu CLAUDE.md. Si aún no usas Claude Code, este archivo es el primer paso. Si ya lo usas pero los resultados no convencen, prueba las técnicas de hoy.

Un aviso final: CLAUDE.md no es trabajo de una sola vez; debe crecer con el proyecto. Tras cada refactor importante, upgrade de stack o cambio de convenciones, actualízalo. Que la IA entienda de verdad tu proyecto empieza por un buen CLAUDE.md.