Un CLAUDE.md que se sigue

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 reglas son líneas duras que nunca deben cruzarse. Esos son dos trabajos diferentes.

Toma una regla como "nunca hagas push a main". Si pones eso en CLAUDE.md, estás esperando que Claude la lea y la 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 puede realmente 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 petición educada. 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 está 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 cada proyecto de tu máquina.
• Proyecto — el archivo compartido con tu equipo, incluido en el repositorio.
• Local — ignorado por git. Tus notas personales solo para este repositorio.

Ese último, 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 cuenta 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 piezas usando la sintaxis de importación de ruta a 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 sabe exactamente qué te aporta, porque es fácil hacerse una idea equivocada. 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 por adelantado. 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 arreglarlo.

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:

• Vaga: "Sigue las mejores prácticas para las rutas de API."
• Específica: "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 con la que debe medirse cada regla.

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, has dejado la puerta abierta.

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

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

El énfasis es un presupuesto

Palabras como "IMPORTANTE" y "DEBES" sí elevan la prioridad de una regla. Pero solo en relación con todo lo demás que está más tranquilo alrededor. Si todas las reglas gritan, entonces nada destaca y el énfasis no significa nada. Así que trata el énfasis como un presupuesto. Gástalo en las dos o tres reglas que realmente duelen cuando se rompen, y deja que el resto se quede a volumen normal.

Mantén el archivo en revisión

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

Cuando Claude hace algo mal, no te limites a suspirar y arreglarlo 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 manera 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, bórrala. Para mantener el archivo ligero y seguible:

1. Mueve las reglas duras a hooks, donde realmente se aplican.
2. Organiza los 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. Gasta tu presupuesto de énfasis en las pocas reglas que más importan.
5. Sigue revisando el archivo cada vez que Claude se equivoque en algo.

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