Image for post CLAUDE.md Masterclass: El Archivo que Controla el 80% de tu Productividad con Claude Code

CLAUDE.md Masterclass: El Archivo que Controla el 80% de tu Productividad con Claude Code

Escrito por Sergio Márquez

La semana pasada un companero me envio un mensaje frustrante: "Claude Code me ignora las instrucciones de estilo, sigue creando archivos que no le pido y los commits no siguen nuestra convencion". Le pedi que me mostrara su CLAUDE.md. Tenia 3,200 lineas. Ahi estaba el problema.

Despues de reducirlo a 180 lineas bien estructuradas, Claude Code empezo a respetar cada regla como si le hubieran cambiado el cerebro. No era magia: era contexto limpio.

Por que CLAUDE.md es tu palanca de productividad mas importante

CLAUDE.md es un archivo Markdown que Claude Code lee automaticamente al inicio de cada sesion. Contiene las instrucciones persistentes de tu proyecto: convenciones de codigo, comandos frecuentes, arquitectura, reglas de testing y todo lo que normalmente repetirias en cada prompt.

Sin el, cada sesion empieza desde cero. Con el bien configurado, Claude ya sabe como trabaja tu equipo antes de que escribas la primera palabra. En mi experiencia, 10 minutos de configuracion ahorran horas de correcciones repetitivas cada semana.

Pero hay un matiz critico que mucha gente ignora: un CLAUDE.md inflado es peor que no tener ninguno. Cuando el archivo es demasiado largo, las instrucciones se pierden en el ruido y Claude empieza a ignorar reglas que estan escritas explicitamente.

Conceptos clave antes de empezar

¿Que es la jerarquia de archivos CLAUDE.md?

Claude Code no lee un solo archivo. Lee una cadena completa de archivos CLAUDE.md en distintos niveles, y todos se combinan de forma aditiva:

  • Global (~/.claude/CLAUDE.md): preferencias personales que aplican a todos tus proyectos.
  • Raiz del proyecto (./CLAUDE.md): convenciones compartidas con tu equipo. Se commitea a git.
  • Local (./CLAUDE.local.md): preferencias privadas por proyecto. Se agrega automaticamente a .gitignore.
  • Subdirectorios (./frontend/CLAUDE.md): instrucciones especificas de un componente. Se cargan bajo demanda cuando Claude accede a archivos en ese directorio.

Cuando hay conflictos entre niveles, las instrucciones mas especificas toman precedencia. Esto es fundamental para monorepos.

¿Que es Auto Memory (MEMORY.md)?

Auto Memory es una funcionalidad donde Claude escribe notas para si mismo sobre patrones descubiertos, errores frecuentes y preferencias detectadas durante las sesiones. Se almacena en ~/.claude/projects/<proyecto>/memory/MEMORY.md.

A diferencia de CLAUDE.md (que tu escribes para Claude), MEMORY.md es lo que Claude escribe para si mismo. Las primeras 200 lineas se cargan automaticamente en cada sesion. Si no ves esta funcionalidad, puedes activarla con la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=0.

¿Que son las Skills y cuando usarlas en lugar de CLAUDE.md?

Las Skills son bloques de conocimiento especializado que Claude carga bajo demanda. CLAUDE.md se carga siempre; las Skills solo cuando son relevantes. La regla es simple: si una instruccion aplica al 80% de tus sesiones, va en CLAUDE.md. Si solo aplica a un tipo especifico de tarea, va en una Skill.

Anatomia de un CLAUDE.md efectivo: paso a paso

Voy a mostrarte como construir un CLAUDE.md desde cero para un proyecto real. Usare como ejemplo un backend en Python con FastAPI, que es el stack que uso en produccion.

Paso 1: Generar la base con /init

Ejecuta /init en Claude Code. Esto analiza tu proyecto y genera un CLAUDE.md inicial basado en tu estructura de archivos, package.json o pyproject.toml, y patrones detectados.

# Dentro de tu proyecto, en Claude Code:
/init

El resultado sera un archivo con comandos basicos y estructura detectada. Usalo como punto de partida, no como producto final. En mi caso, el /init genero 40 lineas utiles y 20 que no necesitaba. Borre las 20 sobrantes.

Paso 2: Definir las reglas criticas primero

Las primeras lineas de CLAUDE.md tienen el mayor peso. Coloca ahi lo que Claude no puede ignorar bajo ninguna circunstancia.

# Proyecto: api-pagos

## Reglas Criticas
IMPORTANT: Nunca crear archivos .md a menos que se solicite explicitamente.
IMPORTANT: No hacer auto-commit. Solo commitear cuando se confirme.
IMPORTANT: Todos los commits en ingles, sin mencionar IA.

## Stack
- Python 3.12, FastAPI, Poetry, ruff, mypy strict
- Base de datos: PostgreSQL 16 con SQLAlchemy 2.0
- Tests: pytest con cobertura minima 80%

