Opus 4.8 rompe tu CLAUDE.md: audítalo antes de seguir

TL;DR: Opus 4.8 ya es el modelo por defecto en Claude Code y reinterpreta directivas de tono, verbosidad y obediencia que llevaban meses funcionando en tu CLAUDE.md. Las instrucciones blandas ("por favor", "intenta") ahora se tratan como sugerencias que el modelo puede ignorar, y el agente cuestiona más tus órdenes. Aquí tienes un checklist concreto para auditar tu CLAUDE.md hoy, separar reglas duras de preferencias y testear los cambios sin quemar una sesión productiva.

El problema: el mismo CLAUDE.md, otro comportamiento

Actualizas Claude Code, sigues con tu flujo de siempre, y de repente el agente responde distinto. Más verboso en unas tareas, más contestón en otras, y a veces se planta y discute una instrucción que antes ejecutaba sin rechistar. No has tocado tu CLAUDE.md. El que ha cambiado es el modelo que lo lee.

Según la documentación de Anthropic sobre Opus 4.8, los cambios de comportamiento "no son breaking changes de la API, pero pueden requerir actualizar tus prompts". Tu CLAUDE.md es un prompt. Uno que se inyecta en cada sesión, así que cualquier desajuste se multiplica por cada tarea que lanzas.

Esto importa porque el coste de no auditarlo es real: tareas mecánicas que se llenan de explicaciones, refactors automáticos que se interrumpen para pedir confirmación, y pipelines que esperaban respuestas concisas y reciben párrafos. Si te interesa el fondo de por qué la configuración pesa más que el modelo que elijas, lo desarrollé en esta guía sobre coding agents en 2026.

¿Qué cambió en Opus 4.8 que afecta a tu CLAUDE.md?

Tres cambios concretos rompen instrucciones heredadas. Ninguno es un bug. Son decisiones de diseño que chocan con cómo escribíamos CLAUDE.md para 4.7 y anteriores.

• Effort en "high" por defecto. La documentación de Anthropic confirma que el parámetro de effort arranca en high en todas las superficies, incluido Claude Code. Más razonamiento por defecto significa respuestas más elaboradas, justo lo contrario de lo que pide una regla "sé conciso".
• Push-back constructivo. El system prompt del modelo lo dice explícito: Claude está dispuesto a cuestionar y ser honesto, "pero de forma constructiva". En la práctica, el agente discute más tus atajos cuando detecta que algo no encaja.
• Más honestidad sobre su propio trabajo. Anthropic destaca que 4.8 es bastante menos propenso a pasar por alto sus propios fallos. Eso es bueno, pero implica que ya no traga instrucciones débiles solo por complacerte.

La consecuencia clave: Opus 4.8 distingue mejor entre una orden y una sugerencia. Una directiva escrita en tono suave la lee como preferencia opcional, no como regla.

¿Por qué falla una instrucción blanda en CLAUDE.md?

Una instrucción blanda es la que usa verbos de cortesía o condicionales en lugar de imperativos directos. Frases como "por favor intenta ser breve" o "estaría bien que uses type hints" funcionaban en 4.7 porque el modelo tendía a obedecer literalmente. Opus 4.8 las interpreta como lo que gramaticalmente son: peticiones suaves que puede priorizar o no según el contexto.

El patrón problemático más común son las listas largas de prohibiciones ("no hagas X, no hagas Y, no uses Z..."). Cuando mezclas quince "don'ts" sin jerarquía, el modelo no sabe cuáles son innegociables y cuáles son orientativas. Y con un agente que ahora cuestiona más, esa ambigüedad se traduce en interrupciones o en incumplimientos selectivos.

El patrón que funciona: reglas duras vs preferencias

Separa lo que debe cumplirse siempre de lo que es orientativo, y márcalo visualmente. Es la misma lógica de la separación de responsabilidades aplicada a tu configuración: cada bloque tiene un único propósito y un único nivel de obligatoriedad.

Tipo	Lenguaje	Ejemplo
Regla dura	Imperativo, mayúsculas para lo crítico, sin condicionales	"NUNCA hagas commit sin confirmación explícita"
Preferencia	Orientativo, agrupado aparte y etiquetado como tal	"Preferencia: respuestas concisas salvo en revisiones de arquitectura"

Antes (instrucción blanda que 4.8 puede ignorar):

# Débil: el modelo lo lee como sugerencia opcional
- Por favor, intenta no usar cat/grep, estaría bien usar rg/fd.

Después (regla dura inequívoca):

# Fuerte: imperativo claro, sin margen de interpretación
## Reglas (obligatorias)
- NUNCA uses cat/grep/find. Usa SIEMPRE rg/fd/bat.
- NO hagas commit ni push sin confirmación explícita.

## Preferencias (orientativas)
- Respuestas directas y sin preámbulo cuando la tarea es mecánica.

El mismo principio aplica a cualquier stack. En reglas para Python o TypeScript, marca lo innegociable como bloque imperativo:

# Regla dura para el agente, no comentario decorativo
# OBLIGATORIO: toda función pública lleva type hints y docstring.
# OBLIGATORIO: no captures Exception genérica, usa el tipo concreto.

Checklist de auditoría de tu CLAUDE.md

Recorre tu archivo con esta lista. Cada punto es un patrón que se volvió contraproducente con 4.8.

