Cómo fijar tu archivo de convenciones en cada sesión de Aider (Guía 2026)

La documentación de convenciones de Aider describe el mecanismo claramente. Escribes un pequeño archivo markdown y luego:

"Lo mejor es cargar el archivo de convenciones con /read CONVENTIONS.md o aider --read CONVENTIONS.md. De esta manera se marca como de solo lectura y se almacena en caché si el almacenamiento en caché de prompts está habilitado."

Dos propiedades se concentran en esa frase, y ambas son deliberadas. Marcar el archivo como de solo lectura significa que el agente no intentará editarlo; un archivo de convenciones es una entrada, no un producto de trabajo. Almacenarlo en caché significa que no se vuelven a pagar los tokens en cada turno cuando el almacenamiento en caché de prompts está disponible.

El truco está en el verbo. Tú lo cargas. El mecanismo documentado de Aider para las convenciones es un archivo que lees explícitamente, no un nombre de archivo que busca. No hay un paso de descubrimiento de CONVENTIONS.md que se active solo porque el archivo exista.

Vale la pena precisar esto, porque es fácil malinterpretarlo, y es un fallo diferente de aquel en el que una herramienta sí descubre tu archivo y luego lo ignora. Por qué los agentes ignoran tus archivos de instrucciones cubre ese caso; este es más simple, porque no se cargó nada para ignorar.

Aider no es indiferente a tu base de código. Construye y envía automáticamente un mapa del repositorio con cada solicitud:

"Aider utiliza un mapa conciso de todo tu repositorio git que incluye las clases y funciones más importantes junto con sus tipos y firmas de llamada."

"Aider envía un mapa del repositorio al LLM junto con cada solicitud de cambio del usuario."

Así que el modelo llega con una imagen real de la estructura de tu código. Con lo que no llega es con tus convenciones, y la razón es estructural más que un descuido. El mapa del repositorio se deriva del código. Puede mostrar que existe un módulo y cuáles son sus firmas de llamada. No puede mostrar que rechazaste una biblioteca alternativa hace ocho meses, porque la biblioteca rechazada no está en el repositorio para ser mapeada. Esa distinción es la razón de ser de un archivo de convenciones.

La documentación incluye un ejemplo comparativo que hace que el efecto sea concreto: con el archivo de convenciones leído, la función generada utilizó el cliente HTTP preferido e incluyó anotaciones de tipo. Sin él, la misma solicitud produjo código que utilizaba la otra biblioteca y sin tipos, descrito en la documentación como "quizás más típico en pequeños scripts de Python". Mismo modelo, mismo prompt, resultado diferente, todo debido a un solo archivo.

Escribir /read CONVENTIONS.md al inicio de cada sesión. Esto funciona y es el primer paso correcto. También es un hábito, y los hábitos fallan los días que tienes prisa, que son exactamente los días en que se viola una convención y se fusiona.

Pegar las convenciones en el prompt. Funciona para un turno. No es de solo lectura, por lo que el agente puede editar el archivo; no se almacena en caché, por lo que pagas por él repetidamente; y la próxima semana será un pegado diferente.

Agregar el archivo de convenciones con /add en lugar de /read. Sutilmente peor de lo que parece. /add coloca un archivo en el chat como un archivo editable. El consejo de la documentación es específico sobre la ruta de solo lectura, y hay un consejo relacionado que vale la pena interiorizar: no hagas /drop de los archivos de solo lectura agregados al inicio. Un archivo de convenciones que el agente puede editar es un archivo de convenciones que eventualmente será editado.

Escribir las convenciones en un bloque de comentarios en la parte superior del archivo fuente principal. Ahora la regla vive dentro del código que gobierna, solo viaja con ese archivo, y el mapa del repositorio incluirá alegremente el comentario mientras tus otros doce módulos nunca lo verán.

Poner todo en el archivo de convenciones. El fallo opuesto, y el más común después de unos meses. Un archivo de convenciones que ha crecido para albergar cada decisión arquitectónica, cada postmortem de incidentes y cada opción rechazada se carga por completo en cada sesión. Es de solo lectura y se almacena en caché, por lo que el costo es manejable, pero ahora estás gastando un bloque grande y fijo de contexto en material que se aplica a una pequeña fracción de tus solicitudes.

Tres pasos. El primero es el cambio de dos líneas; los otros dos son los que evitarán que tengas que hacer esto de nuevo.

