Las 12 reglas de un CLAUDE.md que sí funciona (con ejemplos)

Tu CLAUDE.md no es documentación: es el prefijo de todos tus prompts. Cada línea se cobra en cada turno, para siempre. Por eso la pregunta al escribirlo no es "¿esto es cierto?" sino "¿esto cambia lo que el agente hace, hoy?".

Estas son las 12 reglas que más impacto tienen en que un agente obedezca. Cada una viene con la versión vaga —la que casi todos escribimos primero— y la que sí funciona.

Al final está el resumen: qué recortar, qué nunca borrar, y el resultado de aplicarlo a nuestro propio repo (274 → 168 líneas, de ~5,200 a ~1,850 tokens por turno).

¿Quieres saber cómo está el tuyo antes de leer? Pégalo en el analizador de CLAUDE.md: saca la calificación en 5 segundos y corre en tu navegador, el archivo no sale de tu máquina.

La regla de oro: imperativo, verificable, con consecuencia

Antes de las 12, el patrón que las atraviesa todas. Una regla se obedece cuando el agente puede comprobar si la cumplió. "Considera", "trata de" y "sería bueno" se leen como opcionales, porque lo son.

No funciona	Sí funciona
"Es importante testear"	"Antes de decir listo: npm run check && npm test"
"Cuidado con las queries"	"Filtra en la query, nunca en JS después del .find()"
"Usa buenos nombres"	"Colecciones con prefijo crm_. Confírmalos en el adapter"

Y cuando la regla nació de un golpe real, deja el golpe. Una regla con consecuencia se obedece más que una sin ella:

Nunca Co-Authored-By en commits. Vercel bloquea el deploy.

1. Auto-mejora: que el archivo aprenda solo

La más importante, y la que casi nadie tiene.

Mitchell Hashimoto —creador de Terraform, Vagrant y Ghostty— trata su AGENTS.md como bitácora de fallas: cada línea existe porque el agente se equivocó al menos una vez. No escribió el archivo perfecto de entrada; lo dejó crecer a partir de errores reales.

<!-- Vago -->
Trata de no cometer errores y sigue las mejores prácticas.

<!-- Funciona -->
Cuando cometas un error que este archivo pudo evitar, proponme la línea
antes de cerrar la tarea: fecha, qué pasó, qué hacer distinto.

## Bitácora
- 2026-08-06 — "Gmail no configurado" con Gmail conectado. El helper miraba
  `process.env`; el token vivía en la base. No pre-valides con env.

Señal de que tu archivo aprende: líneas con fecha. Si no las tiene, cada error que corriges de viva voz se va a repetir el mes que entra.

2. Bucle de verificación: cómo comprueba su trabajo

La de mayor retorno de todas. Casi todo repo tiene test o check en su package.json, y casi ningún CLAUDE.md los menciona — así que el agente dice "listo" sin comprobar nada.

<!-- Vago -->
Escribe tests y asegúrate de que el código funcione.

<!-- Funciona -->
Antes de decir "listo": `npm run check && npm test`.
Si falla, arréglalo — no reportes terminado con el gate en rojo.

Dos detalles importan: el comando exacto (no "corre los tests") y qué hacer si falla. Sin la segunda mitad, el agente reporta el fallo y sigue adelante.

Si tu repo no tiene tests, no escribas esta regla. Un CLAUDE.md que manda correr npm test donde no hay tests es peor que uno que calla: hace que el agente reporte verde sobre nada.

3. Preguntar antes de asumir

Una suposición equivocada temprano se amplifica en todo lo que sigue. Es la fuente número uno de trabajo desviado.

<!-- Vago -->
Si tienes dudas, puedes preguntar.

<!-- Funciona -->
Ante ambigüedad que cambia el trabajo, pregunta antes de asumir.

El matiz está en "que cambia el trabajo": no quieres que pregunte todo, quieres que distinga entre una decisión de estilo y una bifurcación real.

4. Tipos estrictos