• Caza las frases de cortesía. Busca "por favor", "intenta", "estaría bien", "si puedes". Conviértelas en imperativos o muévelas a un bloque de preferencias.
• Separa reglas de preferencias. Dos secciones distintas con encabezados claros. No mezcles obligatorio con orientativo en la misma lista.
• Reduce las listas de "don'ts". Si tienes diez prohibiciones, quédate con las tres críticas en mayúsculas y reformula el resto como criterio positivo ("haz X" en vez de "no hagas Y").
• Revisa las reglas de verbosidad. Con effort en high por defecto, una sola línea "sé conciso" no basta. Especifica cuándo: "respuestas breves en tareas mecánicas, detalle solo en decisiones de arquitectura". Si dudas sobre el nivel de razonamiento, repasa cuándo subir el effort a max y cuándo no.
• Comprueba que las reglas siguen siendo válidas. Una regla que dependía de que el modelo "obedeciera ciego" puede sobrar ahora que cuestiona mejor. No acumules basura: tu CLAUDE.md es la capa que más conviene mantener curada, como expliqué al hablar de las tres capas de memoria en Claude Code.

Cómo testear los cambios sin perder la sesión

No edites a ciegas y reces. Valida con un prompt de control antes de meter el CLAUDE.md nuevo en una tarea larga. El objetivo es ver cómo interpreta el agente tus reglas, no si resuelve la tarea.

Un prompt de validación rápido que uso:

# Pide al agente que te explique cómo entiende tus propias reglas
"Lee mi CLAUDE.md. Lista qué consideras reglas obligatorias
y qué consideras preferencias orientativas. No ejecutes nada."

Si el agente clasifica como "preferencia" algo que tú das por obligatorio, ahí tienes el desajuste. Para cambios delicados, abre dos sesiones, una con el CLAUDE.md viejo y otra con el nuevo, lánzales la misma tarea pequeña y compara. Es el mismo enfoque de medir en lugar de intuir que apliqué para detectar si Claude se ha vuelto más tonto: una comparativa side-by-side vale más que cualquier sensación.

En Producción

Lo que cambia entre el tutorial y un flujo real: en pipelines automatizados con Claude Code, la verbosidad extra de 4.8 no es solo molesta, cuesta tokens y puede romper parsers que esperaban salidas escuetas. Si un script tuyo lee la respuesta del agente, audita primero las reglas de formato.

• Coste: effort high por defecto consume más tokens por turno que el default de 4.7 en la misma tarea. Para trabajo mecánico (boilerplate, tests repetitivos), baja el effort de forma explícita en la sesión en lugar de pelearte con el CLAUDE.md.
• Manejo de errores: el push-back significa más interrupciones para confirmar. En flujos desatendidos, define en reglas duras qué decisiones puede tomar solo el agente y cuáles requieren parar. La ambigüedad aquí se paga en tareas a medias.
• Escalabilidad: si gestionas varios proyectos, no tengas un CLAUDE.md monolítico distinto por repo con las mismas reglas copiadas. Centraliza las reglas duras globales y deja en cada proyecto solo lo específico.
• Versiona el cambio: guarda el CLAUDE.md anterior antes de auditar. Si el comportamiento empeora, vuelves en segundos en vez de reconstruir de memoria.

Un trade-off honesto: este enfoque de reglas duras frente a preferencias funciona muy bien para equipos pequeños y proyectos propios. No lo he probado con CLAUDE.md compartidos por equipos grandes donde cada persona añade su capa, ahí la disciplina de mantenerlo curado es el verdadero cuello de botella.

Errores comunes y depuración

• Error: el agente ignora una regla que considerabas crítica. Causa: estaba redactada en tono suave o enterrada en una lista de "don'ts". Solución: reescríbela en imperativo, mayúsculas para lo innegociable, en una sección de reglas separada.
• Error: respuestas demasiado largas en tareas triviales. Causa: effort high por defecto más una regla de concisión vaga. Solución: concreta cuándo aplicar brevedad y baja el effort en la propia sesión para trabajo mecánico.
• Error: el agente se planta y discute en mitad de un refactor automático. Causa: el push-back de 4.8 sin reglas claras sobre autonomía. Solución: define explícitamente qué puede decidir solo y dónde debe parar.

Preguntas frecuentes

¿Tengo que reescribir todo mi CLAUDE.md desde cero?

No. La mayoría del contenido sigue siendo válido. El trabajo es de auditoría puntual: reformular instrucciones blandas a imperativos y separar reglas duras de preferencias. Tirar el archivo entero a la basura es desperdiciar meses de contexto curado.

¿Puedo volver a Opus 4.7 si no quiero auditar ahora?

Sí, puedes seguir seleccionando 4.7 en Claude Code mientras tu CLAUDE.md está muy optimizado para ese modelo. Es una solución temporal razonable si dependes de respuestas muy concisas en pipelines automatizados y no tienes tiempo de auditar hoy.

¿Por qué Opus 4.8 me cuestiona más que antes?

Es comportamiento de diseño. El system prompt del modelo lo describe como push-back constructivo, y Anthropic mejoró su honestidad para que no ignore problemas que detecta. Con reglas claras sobre su margen de autonomía, esas interrupciones bajan mucho.

Conclusión

Hemos visto cómo Opus 4.8 reinterpreta tu CLAUDE.md: el effort en high infla la verbosidad, el push-back hace que cuestione más, y las instrucciones blandas pasan de órdenes a sugerencias opcionales. La clave no está en escribir más reglas, sino en escribirlas mejor: imperativos inequívocos para lo innegociable, un bloque aparte para las preferencias, y un prompt de validación que te diga cómo entiende el agente tus propias reglas antes de jugártela en una sesión larga.

Empieza hoy por lo barato: caza las frases de cortesía y separa reglas de preferencias. Es media hora de trabajo que te ahorra días de fricción. ¿Has notado a tu Claude Code más parlanchín o más contestón tras el salto a 4.8? Cuéntame qué regla se te rompió en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo medir el coste real por tarea de Opus frente a Codex en sesiones largas, que es la otra cara de este cambio de default.