Una guía práctica para crear un archivo CLAUDE.md eficaz.
Aprende 21 reglas concretas y verificables para reducir el tamaño de un archivo CLAUDE.md excesivamente grande, a fin de que Claude Code siga siendo fiable, predecible y fácil de confiar en sesiones prolongadas.
El mes pasado, un desarrollador eliminó 340 líneas de un archivo CLAUDE.md que había ido creciendo durante un año.
El archivo se expandía de forma constante. Cada vez que Claude Code hacía algo molesto, se añadía una nueva regla. Cada vez que una regla no funcionaba, se agregaba una versión más larga debajo de ella. Para agosto, el archivo contaba con 400 líneas, y el comportamiento de Claude era notablemente peor que cuando el archivo tenía solo 60 líneas.
Después de reducirlo a 61 líneas, la mejora se notó ese mismo día.
Esto en realidad no es una lección sobre disciplina personal. Es una lección sobre para qué sirve un archivo de reglas. No es una lista de deseos que se va acumulando con el tiempo. Es un conjunto de instrucciones que el modelo lee al inicio de cada sesión, y cada línea adicional debe competir por atención con todo lo demás que ya está allí.
A continuación se presentan las 21 reglas que superaron la selección, junto con la razón detrás de cada una.
El verdadero costo de un CLAUDE.md sobredimensionado
En agosto de 2026, alguien de la comunidad Claude Code decidió probar algo que parece obvio pero que nadie había verificado realmente: si Claude sigue de verdad las instrucciones de CLAUDE.md que se le dan.
Una primera revisión reveló que el 55.7% de las reglas en un archivo típico podían comprobarse, al menos en principio. Una revisión manual redujo esa cifra al 18%, luego al 8.75%, y finalmente se estabilizó en 6.67%.
Piensa en ese número por un momento. En un CLAUDE.md típico, solo alrededor de una regla de quince puede ser verificada realmente. Las catorce restantes son, en esencia, consejos generales como “escribe código limpio”, “sigue las mejores prácticas” o “ten cuidado con el rendimiento”. Nadie, ni el modelo ni tú, puede determinar si realmente se siguieron.
Ese es el verdadero costo de un archivo sobrecargado. No se trata solo de que las reglas no verificables sean ignoradas, sino también de que siguen ocupando espacio en la ventana de contexto en cada turno, ocupando el lugar de las reglas que realmente podrían ser importantes.
Alrededor de la misma época, los propios ingenieros de Anthropic realizaron una observación similar sobre las instrucciones del sistema: más allá de cierta longitud, añadir más indicaciones empeora el rendimiento en lugar de mejorarlo. Sus modelos más recientes ahora vienen con instrucciones del sistema que ocupan una fracción del tamaño que tenían anteriormente.
Su archivo CLAUDE.md sigue exactamente el mismo patrón. Las 21 reglas que se presentan a continuación están diseñadas para mantenerse en el lado productivo de esa curva.
Reglas 1–7: Detener los daños
Estas primeras reglas existen para evitar que Claude convierta una tarea sencilla en un desastre.
Regla 1: Realizar únicamente ediciones precisas
## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file, even if you would write it differently.
Por qué funciona: Sin esta restricción, Claude tiende a “mejorar” cada archivo al que accede. Pides una corrección de una sola línea y terminas revisando un diferencial de 200 líneas donde tu corrección real está oculta en algún lugar. Esta es probablemente la queja más común sobre los agentes de programación, y también una de las más fáciles de resolver.
Antes: Pides una corrección para un error de “off-by-one” dentro de una función de callback. En lugar de eso, el código se convierte a async/await, tres variables reciben nuevos nombres, y el error original sigue estando allí.
Después: Solo cambia una línea. Revisarla lleva unos cuatro segundos.
Regla 2: Nunca reescribas mis pruebas
## Tests
Do not edit existing tests to make failing code pass.
If a test fails, fix the code.
If you believe the test itself is wrong, say so and stop. Do not edit it.
Por qué funciona: Un modelo al que se le indica que haga que las pruebas pasen siempre tomará el camino más corto disponible, y reescribir una afirmación es más sencillo que corregir realmente el error subyacente. Esta regla elimina por completo ese atajo.
Antes: Tres pruebas pasan. Dos de ellas ahora afirman algo incorrecto.
Después: Claude informa que una prueba espera 404 mientras el código devuelve 500, y luego pregunta cuál es realmente incorrecto.
Regla 3: No añada una dependencia
## Dependencies
Do not add packages. Use what is already in package.json.
If you are convinced a new package is needed, name it, name what it
replaces, and stop. Wait for approval.
Por qué funciona: Cada agente de programación recurre a una nueva biblioteca de la misma manera en que lo haría un desarrollador junior. Si no se controla, uno termina con tres paquetes separados para manejar fechas y un tamaño del paquete que nadie puede explicar.
Antes: Una sencilla tarea de formato de fecha de cuatro líneas se convierte en una nueva dependencia además de un cambio en el archivo de bloqueo.
Después: Las mismas cuatro líneas, creadas utilizando la API Intl que ya estaba disponible.
Regla 4: No hay manejo de errores para situaciones que no pueden ocurrir
## Error Handling
Handle errors that can actually occur here.
Do not add try/catch around code that cannot throw.
Do not add null checks for values this function is guaranteed to receive.
Por qué funciona: El código defensivo escrito para protegerse contra estados imposibles en realidad no es una medida de seguridad, sino un obstáculo. Oculta las dos verificaciones que realmente importan y duplica la longitud de una función sin ningún beneficio.
Antes: Una función de 12 líneas repleta de cuatro cláusulas de protección, tres de las cuales nunca pueden activarse.
Después: La misma función de 12 líneas, manteniendo solo la verificación que realmente podría fallar.
Regla 5: No toque lo que no le han pedido que toque
## Scope
Work only on what was asked.
Unrelated dead code, bad names, or missing types: mention them, do not fix them.
Remove imports and variables that YOUR change made unused. Nothing else.
Por qué funciona: El crecimiento excesivo del alcance oculto dentro de un diff permanece invisible hasta que alguien lo revisa, y para entonces ya se ha desperdiciado tiempo valioso. Definir claramente los límites desde el principio evita las dudas sobre qué se considera aceptable.
Regla 6: Nunca guardar secretos
## Security
Never write a key, token, password, or connection string into a file.
Never commit .env, .env.*, or any credentials file.
If a value is needed, reference the environment variable by name.
Por qué funciona: Este es uno de los pocos casos en los que un solo error es irreparable. La instrucción es breve, incondicional y fácil de verificar, lo cual es exactamente la forma que debe tener una buena regla.
Regla 7: Preguntar antes de hacer algo destructivo
## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, or running a
migration against anything that is not local.
Por qué funciona: Un modelo no tiene una noción inherente de lo que se puede y no se puede deshacer. Desde su punto de vista, modificar la historia y formatear un archivo de texto son el mismo tipo de acción: simplemente otra llamada a una herramienta. Esta regla le proporciona una categoría de riesgo que, de otro modo, no podría reconocer por sí mismo.
Reglas 8-14: Escriba reglas que realmente pueda seguir
Esta es la sección que aborda el problema subyacente detrás de ese bajo índice de cumplimiento. Estas reglas no se refieren directamente al comportamiento, sino a cómo formular las reglas que rigen dicho comportamiento.
Regla 8: Cada regla debe poder verificarse
Bad: Write clean, maintainable code.
Good: Functions over 40 lines must be split.
Por qué funciona: Si no puedes echar un vistazo a la salida y responder sí o no, la regla no hace nada más que ocupar espacio en el contexto. Antes de añadir una línea a este archivo, pregúntate qué evidencia demostraría que se ha violado. Si no puedes responder, no añadas la regla.
Antes: Una instrucción como “escribe código limpio y mantenible” permanece sin usar en tu archivo durante meses. Nunca influye en ninguna salida, y nunca puedes señalar un caso en el que se haya incumplido.
Después: Aparece una función de 61 líneas en un diff, y puedes señalar directamente la regla que se ha violado. A partir de ahí, o se respeta la regla o se elimina. Cualquiera de los dos resultados hace que las cosas avancen.
Regla 9: Una regla, una línea
Bad: When you are working on components, please try to keep them
focused and reasonably small, and generally avoid mixing data
fetching with presentation where that makes sense.
Good: Components do not fetch data. Fetch in the route, pass props down.
Por qué funciona: Una regla expresada en términos vagos suena como una sugerencia suave. Las sugerencias siempre pierden frente a lo que el modelo ya estaba inclinado a hacer.
Regla 10: Nombra el archivo, no los sentimientos
Bad: Follow our API conventions.
Good: New routes follow the shape in src/api/users/route.ts.
Por qué funciona: Frases como “nuestras convenciones” solo tienen sentido para ti, el ser humano. Una ruta de archivo es algo que el modelo puede abrir y leer realmente. Apuntar a código real e existente es mejor que cualquier descripción escrita de ese código.
Regla 11: Prohibir en lugar de fomentar
Bad: Prefer simple solutions.
Good: Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Por qué funciona: Palabras como “preferir” solo entran en juego como factor de desempate, y únicamente cuando el modelo ya está indeciso. En cambio, “no hacer” funciona como una prohibición estricta. Casi todas las reglas que fallan en el uso real lo hacen porque se formularon como un estímulo en lugar de una prohibición.
Hay una prueba sencilla para esto: lee la regla y pregúntate si un modelo decidido a hacer lo que intentas evitar podría, técnicamente, seguir la regla tal como está escrita. Si es así, lo que has escrito es una preferencia, no una regla.
Regla 12: Coloca la regla donde se realiza el trabajo
Core rules live in the root CLAUDE.md, not only in path-scoped rule files.
Por qué funciona: Este caso es fácil de pasar por alto y puede causar un verdadero error si se ignora. En agosto de 2026, se presentó un problema contra Claude Code que describía cómo los archivos de reglas con alcance por ruta pueden fallar silenciosamente al cargarse cuando el agente modifica archivos mediante comandos de shell en lugar de su herramienta de edición integrada, ya que la inyección de reglas está vinculada a ese método de edición. Otros usuarios reportaron el mismo fallo con reglas almacenadas en archivos de subdirectorios anidados.
La lección sigue siendo válida independientemente de si ese error específico se corrige o no. Todo aquello que realmente no se puede permitir pasar por alto debe encontrarse en el archivo raíz que siempre se carga, y no escondido en un archivo condicional que solo se carga ocasionalmente.
Regla 13: Limitar la longitud del archivo
CLAUDE.md stays under 60 lines. If you need line 61, delete something first.
Por qué funciona: Esta es la regla que mejoró significativamente la configuración real de un equipo, y va en contra de la intuición. Al extender el archivo a 400 líneas no se obtienen 400 reglas con las que el modelo pueda actuar; simplemente se genera un bloque denso de texto donde las instrucciones críticas se mezclan con el contenido adicional.
Sesenta líneas no son un umbral mágico. Lo importante es la restricción en sí: agregar una nueva regla debe hacer que se elimine una antigua, de modo que solo permanezcan las reglas que realmente valen la pena conservar.
Regla 14: Mantener las reglas, habilidades y flujos de trabajo en lugares separados
CLAUDE.md : rules that apply to every single task
.claude/skills : reference material, read only when relevant
.claude/commands : fixed step sequences, invoked by name
Por qué funciona: La mayoría de los archivos de reglas demasiado grandes se convierten así porque en realidad contienen tres tipos diferentes de documentos mezclados en uno. Una descripción del esquema de tu base de datos no es una regla, al igual que la secuencia de despliegue. Una vez que se separa ese material, las reglas que quedan vuelven a ser visibles en lugar de quedar ocultas.
Reglas del 15 al 21: Hacer que el comportamiento perdure durante una sesión larga
Una regla que el modelo sigue en la tercera turno pero olvida en el cuadragésimo turno nunca fue realmente una regla. Este conjunto de pautas tiene como objetivo que las instrucciones se mantengan vigentes durante toda la duración de la sesión.
Regla 15: Mantener las reglas en el archivo, no solo en la conversación
Any instruction that must hold for the whole project belongs in this file.
Instructions given in conversation apply to the current task only.
Por qué funciona: Las sesiones largas terminan comprimiéndose en algún momento. Cuando ocurre esa compresión, los detalles de la conversación se resumen mientras los archivos se vuelven a cargar por completo. Una cuenta de agosto de 2026 ilustra esto perfectamente: un usuario le indicó al modelo en dos ocasiones que nunca aumentara la versión del paquete; la compresión tuvo lugar a mitad de proceso, y para la cuarta ocasión la versión ya había sido actualizada de todos modos. Nada se colapsó ni generó error: la instrucción simplemente dejó de existir en el contexto de trabajo del modelo.
Si te das cuenta de que vuelves a formular la misma instrucción en el chat más de una vez, considéralo una señal. Esa instrucción debe estar en el archivo, no en lo que escribes tú.
Regla 16: Vuelve a cargar el archivo de reglas después de la compresión
After any context compaction, re-read CLAUDE.md before the next edit.
Por qué funciona: Es una medida de protección económica contra exactamente el fallo descrito en la Regla 15, y es una de las pocas reglas donde se puede confirmar directamente el cumplimiento simplemente escaneando la transcripción.
Regla 17: Especifique la orden precisa utilizada para verificar el trabajo
## Verification
Before saying a task is done, run:
npm run typecheck && npm test -- --run
Paste the final line of output. If it fails, fix it. Do not report success.
Por qué funciona: Una instrucción como “asegúrese de que las pruebas pasen” no le da al modelo nada concreto para ejecutar. Una orden de shell literal sí lo hace, y exigir la salida pegada permite verificar la afirmación de éxito de inmediato en lugar de confiar ciegamente en ella.
Regla 18: Explique claramente qué significa realmente “hecho”
## Done
A task is done when: the change is made, typecheck passes, tests pass,
and you have stated in one sentence what changed and why.
Not done: "this should work", "you may want to verify".
Por qué funciona: Si se deja sin definir, el modelo proporcionará su propia definición de “completado”, y esa definición suele ser simplemente “He generado algún texto”. Esta única regla hace más que cualquier otra para reducir el número de ocasiones en las que, una hora después, descubres que la compilación está realmente rota.
Regla 19: Limita los comentarios a un único cambio accionable
When something did not work, name ONE thing to change and why.
Do not list five options.
Por qué funciona: Ofrecer cinco opciones diferentes cuando algo falla es en realidad una forma de evitar tomar una decisión. También hace imposible rastrear qué fue lo que realmente solucionó el problema, ya que no se puede determinar cuál de las cinco sugerencias fue importante.
Regla 20: Pregunta en lugar de adivinar
If you need information you do not have, output:
MISSING: <exactly what you need>
and stop. Do not assume a plausible value and continue.
Por qué funciona: Esta podría ser la línea más valiosa de todo el archivo. Casi todos los incidentes graves con un agente se deben a que este completa un detalle faltante con confianza en lugar de detenerse para preguntar. Un rechazo te cuesta treinta segundos; una suposición errónea hecha con confianza puede costar toda una tarde, y generalmente no te das cuenta hasta varios cambios posteriores.
Antes: El modelo necesita un nombre de cola que nunca especificaste. Usa por defecto algo como default, crea una integración que parece correcta, y las tareas se acumulan en una cola que nadie consume. Te das cuenta días después.
Después: Muestra MISSING: the queue name for the retry consumer. Proporcionas la respuesta en cinco segundos, y el código resultante es correcto desde el principio.
Existe una forma sencilla de comprobar si esta regla está realmente activa: solicitar algo que dependa de información que se haya omitido intencionadamente. Si el modelo responde de todos modos en lugar de señalar esa falta, la regla solo existe en teoría.
Regla 21: Continuar con la reducción, una regla al mes
Once a month, remove any rule you have not seen violated recently.
Por qué funciona: Los archivos de reglas tienden a expandirse sin fin, ya que añadir una nueva parece un progreso mientras que eliminar una se percibe como un riesgo. Pero si una regla no se ha aplicado en los últimos meses, o bien ya no es necesaria o nunca se cumplió realmente. En cualquier caso, consume atención en cada interacción. Eliminarla es la forma más económica de mejorar el rendimiento.
Cinco reglas que se eliminaron
El recorte era más importante que cualquier cosa que se añadiera, por lo que aquí hay cinco entradas que antes estaban en un archivo de 400 líneas y ahora faltan en la versión actual de 61 líneas. Si alguna de estas le resulta familiar, probablemente pueda eliminarlas esta noche.
“Piensa en el problema paso a paso antes de programar.” Este ya es el comportamiento por defecto. Las versiones actuales de Claude Code planifican su enfoque antes de tocar los archivos, sin necesidad de indicaciones adicionales. Esta línea era un vestigio de hábitos antiguos y solo servía para ocupar espacio.
“Ten cuidado con los problemas de rendimiento.” Esta no pasa la prueba de verificabilidad: ¿cuidadoso con respecto a qué referencia? Fue reemplazada por dos reglas específicas y verificables sobre el acceso a bases de datos, las cuales sí detectan problemas reales.
Un resumen de 90 líneas del esquema de la base de datos. Eso es documentación, no una regla. Debería estar en un archivo de habilidades que se carga cuando el modelo realiza tareas relacionadas con la base de datos, no en el archivo que se lee antes de cada tarea, incluso en algo tan trivial como un ajuste CSS. Extraer esta sección fue la mayor reducción posible.
“Nunca uses any en TypeScript.” Esta no estaba mal, pero era redundante: el linter ya la bloquea. Todo lo que la cadena de herramientas ya impone no necesita ocupar espacio en el archivo de reglas. Si una infracción puede detectarse en CI, deja que sea CI quien la detecte.
“Añada comentarios útiles.” Cualquier intento de formularlo generó comentarios que simplemente repetían la línea de código que los precedía. La solución fue invertirlo: no explique qué hace el código, sino solo por qué lo hace. Esa versión es tanto más efectiva como una línea más corta.
El patrón es consistente en los cinco casos. Dos contenían algo que el modelo o las herramientas ya habían manejado por sí solos. Dos no pudieron verificarse de manera concreta. Uno era material de referencia disfrazado de regla. Busque estas mismas cuatro categorías en su propio archivo, y los candidatos para su eliminación aparecerán rápidamente.
El archivo completo, listo para usar
# CLAUDE.md
## Stack
Next.js 15 App Router, TypeScript strict, Postgres via Drizzle, Vitest.## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file.## Scope
Work only on what was asked.
Mention unrelated problems, do not fix them.
Remove imports your change made unused. Nothing else.## Abstractions
Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Functions over 40 lines must be split.## Tests
Do not edit existing tests to make failing code pass.
If a test is wrong, say so and stop.## Dependencies
Do not add packages. Use what is in package.json.
To add one: name it, name what it replaces, stop, wait.## Error Handling
Handle errors that can actually occur here.
No try/catch around code that cannot throw.## Patterns
New routes follow src/api/users/route.ts.
Components do not fetch data. Fetch in the route, pass props down.
Database access goes through src/db/queries/. Never inline SQL.## Security
Never write a key, token, password, or connection string into a file.
Never commit .env or .env.*.
Reference environment variables by name only.## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, running a
migration against anything not local.## Verification
Before reporting done, run:
npm run typecheck && npm test -- --run
Paste the final line. If it fails, fix it. Do not report success.## Done
Done means: change made, typecheck passes, tests pass, and one sentence
saying what changed and why.## When Stuck
If you need information you do not have, output:
MISSING: <what you need>
and stop. Do not assume a value and continue.## Reporting
Name ONE thing to change. Not five options.## Persistence
Rules live here, not in chat. After compaction, re-read this file.
Ese es todo el archivo: sesenta y una líneas.
Qué cambió
Después de reducir el archivo de 400 líneas a 61:
- Se detuvieron las reescrituras de archivos. La regla de edición quirúrgica también existía en la versión sobredimensionada. Solo comenzó a respetarse una vez que dejó de estar oculta alrededor de la línea 213.
- La regla
MISSING:pasó a estar activa. Ahora se dispara aproximadamente dos veces por semana, deteniéndose para preguntar en lugar de inventar un valor de configuración. Anteriormente, ambas situaciones habrían generado resultados incorrectos e invisibles. - Las sesiones largas dejaron de desviarse. El problema relacionado con los cambios de versión, junto con tres problemas similares, desapareció una vez que las reglas se anclaron en el archivo en lugar de estar dispersas en mensajes anteriores de chat.
- Las revisiones se aceleraron, simplemente porque las diferencias eran menores. Ese es todo el mecanismo: nada más sofisticado que eso.
No hay una comparación clara de antes y después que presentar aquí, ni se creará ninguna con el fin de contar una historia ordenada. En su lugar, existe un archivo que lleva un minuto leer, junto con un comportamiento que realmente coincide con lo que indica.
Siguientes pasos
- Abre tu CLAUDE.md actual y cuenta las líneas.
- Léelo una vez, marcando cada regla para la cual no puedas señalar una violación concreta en caso de que ocurriera. Elimina esas.
- Convierte cada “preferir” y “tratar de” en un “no hacerlo” explícito.
- Sustituye cualquier referencia a “nuestras convenciones” por una ruta de archivo real.
- Si no tienes algo similar a la Regla 20, añádela. Es la única regla que justifica realizar todo este ejercicio.
Después de eso, deja el archivo sin tocar durante un mes. Cuando vuelvas a él, busca algo más para eliminar.
Las reglas que realmente funcionan comparten las mismas características: son breves, absolutas y verificables. Todo lo demás no es más que una nota para uno mismo que el modelo termina leyendo cientos de veces al día sin ningún beneficio.
Lecturas relacionadas
- Comparación de agentes AI de Frontier: Astra, Flash, Fable y Mythos — Un análisis del rendimiento de las últimas versiones de los modelos GPT, Gemini y Claude en tareas reales de agencia como programación, navegación y uso de herramientas, no solo en pruebas estándar.
- Elegir un marco de trabajo para agentes AI en Python en 2026: Una comparación práctica — Compara cinco marcos de trabajo para agentes AI en Python según su manejo de fallos y complejidad, ayudando a los lectores a elegir la herramienta adecuada para su flujo de trabajo.