Paso 1: Coloca read en el archivo de configuración del proyecto

Aider documenta una forma de hacer esto automático:

"También puedes configurar aider para que siempre cargue tu archivo de convenciones en el archivo de configuración .aider.conf.yml"

El campo es read y acepta un solo nombre de archivo o una lista de ellos. Una entrada para un solo archivo de convenciones; una lista cuando tienes un archivo de convenciones más, por ejemplo, una referencia de esquema que siempre quieres que esté disponible.

Dónde coloques el archivo de configuración importa, porque Aider busca en tres ubicaciones:

"Aider buscará este archivo en estas ubicaciones: Tu directorio de inicio. La raíz de tu repositorio git. El directorio actual. Si los archivos anteriores existen, se cargarán en ese orden. Los archivos cargados al final tendrán prioridad."

Coloca la entrada read en la configuración en la raíz de tu repositorio git, no en tu directorio de inicio. Dos razones. Primero, es la única ubicación que viaja con el proyecto, por lo que los compañeros de equipo y la CI obtienen el mismo comportamiento sin que nadie tenga que configurar nada. Segundo, una entrada read en la configuración de tu directorio de inicio apunta a un nombre de archivo que podría no existir en cada repositorio que abras; una configuración global que hace referencia a un archivo local del proyecto es una trampa que espera al próximo repositorio que clones.

Debido a que los archivos cargados al final tienen prioridad, una configuración en la raíz del repositorio también anula limpiamente lo que hayas configurado globalmente, que suele ser lo que deseas.

Paso 2: Decide qué pertenece al archivo y saca el resto

Ahora que el archivo se carga incondicionalmente en cada sesión, su tamaño es un costo permanente. Eso cambia lo que debería contener.

Conserva las cosas que son verdaderas en cada solicitud y lo suficientemente cortas como para expresarse como una regla: las bibliotecas a preferir, la expectativa de anotaciones de tipo, la convención de nomenclatura, el comando de prueba. Estos son mandatos, y un archivo de convenciones es un buen contenedor para mandatos.

Saca todo lo que sea historia. El párrafo que explica el incidente que llevó a la elección de la biblioteca es valioso —es la razón por la que la regla sobrevive a la revisión—, pero no necesita estar en el prompt en cada turno. Lo mismo ocurre con la explicación larga del modelo de datos, la lista de verificación de lanzamiento y las notas sobre por qué tres módulos están estructurados de manera extraña.

La prueba es simple: si una frase responde a "qué debo hacer", pertenece al archivo de convenciones. Si responde a "por qué", pertenece a algún lugar donde el agente pueda buscarlo cuando se le solicite. Lo que realmente leen los agentes de programación es una verificación útil aquí, porque la misma división se aplica a cada herramienta con un archivo de instrucciones que siempre se carga.

El propio consejo de Aider para el archivo, proveniente de las convenciones de la comunidad a las que apunta la documentación, tiene el mismo espíritu: declaraciones cortas y específicas sobre preferencias.

Paso 3: Dale al "por qué" un hogar que el agente pueda consultar

Este es el paso que evita que el archivo de convenciones vuelva a crecer. Una regla sin una razón registrada es una regla que nadie eliminará y nadie defenderá, por lo que el archivo solo se hace más largo.

El razonamiento debe ser recuperable en lugar de estar siempre cargado, y debe sobrevivir a la siguiente herramienta. Aider es una herramienta nativa de terminal con un mecanismo distintivo, y muchos equipos la ejecutan junto con un asistente de IDE. Si el razonamiento vive en un CONVENTIONS.md que solo Aider lee, la otra mitad de tu cadena de herramientas nunca lo verá, y tú tampoco el próximo año cuando estés usando otra cosa. Convertir la documentación del proyecto en memoria de IA cubre cómo dar esa forma al material escrito existente sin tener que reescribirlo desde cero.

MemoryLake guarda el razonamiento detrás de tus convenciones fuera de cualquier herramienta individual y lo sirve a cualquier agente que lo solicite, a través de MCP o la API. Tu CONVENTIONS.md se queda exactamente donde está, y Aider continúa cargándolo de la manera que describe su propia documentación; la capa compartida contiene solo lo que de otro modo inflaría ese archivo.

Paso 1: Crea una clave de API

Genera una clave y realiza tu primera solicitud en unos treinta segundos. Haz esto antes del Paso 2 anterior, para que tengas un lugar donde poner cada razón a medida que recortas el archivo.

