CLAUDE.md: la documentación que tu agente lee

Si tu repo no tiene un CLAUDE.md, en 2026 estás perdiendo horas cada semana. No porque la IA no funcione: funciona. Sino porque cada sesión empiezas desde cero explicando lo mismo.

Esta guía explica qué es un CLAUDE.md útil, cómo estructurarlo y qué cosas NO meter (porque saturan el contexto y te tiran la calidad de las respuestas).

Qué es CLAUDE.md

Es un archivo en la raíz del proyecto (o por feature) que tu agente lee automáticamente al abrir el repo. Contiene las reglas, convenciones y prohibiciones que esperas que respete.

No es un README. El README es para humanos que llegan al repo. CLAUDE.md es para el agente que va a escribir código en el repo.

Estructura recomendada

# [Project Name] — Development Guide

## Core Stack

- Lo mínimo imprescindible: framework, DB, auth, package manager

## Critical Rules (NON-NEGOTIABLE)

### 1. Directory Structure

### 2. Import Rules

### 3. Dependency Rules

### 4. Language & Code Style

### 5. No Comments Policy

### 6. No Business Logic in Page Components

## Project Structure

## Decision Tree: Where to Put New Code?

## Anti-Patterns (DO NOT DO THIS)

Cada sección tiene 5-15 líneas, no 5 párrafos. La idea no es enseñar; es recordar.

Reglas que SÍ funcionan en CLAUDE.md

• Concretas y verificables: "no console.log, usa @/lib/errors/logger". El agente puede comprobarlo.
• Con ejemplos cortos del bien y del mal:
  Copiar

  // Wrong
  import { Button } from '@/shared/components/ui';
  // Right
  import { Button } from '@/shared/components/ui/button';

• Prohibiciones explícitas ("NEVER use npm/yarn") más fáciles de seguir que recomendaciones.

Reglas que NO funcionan

• Filosofía abstracta: "escribe código limpio". El agente no sabe qué es eso.
• Reglas que cambian: si tu CLAUDE.md tiene una versión de cada librería, en 6 meses está desfasado y el agente confía.
• Documentación que duplica el README: redundancia que no sirve para nada y consume tokens.

CLAUDE.md por feature

Además del CLAUDE.md raíz, conviene uno por feature en módulos sensibles:

src/features/auth/CLAUDE.md
src/features/payments/CLAUDE.md
src/features/blog/CLAUDE.md

Cada uno con:

• Prohibiciones de seguridad ("NEVER trust user HTML", "ALWAYS sanitize")
• Patrones específicos del módulo
• Estados válidos (ej. draft → published → archived)
• Errores comunes que ya hemos tenido

Así, cuando el agente tocha src/features/blog/, lee también las reglas locales y no tiene que adivinar.

Errores comunes al escribir CLAUDE.md

1. Demasiado largo: si tu CLAUDE.md tiene 800 líneas, el agente lo procesa pero pierde prioridades. Apunta a 200-400 líneas máximo en el raíz.

2. Reglas contradictorias: "siempre usa X" en un sitio, "evita X" en otro. Pasa cuando escribes en distintos momentos. Revísalo entero al añadir.

3. Sin "WHY" en las reglas raras: si dices "no uses Edge runtime", explica brevemente: "Prisma no lo soporta". Sin el porqué, el agente puede saltárselo si parece que la situación es distinta.

4. Confundir README con CLAUDE.md: el README explica qué es el proyecto. CLAUDE.md cómo trabajar dentro del proyecto. No los mezcles.

Cómo iterar tu CLAUDE.md

• Cada vez que el agente comete el mismo error 3 veces: la regla aún no está clara o no existe. Documéntala.
• Cada vez que tienes que repetir lo mismo en un prompt: añádelo a CLAUDE.md.
• Cada release mayor: revisa si las versiones, comandos o convenciones cambiaron.

Conclusión

CLAUDE.md es la diferencia entre un agente que "ayuda a teclear" y un agente que "trabaja en tu repo como si lo conociera de hace meses".

5 minutos al día escribiéndolo te ahorran 30 minutos al día de prompts repetidos. En un mes son horas. En seis, son una feature entera.