Recientemente vi una discusión sobre archivos de memoria global para codificación de IA: después de que los proyectos agregan archivos como Claude.md o AGENTS.md, los resultados no necesariamente mejoran. En algunos casos, las tasas de éxito pueden incluso disminuir mientras que el costo del razonamiento aumenta.

Al principio, esto parece contradictorio. Generalmente asumimos que si le damos a la IA más antecedentes del proyecto, más reglas y más explicaciones, debería escribir el código con mayor precisión.
El verdadero problema es que Claude.md no es un documento ordinario. Es un archivo de memoria global que se inyecta en el contexto de cada conversación. Cuanto más contiene, más tiene que leer el modelo cada vez; cuanto más vago sea, más juicio tendrá que hacer el modelo; y si contiene flujos de trabajo que no siempre deberían ejecutarse, el modelo puede desencadenar acciones innecesarias en tareas no relacionadas.

Entonces, la parte difícil de escribir Claude.md es no completarlo. Se trata de decidir qué piezas de información merecen ocupar contexto de forma permanente.

¿Qué es Claude.md?

En las herramientas de codificación de IA, archivos como Claude.md y AGENTS.md son esencialmente archivos de memoria global.

La conversación normal entra en el contexto, pero la longitud del contexto es limitada. Una vez que la conversación se vuelve larga, el contenido histórico se comprime y se pierden algunos detalles. Un archivo de memoria global fija reglas importantes para que el modelo pueda verlas al comienzo de cada tarea.

Esto significa dos cosas:

• El contenido escrito allí es más difícil de olvidar.
• El contenido escrito allí también cuesta algo en cada tarea.

No es como un README que se lee sólo cuando es necesario. Se parece más a un conjunto de limitaciones laborales de larga duración. Una vez que algo se coloca allí, afecta el juicio del modelo por defecto.

Por lo tanto, Claude.md no es una introducción al proyecto, ni una colección de consejos, ni un lugar para deshacerse de cada proceso de desarrollo. Sólo debe almacenar reglas que el modelo probablemente viole repetidamente si no las conoce.

Por qué puede empeorar las cosas

Un archivo de memoria global mal escrito suele provocar tres tipos de problemas.

Primero, consume contexto.

Si Claude.md tiene mil líneas, esas líneas permanecen en el contexto del modelo durante mucho tiempo. Es posible que se reduzcan el código, los mensajes de error y los requisitos que realmente son relevantes para la tarea actual. El contexto no es espacio libre. Cuanto más grande sea el archivo de reglas globales, más fácil será diluir la tarea actual.

En segundo lugar, puede desencadenar comportamientos innecesarios.

Por ejemplo, un archivo global podría decir:

1
2

Before every task, fully read the project directory.
After every change, run a complete end-to-end test.

Estas líneas parecen responsables, pero en un archivo de memoria global se convierten en “hacer esto para cada tarea”. Incluso si la tarea consiste solo en cambiar una línea de copia, el modelo puede realizar exploraciones y pruebas innecesarias debido a estas reglas. El resultado es un trabajo más lento, un costo más alto y, a veces, más interferencia.

En tercer lugar, aumenta la carga del juicio.

Declaraciones como “mantener el código elegante, conciso, mantenible y extensible” suenan correctas, pero son restricciones débiles. Cada vez que el modelo genera código, tiene que decidir qué significa elegante o extensible, sin recibir un límite claro.

Un mejor enfoque es escribir prohibiciones o contraejemplos concretos en lugar de virtudes abstractas. Por ejemplo:

1
2
3

Do not add a generic abstraction for a single call site.
Do not change shared parsing logic without test coverage.
Do not put temporary scripts in the application source directory.

Estas reglas son más específicas y más fáciles de seguir.

¿Qué debería entrar?

Puedes usar un estándar simple para decidir si algo pertenece a Claude.md:

Si la IA comete repetidamente el mismo error sin ella, entonces vale la pena anotarlo.

El contenido adecuado para un archivo de memoria global suele tener estas características:

• Es duradero
• Está fuertemente ligado al repositorio actual.
• No se puede inferir naturalmente de la estructura del código.
• Cambia claramente el comportamiento del modelo.
• Es preferiblemente una restricción, prohibición, regla de ruta o comando fijo.

Por ejemplo:

1
2
3
4

For all Hugo posts, only edit index.zh-cn.md and do not automatically generate other language versions.
Article front matter must include title/date/draft/tags/categories/slug/description.
Do not modify generated artifacts under public/.
On PowerShell, use scripts/deploy.ps1 for deployment.

Estas no son sugerencias vagas. Están vinculados a cómo funciona realmente el repositorio. Si el modelo no los conoce puede cometer errores; una vez que los conoce, puede evitar verdaderos errores.

¿Qué debería quedar fuera?

Mucha gente convierte Claude.md en un manual de proyecto. Esto suele ser innecesario.

El contenido que generalmente no pertenece allí incluye:

