No necesitas un archivo claude.md gigante para trabajar con IA

En los últimos meses se ha vuelto común ver proyectos que incluyen archivos como claude.md, agents.md o similares. Estos archivos suelen contener instrucciones sobre el proyecto para ayudar a los agentes de IA a entender el código.

Sin embargo, una investigación reciente cuestiona esta práctica: los archivos de contexto a nivel de repositorio no siempre ayudan a los agentes de código y, en muchos casos, pueden incluso empeorar su rendimiento.

Esto es importante porque muchas herramientas de IA ---como Claude Code, OpenCode, Gemini CLI, Codex o Copilot--- utilizan comandos como /init que generan automáticamente este tipo de archivos.

La pregunta entonces es:
¿realmente necesitamos esos archivos?

Cómo funciona realmente el contexto en los agentes de IA

Para entender el problema primero hay que entender qué es el contexto.

Cuando usas una herramienta de IA para programar, el modelo trabaja con una especie de ventana de contexto. Puedes imaginarlo como una serie de espacios donde se va guardando información:

• instrucciones iniciales de la herramienta
• mensajes del usuario
• respuestas de la IA
• fragmentos de código

Cada interacción va llenando ese espacio.

Por ejemplo, en algunas herramientas modernas el contexto puede llegar a 200 000 tokens, pero aun así tiene un límite.

Cuando el contexto se llena, el sistema compacta o resume la conversación anterior para poder continuar trabajando sin perder toda la información previa.

Por eso es importante no añadir información innecesaria que ocupe espacio dentro del contexto.

El problema con claude.md o archivos similares

Cuando ejecutas un comando como:

/init

la herramienta escanea el proyecto y genera automáticamente un archivo de contexto que describe:

• el stack tecnológico
• la estructura del proyecto
• comandos disponibles
• arquitectura
• flujo de la aplicación
• variables de entorno
• despliegue

El problema es que muchas de estas cosas ya existen dentro del propio código.

Por ejemplo:

• los comandos ya están en package.json
• el esquema de base de datos ya está en prisma.schema
• la estructura del proyecto puede obtenerse listando archivos
• la arquitectura cambia con el tiempo

Esto genera varios problemas:

1. Información innecesaria

La IA puede obtener esa información directamente del proyecto.

2. Información desactualizada

Si cambias archivos o carpetas, el archivo de contexto puede quedar incorrecto.

3. Consumo de tokens

Cada vez que interactúas con la IA, ese archivo puede cargarse en el contexto.

En otras palabras: estás gastando contexto en información que la IA podría obtener sola.

Qué deberías hacer en lugar de eso

La solución es mucho más simple de lo que parece:

Mantener claude.md lo más pequeño posible

En lugar de incluir documentación completa del proyecto, utiliza este archivo solo para instrucciones repetitivas y específicas.

Por ejemplo:

Usa kebab-case para nombrar archivos.
No ejecutes build automáticamente después de cada modificación.

Este tipo de instrucciones:

• son pequeñas
• son constantes
• realmente ayudan al agente

Usa una carpeta docs para documentación

Si necesitas explicar cosas como:

• arquitectura del sistema
• flujo de autenticación
• procesos de despliegue
• lógica del negocio

lo mejor es crear una carpeta docs.

Ejemplo:

docs/
  architecture.md
  deployment.md
  guide.md

Estos archivos sirven para documentación del proyecto, pero no se cargan automáticamente en cada interacción con la IA.

Usa Skills para tareas específicas

Si necesitas instrucciones más complejas, la mejor opción es usar skills.

Un skill es básicamente un archivo que describe cómo ejecutar una tarea específica.

Por ejemplo:

skills/build/SKILL.md

Contenido:

Nombre: build

Descripción:
Este skill se usa cuando se construye el proyecto.

Pasos:
1. Ejecutar lint
2. Ejecutar build
3. Si hay errores, corregirlos
4. Volver a ejecutar build
5. Crear commit con mensaje descriptivo

La ventaja es que los skills se cargan solo cuando la IA los necesita, no todo el tiempo.

Esto reduce el consumo de contexto y hace que las instrucciones sean más relevantes.

Ventajas de este enfoque

Este método tiene varias ventajas importantes:

Menos tokens usados

El contexto no se llena con información innecesaria.

Menos contradicciones

La IA obtiene la información directamente del proyecto.

Mayor flexibilidad

Los skills pueden especializar tareas concretas.

Mejor mantenimiento

La documentación del proyecto está separada de las instrucciones para la IA.

La regla simple

Si tuvieras que resumir todo en una sola idea sería esta:

No llenes el contexto con información que la IA puede obtener sola.

En su lugar:

• usa claude.md solo para instrucciones pequeñas
• usa docs para documentación
• usa skills para tareas complejas

Conclusión

Los archivos de contexto como claude.md no son inútiles, pero muchos proyectos los están utilizando de forma incorrecta.

En lugar de crear archivos enormes llenos de información del proyecto, es mejor:

• mantener las instrucciones mínimas
• separar documentación
• usar skills para tareas específicas

Esto no solo mejora la forma en que trabajan los agentes de IA, sino que también reduce el consumo de contexto y evita errores innecesarios.