# CLAUDE.md: cómo configurar instrucciones para Claude Code

> Cómo configurar correctamente el archivo CLAUDE.md para Claude Code: niveles de configuración, convenciones de código, secciones Gotchas y Never Do, y la regla del segundo aviso.

**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:

:::tabs
=== Raíz del proyecto (CLAUDE.md)
```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
```
=== Carpeta del proyecto (.claude/CLAUDE.md)
```markdown
# Scoped Project Rules

- Location: .claude/CLAUDE.md
- Applies to all contributors of this repository
- Versioned in Git alongside codebase
- Overrides any user-level global preferences
```
=== Archivo global (~/.claude/CLAUDE.md)
```markdown
# Global User Preferences

### Coding Style
- Prefer functional patterns over OOP classes
- Always write explicit error handling with typed errors
- Keep functions short (under 30 lines where possible)

### Git
- Use lowercase commit messages
- Conventional commits: feat:, fix:, chore:, docs:, refactor:
- Never push directly to main/master branch
```
:::

### Resolución de conflictos

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

> [!IMPORTANT]
> **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.` |

> [!TIP]
> 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 }
    );
  }
}
```
```

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
```

> [!WARNING]
> 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
```

> [!TIP]
> 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

> [!TIP]
> **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

> [!TIP]
> **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

> [!TIP]
> **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

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