## Comandos Frecuentes
- Tests: `poetry run pytest -x --tb=short`
- Lint: `poetry run ruff check .`
- Tipos: `poetry run mypy src/`
- Servidor: `poetry run uvicorn src.main:app --reload`

Nota el uso de "IMPORTANT:" como prefijo. Investigaciones de la comunidad muestran que enfatizar instrucciones criticas mejora la adherencia, aunque no es infalible. En sesiones largas, el contexto se degrada y hasta las reglas enfatizadas pueden ignorarse.

Paso 3: Agregar convenciones de codigo

## Convenciones de Codigo
- Imports: stdlib > third-party > local (separados por linea en blanco)
- Naming: snake_case para funciones/variables, PascalCase para clases
- Comentarios explican "por que", no "que"
- Fail fast: validar inputs al inicio de cada funcion
- Variables de entorno para secrets (nunca hardcoded)

## Estructura de Archivos
src/
  domain/       # Entidades y reglas de negocio
  application/  # Casos de uso
  infrastructure/  # Repos, clients externos
  api/          # Routers FastAPI
tests/
  unit/
  integration/

Paso 4: Definir el workflow esperado

## Workflow
1. Explorar: leer archivos, entender contexto (sin escribir codigo)
2. Planificar: Plan Mode para cambios multi-archivo
3. Codigo: TDD - tests primero, luego implementacion
4. Verificar: ejecutar tests y lint antes de considerar completo

## Prioridad de Decisiones
Correctitud > Simplicidad > Mantenibilidad > Performance

## Guardrails
- No agregar features "por si acaso"
- No crear abstracciones para un solo uso
- Preferir librerias maduras sobre codigo custom

Paso 5: Incluir la seccion de errores conocidos

Esta es la seccion que mas valor aporta con el tiempo. Cada vez que Claude comete un error recurrente en tu proyecto, agregalo aqui.

## Errores Conocidos
- SQLAlchemy: usar `select()` en lugar de `query()` (estilo 2.0)
- FastAPI: los path params van antes que los query params en la firma
- Poetry: no usar `pip install`, siempre `poetry add`
- Tests: fixtures de DB usan scope="function", nunca "session"

En mi proyecto de pagos, esta seccion empezo con 3 items y ahora tiene 12. Cada uno representa un bug que Claude habria repetido sin esta guia.

Optimizacion avanzada: lo que separa a los usuarios casuales de los productivos

La regla de las 500 lineas

Si tu CLAUDE.md supera las 500 lineas, estas causando context bloat. Un desarrollador de la comunidad redujo su archivo de 47,000 a 9,000 palabras en un monorepo y reporto que Claude paso de ignorar instrucciones a seguirlas consistentemente.

Para cada linea, hazte la pregunta: "¿Si elimino esto, Claude cometeria un error?" Si la respuesta es no, eliminala.

Imports con @: organizacion sin reducir carga

CLAUDE.md soporta importar otros archivos con la sintaxis @ruta/al/archivo:

# Contexto adicional
- Arquitectura: @docs/architecture.md
- API contracts: @docs/api-spec.md

Pero atencion: los archivos importados con @ se cargan en memoria al inicio, igual que el contenido inline. Esto mejora la organizacion pero no reduce el consumo de contexto. Si necesitas carga diferida real, referencia el archivo sin @ y deja que Claude lo lea cuando lo necesite:

## Referencias (cargar solo cuando sea necesario)
- Guia de testing detallada: ver `docs/testing-guide.md`
- Patrones de migracion: ver `docs/migrations.md`

Skills: el complemento perfecto para CLAUDE.md

Investigaciones recientes de la comunidad muestran que la tasa de activacion de Skills depende dramaticamente de como se nombran y describen. Una descripcion generica activa la Skill el 19% de las veces. Una descripcion optimizada con keywords explicitas y ejemplos de cuando usarla alcanza el 84%.

Ejemplo de una Skill bien descrita en .claude/skills/database-migrations.md:

---
name: database-migrations
description: >
  Guia para crear y ejecutar migraciones de base de datos con Alembic.
  ACTIVAR cuando: "migration", "alembic", "schema change", "alter table",
  "nueva tabla", "agregar columna".
  USAR PARA: crear migraciones, revisar migraciones, rollback de schema.
---

# Migraciones con Alembic

## Crear nueva migracion
poetry run alembic revision --autogenerate -m "descripcion_del_cambio"

## Aplicar migraciones
poetry run alembic upgrade head

## Revertir ultima migracion
poetry run alembic downgrade -1

Las Skills usan aproximadamente 100 tokens durante el escaneo de metadata y menos de 5,000 tokens cuando se activan. Es mucho mas eficiente que incluir esta informacion en CLAUDE.md para cada sesion.

