Andrew Parra EN

Guías · Sistema con Claude Code

Un CLAUDE.md que cambia el comportamiento

Escribe un CLAUDE.md corto, hecho de cosas que Claude no puede adivinar y que se pueden comprobar (cómo publicar, las reglas, el estado actual, tus preferencias), pruébalo contra no tener archivo y pasa a un hook todo lo que tenga que cumplirse siempre.

Lectura
7 min de lectura
Actualizada
19 de noviembre de 2026
Parte de
el paquete de 66 guías

Cada sesión de Claude Code empieza en blanco. CLAUDE.md es la nota que lee primero: qué es el proyecto, cómo publicarlo, qué no hacer nunca. Tengo uno en cada repositorio, y todos terminaron con la misma forma.

El problema es que un CLAUDE.md parece útil lo sea o no. Escribes veinte líneas, la sesión sale bien y le das el crédito al archivo. Las pruebas medidas que he juntado dicen que la mayoría de las líneas de la mayoría de los archivos no cambian nada. Unas pocas líneas cambian mucho.

Ordenar un CLAUDE.md línea por línea

1
How to shipnpm test, push, curl /healthz se queda
2
El dinero va en centavos enterosClaude no lo puede adivinar a partir del código se queda
3
NUNCA leas .envse tiene que cumplir siempre pasa a un hook
4
Lista de release, 10 pasosse usa de vez en cuando pasa a un skill
5
Write clean codemismo resultado con o sin ella se borra

Misma tarea, tres corridas cada una (Ejemplo: puntajes sobre 6 revisiones)

sin CLAUDE.md          4  4  3
tu archivo corto       6  6  6
Una línea se queda solo si Claude hace algo mal sin ella; las reglas de siempre van a hooks y los procedimientos ocasionales a skills.

1. Empieza por lo que encontraron las pruebas

Tres resultados definen cómo escribo estos archivos ahora. Los tres son cifras de los propios creadores, sacadas de sus videos. Yo no las volví a correr.

Tus propias reglas le ganan al largo. Un creador le dio a Claude una función pequeña (una casilla de código de descuento) con cuatro versiones de CLAUDE.md, tres corridas cada una, y calificó cada corrida con seis revisiones en el navegador. Sin archivo, sacó 4, 4 y 3. El archivo que genera /init, que describe el código y ninguna de sus reglas, sacó 4, 4 y 4. Su archivo de 19 líneas con siete reglas de la casa sacó 6 de 6 todas las veces. Una plantilla de 217 líneas con las mismas siete reglas enterradas en la sección 10 también sacó 6 de 6. La diferencia fueron las reglas que Claude no podía adivinar a partir del código: redondear el descuento hacia abajo al centavo, conservar el código después de recargar la página, no agregar funciones que nadie pidió. Sin ellas, los mismos errores aparecieron en las seis corridas.

La mayoría de las líneas genéricas no hacen nada. Otro creador probó el famoso CLAUDE.md de cuatro líneas en 42 corridas. Una línea cambió el comportamiento todas las veces: "Don't assume. Don't hide confusion. Surface tradeoffs." Con ella, 5 de 5 corridas terminaron con una lista de decisiones que el usuario podría querer cambiar; sin ella, 0 de 5. "Minimum code" redujo el tamaño del código en más o menos una quinta parte, pero también bajó el formato de dinero de 2 de 3 corridas a 0 de 3. Dos líneas no cambiaron nada medible. Él lo llama una pista, no una medición, con 2 a 5 corridas por celda.

El archivo cuesta tokens en cada solicitud. En una prueba de 27 corridas sobre un repositorio grande, un CLAUDE.md de /init subió los tokens por pregunta cuando todas las respuestas ya eran correctas. Un paper de investigación sobre archivos de contexto encontró el mismo patrón en benchmarks de código: ninguna mejora general en el éxito, y un costo más alto.

Así que una línea se gana su lugar solo si Claude haría algo mal sin ella.

