CLAUDE.md: Prepara tu Repositorio para IA y Reduce el Desperdicio de Tokens

El Problema de Cómo la Mayoría de Desarrolladores Usa IA

Imagina que contratas a un contratista para renovar tu cocina. Llega, mira alrededor y pregunta: “¿Cómo se ve esta casa? ¿Qué estilo prefieres? ¿Dónde corren las tuberías? ¿Hay presupuesto?”

Explicas todo. Asiente, toma notas y comienza a trabajar.

Dos semanas después, el mismo contratista vuelve para otro trabajo. Hace todas las mismas preguntas de nuevo.

Eso es lo que sucede cada vez que abres una nueva conversación con IA sin darle contexto estructural al modelo. El modelo no tiene memoria de tu proyecto, tus convenciones, tu stack tecnológico, o tus preferencias. Cada sesión comienza desde cero. Cada sesión quema tokens reestableciendo lo que ya sabes.

El costo es real: respuestas más lentas, sugerencias menos precisas, y una carga cognitiva para ti repetiendo el mismo contexto cada vez.

Existe un mejor camino.

Qué Hace Realmente CLAUDE.md

Claude Code — la CLI de Anthropic para desarrollo asistido por IA — automáticamente lee un archivo llamado CLAUDE.md desde la raíz de tu repositorio al inicio de cada sesión. Sin prompt necesario. Sin setup. Solo carga.

Este archivo no es documentación para humanos. Es un documento de instrucciones para el modelo. Le dice al agente:

Qué es el proyecto y para quién
Cómo se estructura el codebase
Qué comandos usar
Qué convenciones seguir
Qué nunca debe hacer

Cuando el modelo lee este archivo al inicio de una sesión, no necesita explorar tu codebase para responder preguntas básicas. No necesita preguntar cuál es tu convención de nombres. No necesita adivinar si usas Bun o npm. Ese contexto ya existe.

El resultado: menos exploración, menos preguntas aclaratorias, respuestas más enfocadas, y consumo significativamente menor de tokens por tarea.

Los Dos Costos de Falta de Contexto

Hay dos tipos de desperdicio cuando un agente IA carece de contexto del proyecto.

Desperdicio de tokens ocurre cuando el modelo explora archivos que ya debería conocer, relee configuración que ha visto antes, o genera una respuesta que no sigue tus convenciones y tiene que ser corregida. Cada corrección es tokens adicionales. Cada relectura es tokens adicionales.

Desperdicio de atención ocurre cuando tú — el desarrollador — tienes que proporcionar contexto en lenguaje natural al inicio de cada conversación. “Este es un proyecto Astro. Usamos Bun. Español es el idioma por defecto. Nunca usamos emojis.” Escribir eso cada sesión añade fricción, y aún así no es tan confiable como un archivo estructurado.

Un CLAUDE.md bien escrito resuelve ambos a la vez.

Estructura de un CLAUDE.md Efectivo

El archivo no necesita ser largo. Necesita ser preciso. Un CLAUDE.md sin enfoque que incluya todo despilfarra los tokens que intentabas ahorrar. Escribe solo lo que el agente necesita para operar correctamente.

Aquí está la estructura que funciona:

1. Identidad del Proyecto (3-5 líneas)

Quién lo hizo, qué hace, y quién lo usa. Una oración cada uno.

**Quién:** Omar Flores (SazarDev), Desarrollador Full Stack.
**Qué:** Portafolio bilingüe y blog técnico. Astro 5, TypeScript, Tailwind, Netlify.
**Lectores:** Desarrolladores desde junior a senior. Escribe para que ambos puedan seguir.

2. Estructura del Proyecto (árbol de directorios)

Muestra los directorios que importan, con comentarios de una línea. Omite node_modules, dist, y cualquier cosa que el agente no debería tocar.

## Estructura del Proyecto

src/
  content/blog/es/   # Posts en español (.md)
  content/blog/en/   # Posts en inglés (.md)
  layouts/           # BaseLayout, BlogPostLayout
  data/content.json  # Todo el texto de UI — no hardcodees strings
  config/seo.ts      # Tags y categorías canónicas

3. Comandos

Los comandos exactos a ejecutar, nada más.

## Comandos

bun dev        # servidor de desarrollo
bun build      # build de producción
bun run check  # verificación de tipos

4. Reglas Duras

