Tu CLAUDE.md también envejece: cómo podarlo sin romper lo que funciona

El consejo que parece una locura

En julio de 2026, Boris Cherny —creador de Claude Code— propuso una prueba bastante incómoda: cada seis meses, borrar temporalmente tu CLAUDE.md, tus Skills y tus hooks para ver qué puede hacer el modelo nuevo sin el andamiaje que construiste para el anterior. Un hook es una acción automática que se ejecuta cuando ocurre un evento, por ejemplo correr un linter después de editar un archivo o bloquear un comando peligroso antes de ejecutarlo.

La palabra importante es prueba. No estaba diciendo que el contexto dejó de importar ni que debés destruir un sistema de producción. Estaba señalando algo que nos pasa a todas: cada vez que la IA falla, agregamos otra regla. El archivo crece, el modelo cambia y rara vez volvemos a preguntar si esa cicatriz todavía sirve.

El dato que cambia la conversación

Cherny explicó en una charla de Y Combinator que el equipo eliminó más del 80% del system prompt interno de Claude Code al preparar la generación Claude 5, sin una pérdida medible en sus evaluaciones de programación. El system prompt es el conjunto de instrucciones base que el producto entrega al modelo antes de que la persona escriba su solicitud. Muchas de esas instrucciones intentaban corregir comportamientos que los modelos nuevos ya resolvían por sí solos.

Eso no convierte el 80% en una fórmula para tu proyecto. Sí cambia la pregunta. En vez de “¿qué más debería decirle?”, conviene preguntar “¿qué información no puede descubrir y qué regla sigue demostrando valor?”.

Un prompt (la instrucción que le das al modelo) enorme también puede restringir de más. Si CLAUDE.md, una Skill, una regla y tu solicitud dicen versiones ligeramente distintas de lo mismo, el modelo tiene que decidir cuál priorizar antes de empezar el trabajo.

Tu archivo de instrucciones también envejece

Pensá en CLAUDE.md como un manual escrito por varias versiones tuyas para varias versiones del modelo. Ahí pueden convivir:

• una convención real del equipo;
• una solución temporal para un modelo que ya no usás;
• una preferencia repetida tres veces;
• un procedimiento de treinta pasos que solo aplica una vez al mes;
• y una regla de seguridad que, en realidad, debería ser un control técnico.

Más texto no siempre significa más contexto. El contexto útil es información de alta señal que aparece en el momento correcto.

Qué sí debería quedarse

El archivo principal todavía es valioso para datos persistentes que el modelo no puede inferir con seguridad:

• el propósito breve del proyecto;
• comandos reales para ejecutar, probar y construir;
• arquitectura o convenciones particulares del repositorio;
• restricciones del negocio, legales o de marca;
• detalles inesperados que ya causaron fallos y siguen vigentes;
• una definición concreta de terminado.

La documentación de Claude Code recomienda mantener cada CLAUDE.md por debajo de 200 líneas. Ese límite orientativo ayuda a mantenerlo específico, conciso y legible.

Qué debería salir

Estas son las primeras candidatas para una prueba sin instrucciones:

• consejos genéricos como “escribí buen código” o “sé profesional”;
• recordatorios para capacidades que el modelo actual ya ejecuta bien;
• procedimientos largos que solo se usan en una tarea;
• documentación que ya existe en una fuente confiable;
• reglas duplicadas o contradictorias;
• instrucciones imposibles de comprobar;
• prohibiciones que deberían vivir en permisos o controles deterministas.

Menos reglas no significa un pedido vago. La tarea todavía necesita un objetivo, alcance, entregable y criterio de éxito claros.

Dónde poner lo demás

La arquitectura de 2026 se parece menos a un manual gigante y más a un clóset bien organizado:

Las Skills funcionan por carga progresiva: el modelo ve primero su nombre y descripción; carga el procedimiento completo cuando la tarea lo necesita. Es una mejor casa para un checklist de despliegue, una revisión de seguridad o un flujo de contenido que no debería ocupar contexto durante todo el día.

Un ejemplo antes y después

Imaginá que CLAUDE.md contiene estas cinco líneas:

Escribí buen código. Revisá siempre tu trabajo. No cometás errores. Usá TypeScript. Ejecutá pnpm test y pnpm build antes de terminar.

Las primeras tres no definen una conducta comprobable. “Usá TypeScript” puede ser útil si el repositorio permite varios lenguajes, pero el propio código probablemente ya lo muestra. La última sí aporta: nombra verificaciones concretas que el modelo debe ejecutar.

Una versión más fuerte sería:

Antes de terminar, ejecutá pnpm test y pnpm build. Si algo falla, reportá el comando, el error y si fue causado por este cambio. No afirmés que pasó una verificación que no ejecutaste.

Conservá las instrucciones que cambian una decisión y se pueden verificar.

El protocolo de poda semestral

No borres nada a ciegas. Hacé una pequeña evaluación.

1. Guardá una copia versionada de tu configuración actual. Versionada significa que podés recuperar exactamente la versión anterior, por ejemplo con Git.
2. Elegí tres a cinco tareas representativas, incluyendo una difícil.
3. Ejecutalas con el modelo actual y el sistema completo.
4. Repetilas con un CLAUDE.md mínimo y sin los procedimientos heredados.
5. Compará calidad, correcciones, tiempo, costo y cumplimiento de restricciones usando la misma tarea y los mismos archivos.
6. Reincorporá una regla solo cuando resuelva un fallo observado.
7. Mové procedimientos y controles al mecanismo que les corresponde.

La verificación no desaparece. Lo que cambia es la forma: tests, revisiones, criterios de aceptación y límites reales pesan más que repetir “verificá todo” dentro del prompt.

Lo que esto significa si no sos developer

La misma idea aplica a marketing, diseño, operaciones o educación. Si tu archivo de marca intenta contener toda la personalidad, cada campaña, cada plataforma y cada checklist, el modelo recibe una mezcla de identidad, datos y procedimientos que compiten entre sí.

Separá cuatro capas:

• identidad: quién sos y qué no cambia;
• estándares: cómo se ve un resultado aprobado;
• procesos: pasos reusables que se activan cuando hacen falta;
• referencias: ejemplos y fuentes que se consultan bajo demanda.

La ventaja en 2026 no está en escribir el manual más largo. Está en saber qué contexto merece entrar, cuándo debe aparecer y cómo comprobar el resultado.

Fuentes primarias

• Boris Cherny: We Cut 80% of Claude Code’s Prompt, charla publicada por Y Combinator.
• Cómo Claude recuerda un proyecto, Claude Code Docs.
• Descripción general de extensiones: CLAUDE.md, Skills, hooks, MCP y subagentes, Claude Code Docs.

Para convertir los procedimientos que salen de CLAUDE.md en módulos reutilizables, leé CLAUDE.md y Skills: cómo darle buen contexto a tu IA. Para comprobar si el sistema conserva permisos adecuados durante una migración, usá seguridad y estándares para agentes de IA.

Si querés aprender a trabajar con IA con sistemas simples que sí podés entender y mantener, sumate gratis a Pioneras en IA.