Tu CLAUDE.md te está mintiendo

Llevo meses escribiendo reglas en el CLAUDE.md del CRM que corre mi agencia. Cada una salió de algo que se rompió. Cada una tiene su cifra y su fecha.

La semana pasada medí tres de ellas contra el código.

Las tres estaban mal.

No mal escritas: mal como hechos. Describían un código que ya no existe, o que nunca existió. Y llevaban meses ahí, guiando a un agente que las obedecía al pie de la letra.

Lo que un CLAUDE.md realmente es

Lo llamamos documentación y lo tratamos como memoria. Es otra cosa:

Un CLAUDE.md es un conjunto de afirmaciones sobre tu código.

"Las colecciones llevan prefijo crm_" es una afirmación. Se puede verificar. "Los scripts corren en seco por default" es una afirmación. Se puede verificar. "161 rutas bajo /api/v1" es una afirmación con número.

Y a diferencia del código —que tiene tests, tipos, CI— nada verifica esas afirmaciones. El código cambia debajo de ellas y nadie se entera, porque no hay nada que se ponga rojo.

Tu CLAUDE.md es el único archivo del repo que puede mentir sin consecuencias.

Las tres

Una: el prefijo que no era

La regla decía:

Confirma el nombre de la colección antes de escribir. Con prefijo crm_ (crm_negocios, no negocios).

Salió de un incidente real: alguien escribió en la colección sin prefijo, y Mongo —que la crea si no existe— devolvió cero sin fallar. La conclusión fue "no hay datos". Buena regla.

Fui a contar las colecciones para escribir un candado que la forzara.

29 de 107. Veintisiete por ciento.

financial_log no lo lleva. zoom_meetings tampoco. Ni deals, ni expenses, ni payments, ni las familias seo_* y rpm_*.

Si hubiera escrito el candado como decía la regla, habría bloqueado la colección más usada del repo. Habría gritado en falso todo el día. Y a la semana alguien lo habría apagado —yo— y con él se habría ido la protección real.

Un candado que se apaga es peor que no tenerlo, porque durante el tiempo que estuvo prendido te dio la sensación de estar cubierto.

Dos: la bandera que no existía

La regla decía:

Todo script que reescriba dinero corre sin --aplicar por default e imprime el diff cliente por cliente.

Esta salió del incidente más caro del año: un backfill iba a reasignar los ingresos de un cliente completo porque confundió su razón social con la de otro. Lo salvó correr el script en seco primero.

Fui a buscar la bandera para escribir el hook.

--aplicar no existe. En ningún archivo del repo.

Lo que existe son dos convenciones, invertidas entre sí:

Bandera	Si la olvidas
--apply, --commit	Nada. No escribe.
--dry, --dry-run	Escribe a producción.

Tres scripts —los de gastos y facturas, justo los del dinero— viven en el segundo grupo. Corren y escriben salvo que te acuerdes de la bandera.

Alguien que siguiera la regla al pie de la letra —"corre sin --aplicar, eso es lo seguro"— habría escrito a la base. La regla no solo era falsa: apuntaba en la dirección exactamente contraria al peligro.

Tres: la convención que era un deseo

La regla decía:

Toda mutación vive en /api/v1 con auth + zod + rate limit.

Conté las 161 rutas: 127 con auth, 36 con zod, 1 con rate limit.

Auth está sólido. Zod, a medias. El rate limit no es una convención: es algo que alguien quiso que fuera cierto y escribió como si ya lo fuera.

Esa es la más silenciosa de las tres. No produce un bug mañana. Produce un agente que asume que existe un helper de rate limit y lo busca, o peor, lo inventa.

Por qué esto es peor que no tener la regla

Una regla que falta te deja pensar. Vas, miras el código, decides.

Una regla falsa te da confianza en la dirección equivocada. No vas a mirar el código: para eso está la regla.

Y el agente, menos. Un modelo hace exactamente lo que este archivo dice, con más literalidad que una persona. Le dijiste que las colecciones llevan crm_, así que va a inventar un nombre con prefijo que no existe, y Mongo se lo va a aceptar en silencio.

La regla escribió el bug que la regla existía para prevenir.

Por qué se pudren

Ninguna de las tres estaba mal el día que se escribió. Se pudrieron después, cada una a su manera.

Por crecimiento. El prefijo era cierto cuando había ocho colecciones y todas eran del CRM. Llegaron las de Zoom, las de SEO, las financieras. Nadie volvió a leer la regla.

Por aspiración. El rate limit se escribió como convención cuando era un plan. Es el error más humano del montón: describir el repo que quieres tener.

Por memoria. Lo de --aplicar es lo más incómodo. Yo escribí esa línea, y la escribí de memoria, sin abrir un solo script. La convención en mi cabeza no era la del código.

El método

Es una tarde, y no necesitas herramientas para empezar.

Uno. Subraya cada afirmación verificable. Recorre tu CLAUDE.md y marca todo lo comprobable contra el repo: rutas, nombres de archivo, comandos, banderas, números, prefijos.

Lo que queda sin subrayar es proceso —"commitea al terminar cada capa"— y eso no se audita así.

Dos. Verifica las baratas primero. Rutas y comandos son un ls y un vistazo a package.json. Encuentras basura en cinco minutos.

Tres. Cuenta los universales. Cada "toda", "siempre", "nunca", "cada" es una afirmación de cobertura, y la cobertura se mide. Este es el paso que encuentra las caras.