2. Escribe las secciones que llevan datos que Claude no puede adivinar

Estas son las secciones en las que se asentaron mis archivos. Cada una guarda algo que el código no dice.

# my-app: notas de trabajo para Claude

Lee esto primero. README.md tiene la arquitectura; este archivo dice cómo se
trabaja aquí y en qué estado están las cosas.

## Where this fits
Uno de varios proyectos. Lee el servicio de cobros solo a través de su API
pública. Nunca importes el código ni las claves de ese repositorio.

## How to ship
1. Edita, luego `npm test` (tiene que pasar) y `npm run build`.
2. Haz push a `main`; el hosting despliega en más o menos un minuto.
3. Confirma con `curl -s https://<your-app>/healthz` y luego reporta qué cambió.

## Rules (do not relax)
- Las claves viven solo en las variables de entorno del hosting. Nunca escribas,
  imprimas ni subas una.
- El dinero va en centavos enteros. Un costo que falta es "incompleto", nunca cero.
- Pregunta antes de cualquier cosa irreversible: borrar datos, cambiar planes, gastar.

## State as of 2026-11-19
- Esperando por mí: configurar PAYMENTS_WEBHOOK_SECRET en el hosting.
- Bloqueado: el job de exportación falla con archivos de más de 50 MB (ver issue #12).

## My preferences
- Lo importante primero, corto. Leo en mi teléfono.
- Publica, verifica y luego dime qué cambió en pocas líneas.

Por qué está cada una:

  • Where this fits evita que una sesión comparta código o claves con un proyecto hermano "para ayudar".
  • How to ship es la sección que más se revisa. Cada paso es un comando, y "listo" tiene una prueba amarrada. La documentación de Anthropic pide líneas que se puedan comprobar, como "Run npm test before committing", y aquí es donde viven.
  • Rules (do not relax) es corta y específica del proyecto. Las reglas compartidas entran por una importación (ver abajo). "Do not relax" está en el título porque las sesiones van a proponer aflojar una regla para terminar una tarea.
  • State as of una fecha le dice a la siguiente sesión qué está bloqueado y qué está esperando por mí. Mi proyecto Spread lo divide más, en "Blocked on Andrew (ask him, don't guess)" y "Next steps once it runs (in order)".
  • Preferences trata del lector, no del código. Es la razón por la que mis sesiones terminan con tres líneas y no con tres pantallas.

3. Trae las reglas compartidas con una importación

Las reglas que aplican a todos los proyectos no pertenecen a ningún CLAUDE.md en particular. Claude Code expande las importaciones @path, y la documentación confirma que pueden anidarse hasta cuatro niveles.

## Reglas compartidas (leer primero)
@../parent-hub/RULES.md

Todos mis archivos de proyecto empiezan así. La guía sobre un solo archivo de reglas explica la revisión de desviaciones que mantiene honestas las copias.

4. Deja fuera lo que no cambia el comportamiento

La documentación sugiere mantener cada archivo por debajo de unas 200 líneas. Esto es lo que saco para lograrlo:

  • Descripciones del código. Claude puede leer el código. El archivo de /init de la prueba de arriba describía bien el proyecto y aun así no sacó mejor resultado que no tener archivo.
  • Consejos genéricos. "Write clean code" y "be careful" son las líneas que en las pruebas no hicieron nada.
  • Procedimientos que corres de vez en cuando. Una lista de diez pasos para un release va en un skill, que se carga solo cuando hace falta. La guía de costos de Anthropic dice lo mismo.
  • Todo lo que tenga que pasar siempre. CLAUDE.md es contexto. Claude lo lee y decide. Una regla de "nunca" va en un hook o en una regla deny (ver la guía de hooks). Si te descubres escribiendo una línea en mayúsculas, va ahí.
  • Secretos, IDs y URLs privadas. El archivo está en el repositorio, y cada sesión imprime partes de él.

5. Anota quién decidió y cuándo

Una regla sin razón invita a una sesión a "arreglarla". Cuando una regla es una decisión, le pongo una etiqueta:

- El correo de contacto sigue siendo el público de la página de contacto (decidido 2026-10-16).
- Nada de analytics ni cookies. Agregar cualquiera necesita mi OK, un aviso de
  consentimiento y una actualización de la página de privacidad.

La fecha le dice a una sesión futura que la regla es deliberada. Si llevas un log, también le dice dónde buscar el razonamiento. En mis repositorios, la cita completa va en el log del hub y la regla se queda en una línea.

6. Pruébalo como lo hicieron los creadores

No necesitas 42 corridas para aprender algo. Elige una tarea pequeña que toque tus reglas y córrela tres veces de cada forma.

# copia nueva en cada corrida; solo se cargan los settings del proyecto
for variant in none mine; do
  for run in 1 2 3; do
    rm -rf /tmp/try && cp -r . /tmp/try && cd /tmp/try
    [ "$variant" = none ] && rm -f CLAUDE.md
    claude -p "Agrega una casilla de código de descuento a la página del carrito" --setting-sources project > "/tmp/out-$variant-$run.txt"
    npm test > "/tmp/test-$variant-$run.txt" 2>&1; echo "$variant $run exit=$?"
    cd - >/dev/null
  done
done

Califica cada corrida con una revisión que escribiste antes de mirar el resultado. Si una regla saca lo mismo con y sin el archivo, borra la línea o pásala a un hook. Si una línea ayuda, déjala palabra por palabra. Reescribir una línea que funciona es la forma de perderla.

7. Mantenlo al día con un hábito

Cuando Claude comete un error que ya corregiste antes, termina la corrección con "update CLAUDE.md so this doesn't happen again" y luego lee el diff. Una guía de un creador lo recomienda, y así llegaron a mis archivos la mayoría de las líneas útiles: reglas de redondeo, un archivo que tiene que conservar sus finales de línea, una carpeta que nunca se toca.

Lee el diff cada vez. Claude va a escribir con gusto una línea genérica ("ten cuidado con el dinero"). Reescríbela como algo que se pueda comprobar ("el dinero va en centavos enteros").

Qué vigilar

  • La sección de estado se vuelve vieja. El CLAUDE.md de mi repositorio del hub todavía dice "State as of" una fecha de hace seis semanas. Todo lo que pasó después vive en el log del hub. Una sección de estado vieja es peor que no tener ninguna, porque la sesión le cree. Ponle fecha y recórtala cuando registres en el log.
  • Se cuelan los registros de cambios. Uno de mis repositorios más activos lleva en su CLAUDE.md un registro de cada arreglo, una entrada por cambio, y ya pasó de largo la guía de 200 líneas. Lo útil para la siguiente sesión es la regla que dejó cada arreglo. La historia detrás va en un log.
  • /clear borra las reglas del chat. En la prueba de 21 corridas de un creador, dos reglas escritas al inicio de un chat se perdieron después de /clear en 3 de 3 corridas. En CLAUDE.md sobrevivieron. Si sigues repitiendo una regla en el chat, va en el archivo.

Lista de verificación

  • El archivo empieza con "Read this first" y dice qué cubre el README en su lugar.
  • How to ship son comandos numerados que terminan con una revisión y un reporte.
  • Las reglas son específicas del proyecto, se pueden comprobar y van bajo "do not relax"; las reglas compartidas entran por @import.
  • El estado lleva una fecha y dice qué está bloqueado y qué está esperando por ti.
  • Nada de descripciones del código, consejos genéricos, procedimientos ocasionales ni secretos; el archivo tiene menos de unas 200 líneas.
  • Cada regla de "nunca" también existe como hook o regla deny.
  • Corriste una tarea tres veces con y sin el archivo, y cortaste las líneas que no cambiaron nada.

¿Quieres el resto?

Esta es una de 66 guías. El paquete completo es a tu voluntad, desde un café.