Cómo alinear las reglas de JetBrains AI Assistant con AGENTS.md para que el chat y los agentes sigan las mismas instrucciones (Guía 2026)

Comencemos con las reglas del proyecto (Project rules). La documentación de JetBrains las describe como una guía para el chat: "De forma predeterminada, las reglas del proyecto se agregan automáticamente a cada sesión de chat, por lo que AI Assistant se adhiere a las pautas proporcionadas". Usted crea una en la configuración, y "Esto crea una carpeta .aiassistant/rules con el archivo .md dentro".

Cada regla tiene un tipo, que decide cuándo se aplica:

• "Always (Siempre): se aplica automáticamente a todas las sesiones de chat".
• "Manually (Manualmente): se aplica solo cuando se invoca explícitamente en el chat usando @rule: o #rule:, o se agrega mediante la acción Agregar archivo adjunto".
• "By model decision (Por decisión del modelo): se aplica cuando el modelo considera que la regla es relevante". Para este tipo, "También debe proporcionar una Instrucción para que AI Assistant pueda comprender cuándo se debe aplicar la regla".
• "By file patterns (Por patrones de archivo): se aplica cuando un archivo al que se hace referencia en el chat coincide con el patrón de archivo especificado (por ejemplo, *.kt o src/**)".
• "Off (Desactivado): la regla está inactiva y no se aplica".

Cada una de esas descripciones menciona el chat. Eso es deliberado. La página de JetBrains sobre instrucciones para agentes traza la línea de manera explícita: "Las reglas del proyecto se configuran en el IDE y se aplican solo en el modo de chat de AI Assistant".

En su lugar, los agentes utilizan archivos de instrucciones. "Los agentes se pueden configurar utilizando archivos de instrucciones en su proyecto que definen cómo deben comportarse en su base de código, incluidas las convenciones de codificación, las restricciones arquitectónicas y los flujos de trabajo comunes". Y qué archivo depende del agente: "La mayoría de los agentes dependen de un archivo AGENTS.md para obtener una guía reutilizable, aunque algunos utilizan su propio formato. Por ejemplo, Claude Agent obtiene sus instrucciones de CLAUDE.md".

Las páginas de los agentes lo confirman. "Junie lee las instrucciones del archivo AGENTS.md en el directorio raíz del proyecto, por lo que puede mantenerlas bajo control de versiones y reutilizarlas en todo el proyecto". Y para el otro agente: "Claude Agent lee las instrucciones del archivo CLAUDE.md en el directorio raíz del proyecto".

JetBrains incluso establece la división del trabajo prevista: "Utilice archivos de instrucciones para compartir pautas entre herramientas y entornos, y reglas de proyecto para personalizar el comportamiento dentro de AI Assistant". La diferencia en el alcance también importa. Los archivos de instrucciones "son utilizados por el agente de codificación seleccionado y viajan con su repositorio", mientras que las reglas del proyecto, en palabras de JetBrains, se "configuran en el IDE".

En resumen, un proyecto puede tener tres fuentes de instrucciones, y cuál se aplica depende de un menú desplegable.

La CLI independiente de Junie añade un detalle más: tiene su propio orden de descubrimiento para las pautas, que comprueba .junie/AGENTS.md antes del archivo raíz. Esa ruta se cubre en colocar las pautas de Junie sin cortar la carpeta de reglas. Esta guía trata sobre el modo de chat de AI Assistant y los agentes dentro del IDE.

Escribir todo como reglas del proyecto (Project rules). La interfaz de usuario de las reglas está ahí mismo en la configuración, con tipos y patrones de archivo, por lo que parece el lugar principal para las instrucciones. Es el lugar principal para el chat. Los agentes siguen archivos de instrucciones.

Escribir todo en AGENTS.md. Es mejor para compartir entre herramientas, y Junie lo lee. Pero el modo de chat aplica las reglas del proyecto, y Claude Agent lee CLAUDE.md.

Mantener un CLAUDE.md de una configuración anterior de Claude Code y asumir que Junie lo detectará. La página de Junie nombra AGENTS.md. Si su equipo se está moviendo entre los dos formatos, migrar CLAUDE.md a AGENTS.md cubre a qué debe prestar atención.

Establecer cada regla en Always (Siempre). Las reglas Always se aplican "automáticamente a todas las sesiones de chat", lo cual está bien para una lista corta pero resulta costoso para una larga. Otras herramientas con modos de activación se enfrentan al mismo dilema, como muestra elegir un modo de activación para cada regla de Windsurf.