• Visión y antecedentes del proyecto.
• Descripciones de estructuras de directorios grandes.
• Planes de tareas temporales
• Pasos únicos de depuración
• Lemas de calidad de código abstracto.
• Flujos de trabajo largos que solo son necesarios en algunas situaciones.

Por ejemplo, una descripción como “este es un proyecto de comercio electrónico con módulos de producto, pedido y usuario” ayuda muy poco con una tarea de codificación concreta. Durante el desarrollo real, el modelo debe depender de los requisitos, especificaciones, estructura del código y pruebas actuales, no de una introducción aproximada del proyecto en la memoria global.

Lo mismo se aplica a la estructura de directorios. A menos que un directorio tenga una convención especial, como “los componentes compartidos deben importarse desde este directorio”, no es necesario escribir el árbol completo en el archivo. El modelo puede leer el directorio del proyecto. Es fácil que una descripción de directorio estática quede obsoleta.

Los flujos de trabajo pertenecen a habilidades o comandos

Si una sección dice “primero haz esto, luego aquello y luego haz la tercera cosa”, es posible que no pertenezca a Claude.md.

Los flujos de trabajo de larga duración se pueden convertir en habilidades, scripts o comandos. El beneficio es que la memoria global solo necesita conservar el nombre y la condición de activación, mientras que los pasos detallados se cargan solo cuando es necesario.

Por ejemplo:

1
2

When the user asks to translate a Hugo post, use the post-translate skill.
When the user asks to deploy the site, run the hugo-rsync-deploy workflow.

Esto es más liviano que poner los procesos completos de traducción e implementación en Claude.md. La memoria global sigue siendo corta y los flujos de trabajo detallados se encuentran en herramientas activables.

El nuevo flujo de inicialización de Claude también avanza en esta dirección. No solo genera un Claude.md; también intenta dividir los flujos de trabajo reutilizables en habilidades y los eventos fijos en ganchos. La idea subyacente es clara: la memoria global debería ser un punto de entrada, mientras que los detalles deberían cargarse según demanda.

Claude.md necesita iteración

Claude.md no debe escribirse una vez y luego ignorarse.

Un mejor enfoque es ser breve al principio y dejar que las tareas reales expongan los problemas. Si ocurre un error una vez, manéjelo manualmente. Si el mismo tipo de error aparece dos o más veces, puede merecer convertirse en una regla global.

Este tipo de iteración es más útil que escribir un enorme conjunto de reglas al principio. Al principio, no sabes qué reglas son realmente útiles o qué líneas se convertirán en ruido. A medida que el proyecto crece, la colaboración aumenta y el comportamiento del modelo se vuelve más claro, puede agregar gradualmente problemas de alta frecuencia.

También hay una tendencia importante: cuanto más fuerte sea el modelo, más corto debería ser el archivo de memoria global. Muchos requisitos que alguna vez tuvieron que escribirse en indicaciones ahora son manejados naturalmente por el modelo. Continuar poniendo esos requisitos básicos en Claude.md solo aumenta la carga de contexto. La memoria global debería reducirse a medida que mejora la capacidad del modelo, manteniendo solo lo que es exclusivo de este repositorio y no se puede inferir automáticamente.

Una forma más práctica de escribirlo

Al escribir Claude.md, piense en este orden:

1. ¿Qué convenciones especiales tiene este repositorio?
2. ¿Qué errores ha cometido el modelo más de una vez?
3. ¿Qué directorios, archivos o comandos nunca deben usarse indebidamente?
4. ¿Qué flujos de trabajo deberían convertirse en habilidades, guiones o comandos en lugar de un contexto permanente?
5. ¿Qué partes son meras introducciones y pueden eliminarse?

El archivo final puede tener sólo unas pocas docenas de líneas. No es necesario explicar completamente el proyecto. Necesita limitar el comportamiento con precisión.

Un buen Claude.md podría verse así:

1
2
3
4
5
6
7

# Working Rules

- Only edit files related to the current task.
- Do not modify generated artifact directories such as public/ or resources/.
- Hugo post rewrites only process index.zh-cn.md and do not generate other language versions.
- If deployment is involved, run the Hugo build first, then execute the existing rsync script.
- When there are existing user changes, do not revert them. Continue from the current state.

Es breve, pero cada línea afecta el comportamiento real. Ese es el tipo de contenido que vale la pena mantener en contexto permanentemente.

Pensamiento final

El valor de Claude.md no es hacer que la IA “sepa más”. Se trata de hacer que la IA “evite errores corregidos”.

No es una base de conocimientos ni una enciclopedia de proyectos. Es un archivo de restricciones de larga duración para la codificación AI.
Cuanto más específico, breve y cercano a los errores reales sea, más útil será. Cuanto más genérica, más larga y más parecida a una introducción de proyecto sea, más probable será que ralentice el modelo o incluso empeore los resultados.

Trate la memoria global como un recurso escaso, no como un bloc de notas ilimitado. Ese puede ser el principio más importante para escribir un buen Claude.md.