Paso 2: Sube tus primeras memorias

Revisa el archivo de convenciones línea por línea. Para cada regla, escribe por qué existe: la alternativa que rechazaste, el incidente detrás de ella, la restricción que la obligó. Esos párrafos salen del archivo de convenciones y van aquí. Los documentos y archivos de soporte van al mismo lugar.

Paso 3: Conecta tu IA y agentes

Dale acceso a Claude, Codex, OpenClaw y tus otros agentes a través de MCP o la API. Cuando alguien pregunte por qué la convención es la que es, la respuesta llegará con su razón adjunta en lugar de como una simple reiteración de la regla.

El primer cambio es que el fallo del lunes por la mañana se detiene. El archivo de convenciones se carga antes de tu primer mensaje, en cada sesión, en cada máquina que tiene el repositorio, sin que nadie tenga que recordar nada.

El segundo es que el estado de solo lectura y el almacenamiento en caché se convierten en valores predeterminados en lugar de algo que tienes que escribir correctamente. Ambas propiedades provienen de la ruta read documentada, y ambas importan más una vez que el archivo se carga cada vez.

El tercer cambio es que el archivo de convenciones puede hacerse más pequeño en lugar de más grande. Cada regla cuyo fundamento se trasladó a un almacén consultable es una regla que se puede expresar en una sola línea. Un archivo corto que siempre se carga más un almacén de razones consultable es estrictamente mejor que un archivo largo que siempre se carga, y representa la misma información total.

El cuarto aparece cuando alguien del equipo no está usando Aider. Las reglas permanecen en el repositorio donde Aider las lee. El razonamiento está en un lugar al que cada agente puede acceder. Ninguna de las dos partes queda atrapada en el formato de una sola herramienta.

Usa read, no add. El estado de solo lectura es la postura correcta para un archivo de entrada, y es lo que recomienda la documentación. También significa que el agente no reescribirá silenciosamente tus reglas.

Coloca la configuración en la raíz de git. Viaja con el proyecto y tiene prioridad sobre la configuración de tu directorio de inicio, ya que los archivos cargados al final ganan.

Usa una lista cuando tengas más de una entrada que siempre deba estar activa. El campo read acepta una lista, por lo que un archivo de convenciones más una referencia de esquema es una entrada para cada uno en lugar de un megaarchivo fusionado.

No hagas /drop de los archivos de solo lectura agregados al inicio. Los consejos de Aider señalan esto directamente, y es un accidente fácil durante una sesión larga cuando estás limpiando archivos del chat.

Mantén los mandatos en el archivo y las razones fuera de él. El archivo se carga en cada solicitud. Cualquier cosa que responda "por qué" se está pagando en turnos donde nadie preguntó.

No esperes que el mapa del repositorio lleve tus convenciones. Se construye a partir de tu código y se envía con cada solicitud, lo cual es genuinamente útil, y solo puede reflejar lo que contiene el repositorio. Una biblioteca rechazada no deja rastro para mapear.

Sube el archivo de convenciones a git. Obvio, y aún así vale la pena decirlo: un archivo de convenciones que vive solo en una computadora portátil es una preferencia personal vestida con la ropa de un equipo.

Espera tener que hacer esto de nuevo en cada otra herramienta que uses. El mecanismo difiere: hacer que un agente se adhiera a tu estilo de programación cubre la versión de otra herramienta para el mismo trabajo, y soluciones de memoria para agentes de programación autónomos cubre la capa debajo de todos ellos.

El mecanismo de convenciones de Aider es un archivo de solo lectura cargado explícitamente en lugar de un nombre de archivo descubierto por convención, y esa única diferencia es la razón por la que el archivo que funciona en las pruebas deja de funcionar en el uso diario. La solución está documentada y es pequeña: una entrada read en .aider.conf.yml en la raíz de tu repositorio git, lo que hace que el archivo se cargue en cada sesión, como solo lectura y almacenado en caché, para todos los que tengan el repositorio.

La parte que requiere criterio es qué poner en él. Debido a que el archivo ahora se carga incondicionalmente, cada línea es un costo permanente, lo cual es la presión adecuada para limitarlo a mandatos permanentes y mover el razonamiento a algún lugar que un agente pueda consultar bajo demanda. El mapa del repositorio de Aider seguirá diciéndole al modelo lo que contiene tu código. Solo tú puedes decirle lo que tu código deliberadamente no contiene.