Asumir que el agente vio sus reglas porque el chat lo hizo. Diferentes modos, diferentes fuentes. La única comprobación fiable es mirar.

El objetivo es tener un único conjunto de convenciones de equipo que sigan todos los modos, con ajustes exclusivos para el chat donde realmente correspondan.

Paso 1: Mapear lo que lee cada modo en su proyecto hoy

Abra el proyecto y enumere tres cosas.

La carpeta de reglas: cada archivo en .aiassistant/rules, con su tipo. Observe cuáles son Always, cuáles dependen de patrones de archivo, cuáles son manuales o decididos por el modelo, y cuáles están en Off.

El archivo AGENTS.md raíz: si existe y qué cubre. La página de instrucciones para agentes de JetBrains sugiere que un archivo típico incluye el contexto del proyecto, reglas de desarrollo, convenciones del repositorio, tareas comunes, restricciones y una definición de terminado (definition of done).

El archivo CLAUDE.md raíz: si existe y si dice lo mismo que AGENTS.md o si ha divergido.

Luego compare. Cualquier cosa que aparezca en un solo lugar es una instrucción que algunos modos podrían no recibir. Cualquier cosa que aparezca en dos lugares con una redacción diferente es un conflicto latente.

Paso 2: Colocar las convenciones del equipo en AGENTS.md, replicarlas para Claude Agent y mantener las pautas exclusivas de chat en las reglas

Mueva las convenciones que todos los modos deben seguir al archivo AGENTS.md raíz: comandos de compilación y prueba, límites de arquitectura, reglas de nomenclatura, qué no tocar y qué significa "terminado". Este es el archivo que JetBrains recomienda "para compartir pautas entre herramientas y entornos", y viaja con el repositorio, por lo que los compañeros de equipo y otros agentes también lo reciben.

Si alguien en el equipo usa Claude Agent, dele a CLAUDE.md las mismas convenciones. Elija un archivo como la fuente de verdad y haga que la actualización del otro sea parte del mismo cambio. Una breve nota en la parte superior de cada archivo que indique cuál es el canónico evitará mucha confusión más adelante.

Luego, reduzca la carpeta de reglas a lo que sea genuinamente específico del chat: cómo deben formatearse las respuestas, qué explicaciones priorizar, recordatorios que solo tienen sentido en una conversación. Para cada regla restante, elija el tipo deliberadamente. Use Always para las pocas reglas que se aplican a cada chat. Use patrones de archivo para pautas específicas de un idioma o carpeta, como una regla con alcance para *.kt. Use la decisión del modelo para reglas más amplias, con una instrucción clara que describa cuándo se aplican.

Si una regla duplica algo que ahora está en AGENTS.md, elimine el duplicado de la carpeta de reglas o redúzcalo a una referencia. Dos copias de la misma convención terminarán por contradecirse.

Paso 3: Verificar en cada modo, no solo en uno

El modo de chat tiene una comprobación integrada. JetBrains explica: "Para comprobar si se aplicaron las reglas, expanda la lista de archivos adjuntos al principio de la respuesta de AI Assistant". Haga una pregunta que deba activar una regla específica y luego observe.

Para los agentes, pregunte directamente. Inicie una tarea corta con Junie y pídale que enumere las convenciones del proyecto que está siguiendo antes de comenzar. Haga lo mismo con Claude Agent. Si alguno de los dos pasa por alto una convención, significa que el archivo que lee no la contiene.

Finalmente, ejecute la misma solicitud pequeña en Chat, Junie y Claude Agent y compare. Las respuestas diferirán en estilo, ya que el modo de chat "proporciona respuestas y sugerencias pero no aplica cambios a su proyecto automáticamente", mientras que los agentes "pueden realizar acciones de varios pasos en su proyecto, modificar múltiples archivos e informar sobre el progreso durante la ejecución". Pero las convenciones que siguen deben coincidir.

Mientras esté allí, verifique .aiignore. JetBrains señala que "Junie respeta el archivo .aiignore existente, por lo que si tiene uno configurado en su proyecto, no procesará ningún archivo o directorio enumerado allí a menos que le permita explícitamente hacerlo". Asegúrese de que excluya lo que debe y nada de lo que un agente necesite.