La tecla # para memorias rapidas

Durante una sesion, puedes presionar la tecla # para agregar una instruccion directamente a CLAUDE.md sin interrumpir tu flujo de trabajo. Es ideal para capturar patrones en el momento exacto en que los descubres.

Caso real: monorepo con frontend y backend

En un proyecto con React en el frontend y FastAPI en el backend, organice los archivos asi:

mi-proyecto/
├── CLAUDE.md              # Convenciones globales (git, CI, standards)
├── CLAUDE.local.md        # Mi configuracion personal (no va a git)
├── frontend/
│   └── CLAUDE.md          # React, TypeScript, Tailwind
├── backend/
│   └── CLAUDE.md          # FastAPI, SQLAlchemy, Alembic
└── .claude/
    ├── commands/
    │   └── deploy.md      # Comando /deploy personalizado
    └── skills/
        └── db-migrations.md

El CLAUDE.md raiz tiene 90 lineas. El de frontend tiene 45. El de backend tiene 60. Total: menos de 200 lineas distribuidas inteligentemente. Cuando trabajo en el frontend, Claude no carga las instrucciones del backend y viceversa.

El resultado concreto: en dos semanas de uso, la cantidad de correcciones manuales que le pedia a Claude bajo de 8-10 por sesion a 1-2. No es ciencia exacta, pero la diferencia fue notable.

En Produccion

Lo que cambia entre un CLAUDE.md de tutorial y uno de produccion real:

  • Version control obligatorio: CLAUDE.md va en git. Tu equipo debe poder contribuir y revisar cambios como cualquier otro archivo de configuracion. Usa CLAUDE.local.md para preferencias personales.
  • Revision periodica: cada 2-3 semanas, pide a Claude que revise tu CLAUDE.md y sugiera mejoras. Las instrucciones se acumulan, algunas se vuelven obsoletas, otras se contradicen.
  • Degradacion de contexto: en sesiones largas (30+ minutos de conversacion continua), las reglas de CLAUDE.md pierden efectividad. Usa /clear entre tareas no relacionadas y /compact cuando el contexto se sature.
  • Agent Teams (febrero 2026): si usas Agent Teams, ten en cuenta que multiples agentes comparten el mismo directorio de memoria. A febrero 2026, no hay mecanismo de locking, lo que puede causar conflictos de escritura en MEMORY.md. Un issue de GitHub (#24130) esta abierto con propuestas de solucion.
  • Auto Memory no reemplaza CLAUDE.md: MEMORY.md es complementario. Claude escribe ahi lo que descubre; tu escribes en CLAUDE.md lo que Claude debe saber de antemano. No delegues tus convenciones criticas a la memoria automatica.

Errores comunes y depuracion

Error: Claude ignora reglas que estan claramente escritas en CLAUDE.md.
Causa: el archivo es demasiado largo y las instrucciones se diluyen en el contexto.
Solucion: reducir a menos de 500 lineas. Mover contenido especializado a Skills.

Error: las instrucciones de un subdirectorio no se aplican.
Causa: los CLAUDE.md de subdirectorios se cargan bajo demanda, solo cuando Claude lee archivos en ese directorio.
Solucion: si la instruccion es critica para toda la sesion, moverla al CLAUDE.md raiz.

Error: las Skills no se activan cuando deberian.
Causa: la descripcion es demasiado generica o no incluye keywords de activacion.
Solucion: agregar "ACTIVAR cuando:" con keywords explicitas y ejemplos en la descripcion de la Skill.

Error: los imports con @ cargan demasiado contexto al inicio.
Causa: los archivos importados con @ se cargan completamente en memoria al arrancar.
Solucion: referenciar archivos grandes sin @ y dejar que Claude los lea bajo demanda.

¿Que sigue despues de dominar CLAUDE.md?

CLAUDE.md es el cimiento. Una vez que lo tengas optimizado, el siguiente paso es construir encima:

  • Custom Commands: automatiza workflows repetitivos con archivos en .claude/commands/. Piensa en /deploy, /review, /test-integration.
  • Hooks: acciones deterministicas que se ejecutan en respuesta a eventos (pre-commit linting, formateo automatico, validaciones).
  • Plan Mode: presiona Shift+Tab dos veces para entrar en modo planificacion. Claude analiza sin modificar nada. Ideal para cambios multi-archivo donde quieres validar la estrategia antes de ejecutar.
  • Agent Teams: para proyectos grandes, multiples agentes trabajando en paralelo con contextos aislados y un CLAUDE.md compartido como fuente de verdad.

¿Ya tienes un CLAUDE.md en tu proyecto? ¿Cuantas lineas tiene y que instrucciones te han ahorrado mas correcciones? Compartir tu experiencia puede ayudar a otros a encontrar su configuracion optima.

Volver al blog