Las cosas que el agente nunca debe hacer. Sé específico — las reglas vagas se ignoran.

## Reglas Duras

- Sin emojis en ningún lugar.
- Sin auto-commit sin instrucción explícita.
- Sin refactorización fuera del alcance de la tarea.
- Siempre usa bun, no npm o yarn.
- Siempre añade variantes dark: de Tailwind junto con clases de modo claro.

5. Punteros a Contexto Más Profundo

Si el proyecto tiene convenciones de escritura específicas, patrones de componentes, o reglas de SEO, ponlas en archivos separados bajo .claude/ y referéncialos aquí. Esto mantiene CLAUDE.md corto mientras el detalle sigue disponible bajo demanda.

## Más Contexto

- Estilo de escritura y estructura de blog: .claude/rules.md
- Patrones de componentes y código: .claude/patterns.md
- Contexto técnico completo: .claude/context.md

El Directorio .claude/

CLAUDE.md siempre se carga. Los archivos dentro de .claude/ son material de referencia — el agente los lee cuando una tarea requiere ese conocimiento específico.

Piénsalo como una biblioteca. CLAUDE.md es el índice. Los archivos .claude/ son los capítulos.

.claude/rules.md — convenciones de escritura, voz, guía de estilo, estructura de post de blog, checklist de SEO. Se carga cuando la tarea implica creación o edición de contenido.

.claude/patterns.md — snippets de código listos para usar, templates de componentes, comparaciones de antipatrones, ejemplos de frontmatter. Se cargan cuando la tarea implica generar o revisar código.

.claude/context.md — versiones del stack tecnológico, rutas de archivos clave, arquitectura i18n, tokens del sistema de diseño, configuración de build. Se cargan cuando la tarea implica decisiones arquitectónicas o partes desconocidas del codebase.

Cada archivo es denso y específico. Sin relleno. Sin repetición entre archivos. Si algo pertenece a context.md, no está también en rules.md.

Eficiencia de Tokens: La Mecánica Práctica

El consumo de tokens en una sesión de IA es aproximadamente:

tokens totales = prompt del sistema + contexto cargado + tu mensaje + respuesta del modelo

No puedes controlar el prompt del sistema. Puedes controlar el contexto cargado y qué tan precisamente escribes tus mensajes.

Principio 1: Carga contexto al frente, no mensajes.

Si el agente lee CLAUDE.md y .claude/context.md al inicio, tu mensaje puede ser corto: “Añade soporte de modo oscuro al componente BlogCard.” Sin ese contexto, la misma solicitud requiere: “Este es un proyecto Astro usando Tailwind CSS con una estrategia de clase .dark en <html>. El componente BlogCard está en src/components/blog/BlogCard.astro. El modo oscuro debe usar variantes dark: de Tailwind, no media queries. Por favor añade soporte de modo oscuro.”

Misma tarea. Una requiere 15 tokens. La otra requiere 80 tokens — y aún así corre el riesgo de perder una convención.

Principio 2: Archivos específicos cargan más rápido que exploración amplia.

Un agente que explora tu codebase para responder una pregunta lee docenas de archivos y produce miles de tokens intermedios. Una referencia a una ruta de archivo específica omite todo eso. Tus archivos .claude/ deberían incluir las rutas exactas de archivos para recursos clave.

Principio 3: Las reglas previenen ciclos de corrección.

Cada corrección duplica el costo de tokens de una tarea. Si el agente genera código sin variantes dark: y la corriges, ya has usado tokens para la salida errónea, la corrección, y la nueva salida. Una regla clara en CLAUDE.md elimina ese ciclo.

Principio 4: El contexto muerto cuesta tanto como el contexto vivo.

Un archivo CLAUDE.md que incluye reglas desactualizadas, configuración irrelevante, o explicaciones verbosas carga el mismo peso de tokens que uno que es actual y preciso. Revísalo cuando cambies tu stack. Elimina lo que ya no es verdad.

Memoria Entre Sesiones

Claude Code soporta un archivo de memoria persistente que se carga en cada sesión a través de todo el proyecto. La ruta es:

~/.claude/projects/[ruta-del-proyecto]/memory/MEMORY.md

Este archivo es diferente de CLAUDE.md. Está pensado para cosas que quieres que el agente recuerde entre conversaciones — no la estructura del proyecto (eso pertenece a CLAUDE.md) sino preferencias aprendidas, decisiones recurrentes, y resúmenes de referencia rápida.