Alinear los tres archivos cubre las convenciones que pertenecen a un solo repositorio. Cierto contexto es más amplio que eso: decisiones que abarcan varios proyectos, las razones detrás de una convención, lecciones que un equipo aprendió de la manera difícil y el mismo trasfondo necesario en herramientas fuera de JetBrains. MemoryLake es un lugar para mantener esa capa de modo que cada asistente que use su equipo comience desde allí.

Usted mismo escribe las entradas, con sus propias palabras. No se lee nada, ni se escribe, ni se elimina de su carpeta .aiassistant/rules, de sus archivos de instrucciones o del almacenamiento de ningún proveedor.

Paso 1: Crear una clave de API

Inicie sesión y genere una clave desde el panel de control. La clave es lo que permite a un agente leer las entradas que ha escrito, independientemente del IDE o modo en el que se ejecute.

Paso 2: Subir sus primeros recuerdos

Comience con lo que el Paso 1 reveló que ningún archivo de repositorio único debería contener: decisiones entre proyectos y las razones detrás de sus convenciones. Una decisión por entrada, con la razón adjunta.

Paso 3: Conectar su IA y agentes

Conecte los asistentes y agentes de codificación que utiliza su equipo. El mismo trasfondo estará disponible junto con AGENTS.md, incluso en herramientas que no leen ni este archivo ni su carpeta de reglas.

La primera diferencia es que cambiar de modo deja de alterar las reglas. Una vez que las convenciones residen en AGENTS.md y CLAUDE.md y la carpeta de reglas contiene solo pautas específicas del chat, pasar de Chat a Junie o a Claude Agent mantiene vigentes los mismos estándares.

La segunda es que el repositorio se convierte en la fuente de verdad. Los archivos de instrucciones viajan con el código, por lo que un nuevo compañero de equipo, otro IDE u otro agente adoptan las mismas convenciones. Es el mismo principio detrás de Claude Code leyendo AGENTS.md cuando no hay CLAUDE.md: los archivos compartidos superan a las configuraciones específicas de la herramienta.

La tercera es que el problema de "el agente ignoró nuestras reglas" se vuelve diagnosticable. Con un mapa de qué modo lee qué archivo, puede saber si faltaba una instrucción, si estaba desactualizada o si simplemente nunca se cargó. La versión más amplia de este problema se trata en por qué los agentes de IA ignoran los archivos de instrucciones que usted escribió.

La cuarta es que hay menos conflictos silenciosos. Dos copias de una convención en dos archivos diferentes terminarán por divergir. Un archivo canónico, con el otro replicándolo, mantiene visible cualquier discrepancia.

Trate las reglas del proyecto (Project rules) como configuraciones de chat. JetBrains afirma que "se aplican solo en el modo de chat de AI Assistant".

Mantenga las convenciones del equipo en el archivo AGENTS.md raíz. Junie lo lee y viaja con el repositorio.

Replique las convenciones en CLAUDE.md si alguien usa Claude Agent. Claude Agent lee CLAUDE.md desde la raíz del proyecto.

Defina un archivo como canónico. Actualice la réplica en el mismo cambio.

Elija los tipos de reglas deliberadamente. Mantenga pocas reglas Always; use patrones de archivo y decisión del modelo para el resto.

Verifique la lista de archivos adjuntos en el chat. Muestra qué reglas se aplicaron a una respuesta.

Pida a los agentes que indiquen sus convenciones. Es la forma más rápida de confirmar lo que un agente realmente leyó. Otras herramientas ofrecen comprobaciones similares, como al saber qué pautas de Tabnine están vigentes, y la misma disciplina evita que Cursor olvide las reglas del proyecto.

JetBrains AI Assistant es claro sobre de dónde obtiene sus instrucciones cada modo. El modo Chat aplica las reglas del proyecto desde .aiassistant/rules. Junie lee el archivo AGENTS.md raíz. Claude Agent lee el archivo CLAUDE.md raíz. La documentación incluso indica cómo dividir el trabajo: archivos de instrucciones "para compartir pautas entre herramientas y entornos", y reglas de proyecto "para personalizar el comportamiento dentro de AI Assistant".

El riesgo es que las tres fuentes diverjan detrás de un único menú desplegable. Mapee lo que lee cada modo, coloque las convenciones del equipo en AGENTS.md y replíquelas para Claude Agent, mantenga las pautas específicas del chat en las reglas con tipos deliberados y verifique en cada modo.

Mantenga el contexto que sea más amplio que un solo repositorio en una capa a la que cada herramienta pueda acceder, y cambiar entre el chat y los agentes dejará de significar cambiar entre diferentes conjuntos de reglas.