Ojo con algo que me costó: las afirmaciones más peligrosas no usan palabras universales. La del prefijo decía "Confirma el nombre de la colección. Con prefijo crm_" — ni un "toda", ni un "siempre". Está redactada como instrucción y afirma una convención universal de contrabando.

Cuatro. Para cada una que falle, hay tres salidas honestas:

1. Reescribir la regla para que diga la verdad.
2. Hacer que el código cumpla la regla.
3. Borrar la regla.

Lo que no es una salida es dejarla.

La primera fue mi caso con el prefijo. La regla quedó así:

Confirma el nombre exacto de la colección contra docs/SCHEMA.md. No lo deduzcas: un tercio lleva prefijo crm_ y el resto no, y un nombre equivocado devuelve 0 sin fallar.

Más larga, menos elegante, y cierta.

El tool

Hacer esto a mano funciona una vez. Automaticé los chequeos mecánicos en un script sin dependencias que corre en cualquier repo.

Contra mi CLAUDE.md de antes de la limpieza:

HECHOS — 2 afirmaciones que el codigo contradice

  --aplicar
    no aparece en ningun archivo de codigo   · CLAUDE.md:170

  64 archivos de test
    hay 112 archivos de test   · CLAUDE.md:18
    Desvio de 43%.

PARA TU CRITERIO — 1 regla universal que se cumple a medias

  27 de 105 lo llevan — 26%   · CLAUDE.md:80
    - Confirma el nombre de la coleccion... Con prefijo `crm_`
    medido en: nombres pasados a .collection()
    no lo llevan: linear_issues, zoom_meetings, cms_config

Contra el de después:

Ninguna afirmacion verificable resulto falsa.

Las dos cubetas

Lo único que me importaba del diseño: hechos y criterio nunca se mezclan.

Un hecho es que la ruta no existe. Es verificable, no admite opinión, y solo se corrige o se borra.

Lo otro es una convención que se cumple a medias. El tool te da el porcentaje y se calla. Porque qué hacer con un 26% no es dato — depende de si esa colección la vas a migrar, de si el prefijo era una decisión o un accidente, de cosas que el tool no sabe.

Es la misma doctrina que ya tenía escrita para otra cosa:

El validador solo las señala. A qué plan pertenece un issue es criterio, no dato.

Un auditor que opina sobre lo que no puede verificar se vuelve ruido. Y el ruido se apaga.

La calibración importa más que la cobertura

La primera versión encontró siete "hechos". Cinco eran falsos.

Cuatro eran rutas HTTP —/api/v1, /cms/outreach— que leía como archivos faltantes. La quinta era un nombre de rama de git.

Un auditor que grita en falso cinco de siete veces se borra el mismo día. Y borrarlo sería la conclusión correcta.

Así que cada chequeo terminó calibrado para callarse cuando duda: sin diagonal no es una ruta sino un tipo de archivo; con diagonal inicial es HTTP y no disco; si el primer segmento no es un directorio real, no está hablando del repo.

Y los prefijos se miden contra la familia que se usa igual —los nombres que recibe la misma función—, no contra todo string parecido. Ese cambio movió el número de "9% sobre 338 identificadores" a "26% de las colecciones". El primero mezclaba llaves de Stripe con nombres de colección. Los dos son técnicamente ciertos; solo uno es útil.

De las 16 pruebas del tool, cinco verifican únicamente que se quede callado.

La ironía, que no me la voy a guardar

Mientras escribía el auditor puse un nombre de colección inventado como ejemplo, dentro de un comentario.

Un hook que había construido esa misma tarde —el candado de colecciones, el que salió de la regla del prefijo— me bloqueó la edición.

Lo esquivé usando un nombre real y seguí. Media hora después, escribiendo este artículo, me bloqueó otra vez: el párrafo que estás leyendo contenía el mismo ejemplo.

La segunda vez ya no era gracioso, era un defecto. El hook miraba el contenido sin mirar el destino: un nombre de colección dentro de un archivo de texto es un ejemplo, no una query. Le agregué tres líneas para que solo mire código fuente, y dos pruebas para que no vuelva.

Ese es el ciclo completo en una tarde: una regla se vuelve candado, el candado dispara de más, y el candado se corrige con la misma evidencia con que se construyó. Lo que no se puede hacer es dejarlo gritando y esperar que la gente lo aguante. No lo aguanta: lo apaga.

Dentro de dos semanas voy a revisar cuál de mis cinco hooks disparó de verdad y cuál solo estorbó. Los que estorbaron se borran.

Agregar es fácil. Revisar es el trabajo.

Lo que haría distinto

Escribir las reglas con su cifra y su fecha. No "las colecciones llevan prefijo crm_" sino "27% lo llevan (medido 2026-08)". Una regla con fecha se ve vieja. Una sin fecha se ve eterna.

Nunca escribir una regla de memoria. La de --aplicar me tomó treinta segundos escribirla y meses estar equivocada. Abrir el archivo antes cuesta un minuto.

Medir antes de forzar. El momento más caro para equivocarte es cuando conviertes una regla en candado. Ahí deja de ser una sugerencia que el modelo pondera y pasa a bloquear trabajo real.

Corre el tuyo

Mi apuesta: si tu CLAUDE.md tiene más de tres meses, encuentras algo.

Y si no encuentras nada, tampoco pierdes: sabes que las reglas que tienes son ciertas. Que es más de lo que yo podía decir la semana pasada.