¿Qué es CLAUDE.md y por qué te hace perder plata?
Si abrís Claude Code de fábrica y empezás a pedirle tareas, estás tirando el 80% de tu cuenta a la basura sin saberlo. El archivo CLAUDE.md es un documento de texto simple que le da instrucciones de sistema al agente para frenar su comportamiento derrochador por defecto.
El problema de Claude Code es que viene configurado para ser un asistente conversacional amigable. Eso significa que te saluda, te explica todo lo que hace, relee el contexto constantemente y, peor aún, reescribe archivos enteros de código solo para cambiar una coma. Todo eso se traduce en miles de tokens facturados por minuto que no aportan ningún valor real a tu código.
Por qué importa configurar estas reglas
Trabajar sin un archivo de reglas en la terminal es insostenible a largo plazo. Configurar estos límites te da tres beneficios inmediatos:
- Ahorro masivo de tokens: Cortás de raíz el consumo de salida (output tokens), que son los más caros.
- Velocidad de ejecución: Al no tener que generar párrafos de explicaciones ni reescribir archivos grandes, Claude Code termina las tareas en una fracción del tiempo.
- Precisión quirúrgica: Evitás que el agente "mejore" cosas que no le pediste, reduciendo la cantidad de bugs introducidos por accidente.
Comparativa: Claude Code de fábrica vs optimizado
| Comportamiento | Default Claude Code | Con CLAUDE.md optimizado |
|---|---|---|
| Edición de código | Reescribe el archivo completo | Usa diffs quirúrgicos (cambia solo 3 líneas) |
| Tono | "¡Claro! Excelente pregunta. Voy a..." | Directo al código, sin saludos |
| Manejo de contexto | Relee el mismo archivo varias veces | Confía en la memoria de la sesión |
| Autonomía | Corre tests y crea archivos por su cuenta | Pide permiso explícito antes de actuar |
| Consumo promedio | Altísimo (desperdicio de output tokens) | Hasta un 80% más bajo |
Las 8 reglas de oro para tu CLAUDE.md
Para domar a Claude Code, tenés que copiar y pegar estas 8 directivas exactas en tu archivo. Son mandatos simples pero que cambian por completo cómo opera el modelo.
1. Edits mínimos
Decile explícitamente que cuando le pidas cambiar 3 líneas, no te reescriba el archivo entero. Tiene que usar herramientas de búsqueda y reemplazo (old_string / new_string) en lugar de escupir todo el código de nuevo. Pagar por reescribir 500 líneas para arreglar un typo es un robo.
2. Nada de saludos
Sacá los "claro", "excelente pregunta", "perfecto" y "espero que esto te sirva" de cada respuesta. Prohibile el comportamiento de asistente virtual. Querés un ingeniero de software, no un bot de atención al cliente.
3. No releer el contexto
Que no te queme tokens leyendo lo mismo dos veces en la misma sesión. Si ya abrió el App.tsx hace cinco minutos, tiene que confiar en lo que ya tiene cargado en memoria en lugar de volver a pedir el archivo completo.
4. Respuestas cortas
Sin parrafadas explicando lo que ya sabés. Si le pedís que arregle un bug de CSS, querés el comando o el código modificado, no una tesis sobre cómo funciona Flexbox.
5. No inventar archivos
Si el archivo no existe, que pregunte antes de crear. A veces Claude alucina rutas o asume arquitecturas que no son las tuyas y empieza a sembrar archivos inútiles por todo tu repositorio.
6. No auto-test
Que no corra el test suite a menos que se lo pidas vos. Ejecutar npm run test en un proyecto grande consume tiempo, satura la terminal y llena el contexto de logs de consola que Claude va a tener que procesar (y cobrarte).
7. Commits limpios
Mensajes cortos, directos y sin coautores agregados. Claude Code tiene la mala costumbre de firmar los commits o hacer descripciones larguísimas. Forzalo a usar el formato convencional (fix:, feat:) en una sola línea.
8. No tocar lo que no se pidió
El scope es sagrado. Si te pedí cambiar X, no me toque Y con la excusa de "mejorarlo" o "refactorizarlo". Esta regla evita dolores de cabeza gigantes cuando vas a revisar el diff y te das cuenta de que formateó la mitad del proyecto sin permiso.
Cómo empezar a ahorrar hoy mismo
Implementar esto te lleva literalmente un minuto y el impacto en tu facturación mensual es inmediato.
- Creá el archivo: Andá a la raíz de tu proyecto (donde está tu
package.jsono equivalente) y creá un archivo vacío llamadoCLAUDE.md. - Pegá las reglas: Escribí las 8 reglas mencionadas arriba en formato Markdown. Podés usar viñetas simples o listas numeradas.
- Ajustá tu stack: Si querés, agregá una línea extra con las convenciones de tu proyecto (por ejemplo: "usamos Tailwind", "usamos pnpm").
- Reiniciá la sesión: Cerrá Claude Code si lo tenías abierto y volvé a correr el comando
claude. El agente va a leer el archivo apenas arranque.
El impacto real en tu flujo de trabajo
Con estas 8 reglas activas, tu Claude Code va a consumir un 80% menos de tokens, va a tardar la mitad del tiempo en responder y va a hacer exactamente lo que le pedís sin desvíos.
Dejás de pelear contra un asistente conversacional que quiere explicarte todo, y pasás a tener una herramienta de terminal quirúrgica que ejecuta código rápido y barato. Es literalmente un archivo de texto; no hay excusa para no tenerlo configurado en todos tus repositorios.
Preguntas frecuentes sobre CLAUDE.md
CLAUDE.md es un archivo Markdown que funciona como el cerebro persistente o la memoria de tu proyecto cuando usás Claude Code en la terminal. En lugar de tener que explicarle tus reglas de formateo, preferencias de código o restricciones de tokens en cada nueva sesión, escribís todo una sola vez en este documento. Cuando iniciás la herramienta, Claude lee automáticamente estas instrucciones y las aplica a todas sus respuestas y acciones. Esto es fundamental porque, por defecto, el modelo asume comportamientos conversacionales que son muy caros en consumo de tokens. Al definir directivas estrictas en la raíz de tu repositorio, lográs que el agente se comporte exactamente como vos querés, desde el primer prompt. Si querés profundizar en cómo funcionan los agentes de terminal, te recomiendo leer nuestra guía completa sobre Claude Code y revisar la documentación oficial de Anthropic.
Si usás Claude Code recién instalado sin configurarlo, vas a notar que tu saldo de tokens baja rapidísimo. Esto pasa porque el modelo base está entrenado para ser conversacional y servicial. Entonces, te responde con saludos largos como "¡Claro que sí! Voy a ayudarte con eso", te explica conceptos que ya sabés y, lo más grave, reescribe archivos enteros de cientos de líneas solo para cambiar una variable. Además, tiende a releer el mismo contexto varias veces y ejecuta suites de tests completas por su cuenta para asegurarse de que todo funcione. Cada una de estas acciones invisibles consume miles de tokens de entrada y salida. Para evitar esta fuga de saldo, es obligatorio imponer límites estrictos. Podés aprender más sobre cómo optimizar el uso de los modelos en nuestra sección de herramientas de IA o ver estrategias avanzadas en los 6 tips de Boris Cherny para dominar Opus 4.7.
Para que Claude Code detecte y aplique tus reglas automáticamente, tenés que guardar el archivo con el nombre exacto CLAUDE.md en la raíz de tu proyecto, justo al lado de tu package.json, pyproject.toml o archivo de configuración principal. Si trabajás en un equipo, lo ideal es commitear este archivo en tu repositorio de Git para que todos los desarrolladores hereden las mismas reglas y ahorren tokens. Si preferís tener reglas privadas que no se compartan con el resto, podés crear un archivo llamado CLAUDE.local.md, que tiene prioridad pero debe agregarse al .gitignore. Además, podés configurar un archivo global en tu computadora ubicado en ~/.claude/CLAUDE.md para que aplique a todos tus proyectos por defecto. Podés consultar más detalles técnicos sobre el manejo de memoria en la documentación de Anthropic o explorar otras guías de automatización en nuestra plataforma.
Cuando existe un conflicto entre lo que le pedís en el prompt actual y lo que está escrito en tu archivo CLAUDE.md, Claude Code generalmente le da prioridad a las instrucciones del archivo base, ya que actúan como sus directivas de sistema o "system prompt". Sin embargo, si sos extremadamente explícito en tu pedido, podés forzarlo a ignorar una regla temporalmente. Por ejemplo, si tu archivo dice "nunca corras los tests", pero vos le escribís "por esta única vez, ignorá la regla y ejecutá el test suite completo", el modelo suele obedecer la instrucción directa. De todas formas, la mejor práctica es mantener el archivo optimizado para el 90% de tus casos de uso diarios y manejar las excepciones manualmente. Si querés aprender a darle instrucciones más precisas a los modelos, te sugiero revisar nuestra colección de prompts avanzados y leer sobre las mejores prácticas de prompting.
No, implementar estas ocho reglas restrictivas no baja la calidad del código generado, sino que mejora drásticamente la precisión y velocidad del agente. Al prohibirle que toque archivos que no le pediste o que invente soluciones no solicitadas, estás reduciendo la superficie de error y limitando las alucinaciones. Claude Code se vuelve mucho más predecible y quirúrgico: hace exactamente lo que le indicás y nada más. Esto es clave en proyectos grandes donde un cambio automático no deseado puede romper dependencias complejas. La calidad del razonamiento lógico del modelo (como Opus 4.7 o Sonnet 3.7) sigue siendo la misma, pero le sacás el ruido innecesario. Para entender cómo los modelos más grandes mantienen su nivel de inteligencia incluso con prompts estrictos, podés leer nuestra guía sobre Claude Opus 4.7 o visitar el blog oficial de Anthropic para ver los últimos benchmarks.
Fuentes e inspiración
Mirá los posts originales donde desarrollamos estas ideas en redes.
