Cargando

Un CLAUDE.md que se respeta

Lección 27 min
Cargando

Un CLAUDE.md que se respeta

Aquí hay una trampa que atrapa a casi todos: tu archivo CLAUDE.md no deja de crecer. Te topas con un problema, agregas una regla. Te topas con otro, agregas otra regla. En poco tiempo tienes un archivo gigante, y Claude empieza a ignorar partes de él. Eso no es un error de Claude. Así es como funciona el archivo.

Lo clave que hay que entender es que CLAUDE.md no es una configuración forzada. Es orientación. Cada línea compite con todas las demás por la atención de Claude. Cuanto más crece el archivo, más compite consigo mismo, y con menos fiabilidad Claude sigue cualquier regla individual. Así que el objetivo no es anotarlo todo. El objetivo es mantener el archivo ajustado. Mientras más esbelto sea el archivo, más de él sigue Claude realmente.

Primero, pregúntate si CLAUDE.md es siquiera la herramienta correcta

Antes de escribir una regla, pregúntate si pertenece a CLAUDE.md en absoluto. Algunas reglas son orientación, y otras son líneas duras que nunca deben cruzarse. Esos son dos trabajos distintos.

Toma una regla como "nunca hagas push a main". Si pones eso en CLAUDE.md, estás esperando que Claude lo lea y lo respete. La mayoría de las veces lo hará. Pero "la mayoría de las veces" no es suficientemente bueno para algo tan peligroso. Una regla dura como esa pertenece a un hook de pre-uso-de-herramienta en su lugar.

La diferencia importa. Un hook es código que se ejecuta antes de que Claude realice una acción, y de verdad puede bloquear la acción. Así que incluso si Claude intenta hacer push a main, el hook lo detiene. Eso es aplicación real, no una solicitud cortés. Mueve tus reglas duras a hooks y deja que CLAUDE.md maneje las convenciones más suaves.

Las cuatro ubicaciones

CLAUDE.md no es solo un archivo que reside en tu proyecto. Hay cuatro lugares donde puede vivir, y Claude los carga todos juntos al iniciar. Nada se descarta, y se apilan.

Esto es para qué sirve cada uno:

  • Política gestionada — el archivo a nivel de organización que controla tu equipo de plataforma. No puedes excluirlo, así que la política de la organización siempre está en juego.
  • Usuario — tus preferencias personales que te siguen en todos los proyectos de tu máquina.
  • Proyecto — el archivo compartido con tu equipo, registrado en el repositorio.
  • Local — ignorado por git. Tus notas personales solo para este repositorio.

Esa última, la local, es fácil de pasar por alto pero realmente útil. Digamos que estás refactorizando en tu propia rama y quieres que Claude tenga en mente algunas decisiones arquitectónicas mientras trabajas. Eso no pertenece al archivo de proyecto compartido, donde afectaría a todo tu equipo. Va en local, donde es solo tuyo para este repositorio.

Divide un archivo grande con importaciones

Cuando tu archivo de proyecto empieza a alargarse, puedes dividirlo en partes usando la sintaxis de importación ruta-al-archivo. En lugar de un muro de texto, apuntas a otros archivos:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

Esto es genial para organizar. Pero debes saber exactamente qué te aporta, porque es fácil malinterpretarlo. Cuando Claude se inicia, expande esos archivos importados en línea, justo donde los referenciaste. Así que las importaciones te ayudan a mantener las cosas ordenadas, pero todo se sigue cargando de antemano. No reducen la cantidad de contexto que Claude tiene que leer. Usa las importaciones para organizar, no para reducir la carga.

La redacción es lo que hace que las reglas se mantengan

Una vez que has decidido que una regla pertenece a CLAUDE.md, que Claude realmente la obedezca depende de cómo la redactes. La mayoría de las reglas fallan porque son vagas. Así es como se arregla eso.

Sé específico y verificable

No escribas "sigue las mejores prácticas". ¿Sabes siquiera exactamente qué significa eso? Si no puedes verificar si se siguió, tampoco puede Claude. Compara estas dos:

  • Vago: "Sigue las mejores prácticas para rutas de API."
  • Específico: "Pon las nuevas rutas de API en src/api/handlers, una por archivo."

La segunda es explícita. Puedes mirar el resultado y saber de inmediato si se hizo bien. Esa es la vara que toda regla debe alcanzar.

Nombra el reemplazo, no solo prohíbas algo

Cuando le dices a Claude que no haga algo, di qué hacer en su lugar. De lo contrario, dejas la puerta abierta.

  • Deja la puerta abierta: "No uses exportaciones por defecto." Bien, ¿pero entonces qué?
  • La cierra: "Usa exportaciones nombradas, no exportaciones por defecto."

La segunda versión nombra el reemplazo, así que no queda nada por malinterpretar.

Fórmula la regla con sencillez en vez de gritar

Palabras como "IMPORTANTE" y "DEBES" rara vez rescatan una regla que Claude sigue sin cumplir. Los modelos actuales siguen una línea redactada con sencillez, y acumular énfasis más bien hace que Claude aplique la regla en exceso. Si una regla no puede doblarse, conviértela en un hook. Si se está perdiendo, acorta el archivo.

Mantén el archivo en revisión constante

Tu archivo CLAUDE.md nunca está terminado. Trátalo como código vivo que se sigue editando.

Cuando Claude hace algo mal, no solo suspires y lo arregles a mano. Trátalo como un reporte de error contra tu archivo CLAUDE.md. Incluso puedes decírselo directamente a Claude: "agrega eso al archivo CLAUDE.md", y él escribirá la regla por ti. De esa forma, el archivo mejora cada vez que algo sale mal.

La conclusión

Trata tu CLAUDE.md como código de producción. Si no puedes justificar una línea, elimínala. Para mantener el archivo esbelto y fácil de seguir:

  1. Mueve las reglas duras a hooks, donde realmente se aplican.
  2. Organiza archivos largos con importaciones (solo recuerda que no reducen el contexto).
  3. Haz que cada regla sea específica y verificable, y nombra el reemplazo.
  4. Redacta las reglas con sencillez en vez de agregar énfasis.
  5. Sigue revisando el archivo siempre que Claude se equivoque en algo.

La idea completa es simple. Mientras más esbelto sea el archivo, más de él sigue Claude.