Un MEMORY.md útil es corto — menos de 60 líneas — y cubre:

Identidad del proyecto y preferencia de runtime (una línea cada uno)
Recordatorios de comportamiento del agente (leer antes de actuar, explicar antes de código)
La voz de escritura en tres bullet points
Reglas de SEO en dos bullet points
El mapa de archivos para los recursos más accedidos

Cualquier cosa más larga que eso debería estar en un archivo .claude/, no en memoria.

Qué Cambia el Modo Agentic

Cuando usas Claude Code en modo agentic — donde el modelo puede leer archivos, escribir archivos, ejecutar comandos, y tomar secuencias de acciones — la calidad de tus archivos de contexto importa aún más.

Sin contexto, un agente en modo agentic explora ampliamente antes de actuar. Lee archivos de configuración para entender el stack. Lee múltiples componentes para entender patrones. Lee contenido existente para entender tono. Esta exploración es necesaria — pero es cara cuando la información ya existe en forma estructurada.

Con un buen setup de CLAUDE.md y .claude/, el agente puede moverse directamente a la tarea. Conoce el stack. Conoce las convenciones. Conoce qué herramientas usar. La exploración se vuelve enfocada en lugar de amplia.

Esto cambia significativamente el perfil de velocidad de tareas agentic. Las tareas que previamente requerían 10-15 llamadas de herramientas exploratorias antes de producir salida pueden reducirse a 2-3 cuando el agente comienza con contexto confiable.

Errores Comunes

Escribir CLAUDE.md como documentación para humanos. El archivo es un documento de instrucciones, no un README. Debe ser denso y estructurado, no narrativo y acogedor.

Incluir todo. Un CLAUDE.md de 500 líneas no es más útil que uno de 60 líneas. El agente lo carga todo — las partes relevantes y las irrelevantes. La longitud es costo.

Reglas vagas. “Escribe código limpio” no le dice nada al agente. “Sin any en TypeScript. Sin estilos inline. Siempre añade variantes dark: de Tailwind.” le dice al agente exactamente qué hacer.

No actualizarlo. Un CLAUDE.md que describe tu stack antiguo es peor que ninguno. Crea respuestas confiadamente incorrectas. Trátalo como un documento vivo.

Omitir la estructura .claude/. Si tu CLAUDE.md intenta incluir todas las convenciones, todos los patrones, y todo el contexto, se vuelve tanto demasiado largo para cargar eficientemente como demasiado corto para ser preciso. La división entre un archivo raíz conciso y archivos de referencia detallados en .claude/ es lo que hace que el sistema escale.

Un Punto de Partida Mínimo

Si quieres añadir esto a tu propio proyecto hoy, comienza con solo tres cosas:

1. Crea CLAUDE.md en la raíz del repositorio. Escribe la identidad de tu proyecto, estructura, comandos, y cinco reglas duras. Mantenlo bajo 80 líneas.

2. Crea .claude/rules.md con tus convenciones de código — nombres, formato, patrones de componentes, y cualquier cosa que un desarrollador senior en tu equipo sabría que uno nuevo no.

3. Crea un MEMORY.md corto en ~/.claude/projects/[ruta-de-tu-proyecto]/memory/MEMORY.md. Pon solo las cosas que quieres que el agente recuerde sesión tras sesión: tu preferencia de runtime, las reglas más importantes, las rutas de archivo que necesita más frecuentemente.

Eso es suficiente para ver una diferencia significativa en calidad de respuesta y eficiencia de tokens. Entre más específico seas, más el sistema se compone con el tiempo.

El Retorno Compuesto

La primera vez que escribes CLAUDE.md, inviertes una hora. Cada sesión después de eso, ahorras cinco minutos y docenas de tokens. Con el tiempo, eso se compone en un flujo de trabajo de desarrollo mediblemente más rápido.

Más importantemente, el agente se vuelve más predecible. Sigue tus convenciones. No te sorprende con patrones incorrectos. No necesita ciclos de corrección. La interacción se vuelve más como trabajar con un desarrollador que conoce tu codebase, y menos como contratar un nuevo contratista cada día.

El agente no puede leer tu mente. Dale las instrucciones que necesita, y dejará de pedirte que te repitas.