TypeScript es el lenguaje más usado en GitHub, y buena parte de la razón es que los agentes trabajan mejor con tipos: atrapan errores sin necesidad de más tests y garantizan contratos.

<!-- Vago -->
Usamos TypeScript, procura tipar bien.

<!-- Funciona -->
`strict: true`. Nunca `any` — si no sabes el tipo, `unknown` y estrecha.

Si tu tsconfig.json ya tiene strict: true, dilo en el archivo. El agente no lo lee por su cuenta antes de escribir código, y termina generando algo que no compila y corrigiéndose después.

5. Paquetes mantenidos

Sin criterio, un agente hace una de dos cosas malas: instala lo primero que encuentra, o escribe 200 líneas para evitar una dependencia de tres.

<!-- Vago -->
No agregues dependencias innecesarias.

<!-- Funciona -->
Antes de instalar: commits recientes y uso real. Prefiere un paquete sólido
a 200 líneas propias — pero no metas una dependencia por una función de tres.

Con los ataques de cadena de suministro de los últimos meses, "commits recientes y uso real" dejó de ser preferencia de mantenimiento y pasó a ser seguridad.

6. Nombres y convenciones

Igual que un equipo humano, un agente en días distintos escribe login, signIn y iniciarSesion. La consistencia no es solo estética: mejora la capacidad del modelo de razonar sobre el código.

<!-- Vago -->
Mantén nombres consistentes.

<!-- Funciona -->
Colecciones con prefijo `crm_` (`crm_negocios`, no `negocios`). No los
adivines: confírmalos en el adapter. Escribir en la colección equivocada
no falla — devuelve 0 y te hace concluir que no hay datos.

Ese ejemplo es real y por eso funciona: la consecuencia (un fallo silencioso que parece dato faltante) hace que la regla se recuerde.

7. Estructura del proyecto

Puede ser delgada: el agente infiere mucho del árbol de archivos. Escribe solo lo que no es obvio mirándolo.

<!-- Vago -->
El proyecto sigue una estructura estándar de Next.js.

<!-- Funciona -->
Lógica pura en `src/lib/<dominio>/` · endpoints en `app/api/v1/` · UI en `app/(app)/`

Una línea. Lo que evita es que el agente ponga lógica de negocio dentro de un componente porque no sabía que existe src/lib.

8. Recorrer el flujo como usuario

Los tests unitarios en verde no prueban que la aplicación sirva. Antes esto costaba un equipo de QA; hoy un agente abre un navegador y hace clic como una persona.

<!-- Vago -->
Prueba que la funcionalidad ande bien.

<!-- Funciona -->
Al terminar una feature con UI, recorre el flujo completo como usuario
antes de cerrar. Las condiciones de carrera y los casos borde salen ahí,
no en los unit tests.

Igual que la regla 2: si no tienes con qué (Playwright, Cypress, un navegador headless), no la escribas todavía.

9. Revisión visual

Complemento de la anterior, y la que atrapa lo que ningún test ve. Puedes tener todo en verde y que alguien haya dejado un opacity: 0 en el body.

<!-- Vago -->
Revisa que se vea bien.

<!-- Funciona -->
Screenshot con datos realistas, no lorem ipsum: el texto largo es lo que
rompe el layout. Mira la imagen, no solo el diff.

Lo de los datos realistas no es un detalle. Un diseño se ve perfecto con lorem ipsum y se desborda con el nombre real de un cliente.

10. Performance

Donde más dinero se pierde en silencio. Aun con los modelos actuales, es común que un agente traiga mil filas de la base y filtre en memoria.

<!-- Vago -->
Cuida el rendimiento de las consultas.

<!-- Funciona -->
Filtra en la query, nunca en JS después del `.find()`.
Antes de un `.find()` sobre colección grande, confirma que hay índice.
Endpoint que pasa de ~300ms se revisa antes de mergear.

El número concreto es lo que la hace verificable. "Que sea rápido" no se puede comprobar; "300ms" sí.

11. Manejo de errores

Los bugs se cuelan cuando un error se traga o se ignora. La política vale más que el caso puntual.

<!-- Vago -->
Maneja los errores apropiadamente.

<!-- Funciona -->
Falla ruidoso y temprano. Nunca un catch vacío; reporta el error real.
No pre-valides con helpers que solo miran `process.env` — llama a la
función real y reporta SU error en el catch.

Esa segunda mitad salió de un caso concreto: un helper decía "Gmail no está configurado" porque solo miraba variables de entorno, mientras el token vivía en la base y el sistema llevaba meses mandando correos con él.

12. Arquitectura

Si tu repo tiene más de 10 dominios, esta tabla es la sección de mejor retorno del archivo: evita que cada sesión nueva gaste tokens redescubriendo lo mismo.

<!-- Vago -->
El proyecto tiene varios módulos para las distintas áreas del negocio.

<!-- Funciona -->
| Dominio | Vive en | Qué resuelve |
|---|---|---|
| Radar | `src/lib/radar` | Prioridades operativas del día |
| Horas | `src/lib/horas` | Timer nativo (reemplaza Harvest) |
| Invoices | `src/lib/invoices` | Duales: MXN (Zoho) y USD (Stripe) |

Solo los dominios que tocas seguido. Doce filas, no cuarenta y seis.

Lo que hay que sacar

Las 12 reglas dicen qué agregar. Igual de importante es qué quitar, porque el presupuesto es real: ~150 líneas para un archivo de proyecto.

Procedimiento paso a paso. Si son diez líneas explicando cómo se hace algo, pertenece a un skill que se carga al invocarlo. En el CLAUDE.md queda una línea con el disparador. Nuestro archivo global tenía 17 líneas sobre cómo generar diagramas —dónde guardar el JSON, qué tamaños exportar— que solo importan cuando ya estás haciendo un diagrama, momento en el que el skill ya está cargado.

Código que ya no existe. El repo evoluciona y el archivo no. El nuestro decía "Supabase y Airtable se removieron", y noventa líneas más abajo seguía explicando los formatos de ID de Airtable y Supabase.

Referencia que se consulta a veces. El setup completo de internacionalización, las plantillas de correo, "cómo agregar un backend nuevo". Van a docs/ con un puntero de una línea.

Lo que un linter ya obliga. Comillas, punto y coma, indentación. Eso no es una instrucción, es configuración.

Lo que nunca se borra

Al recortar, el error clásico es llevarse las líneas con fecha porque parecen ruido histórico. Son lo contrario: cada una costó un error real. Comprímelas de cuatro líneas a una, con la fecha intacta, pero no las tires.

Lo mismo con las prohibiciones absolutas que ya atraparon algo. Son baratas en tokens y caras si se pierden.

El resultado

Aplicamos esto a nuestro propio repo —el CRM interno de la agencia— y el archivo pasó de 274 a 168 líneas: de ~5,200 a ~1,850 tokens en cada turno. Sumado al archivo global, la sesión bajó de ~8,000 a ~3,700 tokens de contexto pagado por prompt.

Pero la métrica que importa no es esa. Es cuántas veces por semana corriges al agente por algo que el archivo debía cubrir. Si después de recortar sube, te llevaste algo que sí servía — revisa el diff en git y devuélvelo.

Por dónde empezar

Si solo vas a hacer una cosa esta semana, que sea la regla 2: escribe el comando exacto con el que se verifica el trabajo, y qué hacer si falla. Es la que convierte "creo que quedó" en "pasó el gate".

Después la regla 1, para que el archivo empiece a crecer solo a partir de tus errores reales en vez de tu imaginación.

Y si quieres ver cómo está el tuyo antes de tocarlo: pégalo en el analizador. Da la calificación, los tokens por turno y qué reglas te faltan, con el arreglo de cada una. Corre en tu navegador —el archivo no sale de tu máquina— y es gratis, igual que el skill que lo reescribe contra tu repo de verdad.