Lead / quien arma el MD
- §7 Arquitectura — el mapa del disco, no el del libro.
- §16 Equipo y Git — una fuente en el repo; PR de reglas con el código.
- §17 Adopción — lista corta del día 0.
- Fichas: portable-agents · por herramienta.
Documentación de equipo
Manual para compartir: cómo se inyectan CLAUDE.md, AGENTS.md y archivos propios de cada herramienta en el contexto. No es una guía solo de Cursor. Cubre Claude Code, OpenCode, Copilot, VS Code, Cline, Roo, Aider, Windsurf, Codex, Amazon Q, Gemini CLI, Junie, Zed, Goose y otras. Qué ocurre en cada tipo de chat, cómo anclar arquitectura, qué modelo elegir, y casos reales. Basada en documentación pública (septiembre 2026).
Empezá por un click.
Atajo por rol: lead, React, Java o quién elige el modelo.
Clave 632 plantillas (React, Java, Angular, Android) para el chat de hoy. Abrilo en el editor o en GitHub.
El navegador suele mostrarlo como texto crudo, no como capítulo.Bugs, features y capas dentro de la enciclopedia. Para enviar: las dos tarjetas de abajo.
Claves 4 · 5Rápido vs. pensar, y cómo no gastar contexto en MD duplicado o hilos eternos.
Clave 2Una fuente de verdad en el repo. El PR de reglas viaja con el código.
Clave 8Enlaces oficiales. Si el producto cambia, vale la página del proveedor.
Clave 7Bug, endpoint, monolito, Angular, Android. Tocá poco; no reescribas el módulo.
Clave 7Día 0, tajada vertical, un stack, CI. El mapa va antes que la feature.
Índice: guia-inicio.html. Fichas legacy / nuevo (HTML práctico, no solo este manual): casos-practicos-legacy-y-nuevos.html.
Introducción
Importante — claves 1 y 3. Lista completa: Puntos clave.
Los capítulos 1–19 siguen siendo el manual. Este bloque es el atajo: elegí tu rol, abrí esos anclas, y para el chat de hoy copiá un prompt.
Prompts listos para pegar: docs/casos/prompts-base.md.
Esta guía no reemplaza la documentación oficial de Cursor, Claude Code, OpenCode, Copilot ni de ningún proveedor. Si un detalle de producto choca con lo escrito aquí, prevalece el enlace en Referencias. El foro no es contrato. Los nombres de modelos cambian; la lógica (planear con uno capaz, ejecutar con uno rápido, MD corto) no.
src/.También: tokens (MD corto, no pegar el repo, no duplicar AGENTS.md + .mdc) · catálogo de chats · glosario.
Introducción
Un agente de IA (el asistente que lee y modifica código) arranca cada conversación casi en blanco respecto de este repositorio. Sin instrucciones fijas, cada persona vuelve a explicar la estructura, las convenciones y lo prohibido. En un equipo eso produce arquitectura inconsistente, cambios que se apartan de los patrones y tiempo perdido.
La propuesta: dejar ese conocimiento en el repo, en archivos que la herramienta lee sola. Quedan como documentación viva para la IA y para quien entra al equipo. Complementan —no reemplazan— linters, CI, revisiones de código y controles de seguridad.
Esto es contexto (información que el modelo tiene en cuenta), no un candado. El Markdown no bloquea por sí solo una acción peligrosa. Si algo no debe ocurrir nunca (secretos, producción, datos reales), hace falta otro mecanismo: permisos, hooks o política del equipo. Anthropic lo deja explícito: para bloquear una acción, un hook (por ejemplo PreToolUse), no solo el CLAUDE.md. Ver How Claude remembers your project.
Esta guía resume docs públicas de septiembre 2026. No reemplaza las páginas oficiales: si un detalle de producto choca, vale el enlace en Referencias. El comportamiento exacto depende de la versión de cada herramienta (Claude Code, OpenCode, Copilot, Cline, Cursor, etc.). Ejemplo Cursor/Claude: exclusiones de reglas on-demand antes de v2.1.211, o /init leyendo AGENTS.md solo con un flag. Si algo no coincide: en Claude Code usá /context y /doctor; en Cursor, Customize → Rules. AGENTS.md no es universal: es la convención portable (agents.md); varias herramientas tienen archivo propio. Ver Otras herramientas. La duplicación AGENTS.md + .mdc always-on está reportada en el foro, no como contrato de Rules. Los nombres de modelos son heurística, no garantía.
Archivo de reglas
Un .md (Markdown) es texto plano. CLAUDE.md y AGENTS.md cubren el mismo tipo de instrucciones, pero no las lee la misma herramienta:
CLAUDE.md — lo que lee Claude Code. Anthropic: Claude Code no lee AGENTS.md salvo que lo importes (@AGENTS.md) o haya un symlink. Documentación CLAUDE.md.AGENTS.md — convención portable (agents.md). La leen Codex, OpenCode, Cline, Roo, Junie, Zed, Goose (por defecto), VS Code (setting) y otras; no Claude Code ni Amazon Q ni Continue (archivo propio). Cursor: alternativa simple a .cursor/rules. Tabla: 11.3.Cursor también puede leer CLAUDE.md en la raíz (compatibilidad). En la ayuda de Cursor, CLAUDE.md se aplica a la conversación de forma persistente; si hace falta una regla condicional, usá .cursor/rules con glob. Confirmá el comportamiento en tu versión (ver Alcance y límites). Dentro del archivo no va el código de la aplicación: van instrucciones permanentes (mapa, comandos de build/test, patrones del equipo, prohibiciones).
Consultar: CLAUDE.md (Anthropic) — Claude Code no lee AGENTS.md salvo import · Cursor Rules — AGENTS.md vs .mdc · lista completa.
| Dónde | Qué va | Quién lo ve |
|---|---|---|
Raíz: AGENTS.md / CLAUDE.md |
Lo que vale en todo el repo, en cada chat | Todo el equipo (Git) |
Subcarpeta o regla con paths / glob |
Solo esa zona (API, UI, tests) | Cuando se trabaja esa zona |
CLAUDE.local.md / reglas de usuario |
Gustos de una persona | No se comparte (gitignore / cuenta) |
Cómo funciona el chat
La IA no “escanea el proyecto buscando Markdown”. La herramienta (Cursor o Claude Code) inyecta ciertos archivos en la ventana de contexto de la sesión: la memoria de trabajo de ese chat (instrucciones + archivos leídos + el hilo). Esa ventana es limitada. Cada línea del MD ocupa tokens (unidades de texto que cuestan y desplazan otra información). Anthropic recomienda archivos cortos (~200 líneas) porque más texto reduce el cumplimiento. Fuente: CLAUDE.md.
| Fuente | Herramienta | Cuándo entra |
|---|---|---|
CLAUDE.md o .claude/CLAUDE.md en la raíz (y padres) |
Claude Code; Cursor también puede leerlo | Al inicio de la sesión |
AGENTS.md en la raíz |
Cursor (y otras herramientas compatibles) | Al inicio de la sesión |
CLAUDE.md / AGENTS.md en subcarpetas |
Ambas (con matices) | Bajo demanda: cuando el agente lee archivos de esa carpeta |
.claude/rules/*.md sin paths |
Claude Code | Al inicio, como el CLAUDE.md del proyecto |
.claude/rules/* con paths: |
Claude Code | Cuando trabaja archivos que coinciden |
.cursor/rules/*.mdc |
Cursor | Según tipo: always / glob / agent-requested / manual @regla |
README.md, notas.md, docs sueltas |
— | No, salvo que se pidan o se importen con @ruta |
Claude Code carga CLAUDE.md y CLAUDE.local.md del directorio de trabajo y de los padres. Los concatenan; no se pisan. Lo más cercano al directorio de trabajo se lee al final. Los de subdirectorios no van al arranque: se incluyen cuando Claude lee archivos ahí. Detalle: How CLAUDE.md files load.
Cursor: AGENTS.md en raíz y anidados; .cursor/rules con metadatos. Un .md plano dentro de .cursor/rules se ignora (hace falta .mdc con frontmatter). Fuente: cursor.com/docs/rules.
En Claude Code, los CLAUDE.md de la raíz y de los directorios padres se leen al inicio de la sesión y se entregan como mensaje de usuario (no van “dentro” del system prompt). No se releen del disco en cada turno ni se recortan. Si editás el archivo a mitad de conversación, el cambio entra en la próxima sesión, o en la actual con /compact o abriéndolo en /memory. Fuente: Help Center. /context lista qué archivos de memoria cargó esta sesión. Pedirle al agente que lea el path es un parche: trae el texto al hilo, pero no es la inyección automática.
El modelo puede ignorar una regla vaga o contradictoria. Dos reglas opuestas: puede elegir cualquiera. Un hook sí puede negar una herramienta (por ejemplo, impedir un comando). Seguridad, secretos y producción no se delegan solo al Markdown.
Cursor trata AGENTS.md y .cursor/rules/*.mdc como fuentes distintas (se combinan; no se deduce que un symlink sea “el mismo” archivo). En el foro oficial se reportó que el mismo texto en ambos se inyecta dos veces. No está en la página de Rules como garantía de producto: tratalo como riesgo práctico. Elegí una fuente para lo always-on. Cursor: reglas de proyecto < ~500 líneas; Anthropic: CLAUDE.md < ~200 líneas (un archivo > 4 MiB se omite). Team Rules (planes Team/Enterprise), si existen, se mezclan con las demás; Cursor documenta precedencia Team → Project → User cuando hay conflicto. Práctica del equipo (coste, chat nuevo, capturas): Cuidar los tokens. Rules.
/init, /context, /memory, /compact/init — explora el repo y propone un CLAUDE.md (si ya existe, sugiere mejoras; no lo pisa). Hay que revisar, borrar lo inventado y commitear. Puede tomar partes de .cursor/rules. Con CLAUDE_CODE_NEW_INIT=1 también puede leer AGENTS.md de otros agentes. Docs./context — qué archivos de memoria entraron en esta sesión (lista Memory files). Si no aparece, no se inyectó./memory — ver y editar CLAUDE.md, local y la auto memory (notas que escribe Claude; no es la fuente de verdad del equipo). Pedir “remember” puede anexar una regla al MD. Help: Give Claude context./compact — resume el hilo. El CLAUDE.md de la raíz del proyecto se relee de disco y se reinyecta. Anidados y reglas con paths: vuelven cuando Claude lee archivos que coinciden. Lo que solo se dijo en el chat puede perderse. Instructions seem lost after /compact./clear — chat limpio; el MD del proyecto sigue (Help Center: una tarea por conversación).@regla| Tipo | Cuándo entra | Uso |
|---|---|---|
alwaysApply: true |
Todos los chats | Pocas reglas universales (equivalente práctico al AGENTS.md corto) |
Glob (p. ej. src/api/**/*.java) |
Cuando hay archivos que coinciden en juego | Convenciones de API, no de CSS |
| Agent-requested | El agente decide si es relevante | Temas ocasionales |
Manual @nombre |
Cuando la persona lo menciona | Playbooks que no deben estar siempre |
Consultar: tipos de regla Cursor (always / glob / inteligente / @) · carga de CLAUDE.md y /compact · Referencias.
Prácticas
Anthropic: instrucciones específicas se cumplen mejor. Cada línea debe poder comprobarse en una revisión.
| Vago (malo) | Concreto (bueno) |
|---|---|
| Mantener el código ordenado | Los handlers HTTP viven en src/api/handlers/. No crear src/controllers/ nueva. |
| Seguir buenas prácticas | La regla de negocio no va en el @RestController ni en el componente Angular. Va en dominio o caso de uso. |
| Probar los cambios | Antes de dar por cerrado un cambio de API: ./mvnw test. Un cambio de UI: tests del feature tocado. |
| No romper producción | No ejecutar migraciones destructivas. No apuntar a credenciales de prod. No hacer push sin pedido explícito. |
| Mecanismo | Para qué |
|---|---|
| MD de reglas | Arquitectura, “dónde va X”, prohibiciones de alcance, comandos de proyecto que el agente no adivina |
| Linter / formateador | Espacios, imports, estilo mecánico. No copiar la guía de estilo entera al MD. Cursor Learn lo dice: el linter complementa; no sustituirlo con un tratado. |
| CI | Que el build y los tests pasen en el remoto, aunque el agente se salte algo en local |
| Hooks | Bloquear de verdad (secretos, comandos peligrosos) |
Según Anthropic, agregar una regla cuando: el agente comete el mismo error dos veces; una review muestra algo que debería haber sabido; se está tipeando la misma corrección en cada chat; una persona nueva necesitaría ese dato para ser productiva. No documentar “por si acaso” procedimientos de diez pasos: eso va a un skill o a una regla por ruta. Fuente: When to add to CLAUDE.md.
@AGENTS.md)Claude Code puede importar archivos con @ruta (relativa al archivo que importa). Sirve para un CLAUDE.md de una línea que apunta a AGENTS.md y no duplicar. Los imports se expanden al lanzar la sesión. Para mencionar una ruta sin importarla, va entre backticks. Fuente: Import additional files.
# CLAUDE.md
@AGENTS.md
# Solo Claude Code
- Antes de terminar, correr /context si hay duda de qué reglas cargaron.
Un MD de 800 líneas se cumple peor y empuja código útil fuera del contexto. Extraer: un párrafo de arquitectura en la raíz; detalles de API en regla con paths; el resto en el linter o en un doc que el agente lea cuando se lo pidan. Práctica de coste y contexto: Cuidar los tokens.
Tokens / contexto
Importante — clave 5. Lista: Puntos clave.
Un token es una unidad de texto: se cobra y se descuenta de la ventana de contexto (memoria de trabajo de este chat). El MD, el hilo, los archivos leídos, las capturas y los logs compiten por el mismo espacio. Glosario: Token.
Esto no es un tutorial de facturación. Es cómo el equipo deja sitio para el diff del ticket.
Recortar tokens no es un candado de seguridad. Un MD corto sigue siendo contexto. Secretos, prod y push se cubren con hooks, permisos y CI.
| Hacer | No hacer |
|---|---|
Raíz corta: mapa, quién habla con quién, prohibiciones. Detalle de React o JPA en frontend/AGENTS.md, api/AGENTS.md, glob / paths, o un skill que se carga on-demand. |
400 líneas de Angular en la raíz “para que siempre las vea” en un ticket de SQL. |
| Dejar que el agente lea el archivo del síntoma. En el prompt: path y síntoma. | Pegar el repo, el Jenkinsfile o cinco clases “por si acaso”. Eso no sustituye la herramienta de lectura y llena el hilo. |
Una fuente always-on: AGENTS.md o un .mdc con alwaysApply, no el mismo párrafo en los dos. Claude Code: CLAUDE.md con @AGENTS.md, sin copiar el tratado. Catálogo I. |
Symlink AGENTS.md → .mdc always-on (riesgo de doble inyección en Cursor; foro, no contrato de Rules). |
| Chat nuevo cuando el hilo es enorme, cambió el tema, o se editó el MD. Un ticket por conversación. | Un chat eterno “para no perder contexto”: el contexto ya está sucio; el modelo prioriza el final y olvida el mapa. |
Claude Code: /compact si querés seguir el mismo ticket y releer el MD de raíz. Lo que solo se dijo en el chat puede perderse. Anidados y paths vuelven al tocar esos archivos. Catálogo K. |
Creer que /compact recarga todos los anidados de una vez, o usarlo para no abrir chat nuevo cuando el ticket ya es otro. |
Reglas con glob / paths / anidadas: entran al trabajar esa zona. Always-on: pocas líneas universales. |
Always-on con el estilo de tests, JPA y CSS juntos. Gasta tokens en cada chat y se cumple peor. Tabla: §3.6. |
| Capturas y logs: recortar al síntoma. Una imagen del botón, no el PDF del Figma. Un stack de 30 líneas, no el catalina.out. | Adjuntar 15 screenshots o un dump con PII. La imagen cuesta contexto; el log enorme empuja el MD fuera. |
| Modelo rápido (Composer, Grok, Haiku) para el parche chico: menos tokens de “pensar”. El capaz, en otro chat, para el mapa. | Opus/Fable para un rename o un reset de page. Pensar también se cobra. |
alwaysApply: true, Team Rules enforced): cada sesión. Reservalo al cauce y a “no inventar / no agrandar / no commit”.paths: en Claude): cuando el agente lee o edita archivos que coinciden. El detalle de @RestController no debe viajar a un .tsx.@: playbooks que casi nunca hacen falta. No los copies al MD de raíz.Ventajas de raíz corta + on-demand
.mdc idéntico.Desventajas del MD gordo (y del anidado mal usado)
frontend/ para que entre el anidado (Claude: on-demand).Consultar: Anthropic ~200 líneas, /compact, anidados on-demand · Cursor Rules (tamaño, nested, tipos) · no duplicar AGENTS.md + .mdc · prompts (no pegar el MD).
Cómo funciona el chat
Analogía: nota en la puerta. Quien entra la ve. Quien ya está adentro, no, hasta salir y volver a entrar. El detalle de cada variante está en el catálogo siguiente.
Consultar: qué pasa al abrir la sesión y si editás el MD a mitad · Memory · Referencias.
Cómo funciona el chat
En todos: setup, qué hace la herramienta, qué “ve” el modelo, qué hacer, fallo típico.
Setup
El repo tiene AGENTS.md (o CLAUDE.md) en la raíz, en Git. La persona clona, abre la carpeta, abre Agent / Claude Code, chat nuevo. No pega las reglas.
Qué hace la herramienta
Al iniciar la sesión busca la raíz (y padres). Encuentra el archivo, lo inyecta en el contexto. Aún no hace falta un mensaje.
Qué ve el modelo
El texto del MD + el primer prompt. No ve READMEs ni docs de /docs salvo que los abra después.
Qué hacer
Escribir el ticket. Si hay duda de carga: en Claude Code, /context.
Fallo: abrir el chat con otra carpeta (un solo módulo fuera del repo) y creer que cargó el AGENTS.md de la raíz. La herramienta busca desde el directorio de trabajo.
Ventajas
Desventajas
Setup
No hay AGENTS.md ni CLAUDE.md. Se trabaja un rato. Después alguien crea el archivo en el mismo chat o en el disco.
Qué hace la herramienta
El chat ya abierto no incorpora el archivo nuevo solo. Un chat siguiente sí lo carga al inicio. Claude Code: /init puede generar el primer borrador; hay que revisarlo y commitearlo.
Qué ve el modelo
En el chat viejo: nada del MD, salvo que le pidan “leé AGENTS.md”. En el chat nuevo: el archivo completo de la raíz.
Qué hacer
Crear el MD → commit → chat nuevo (o lectura explícita). No asumir que el hilo anterior ya “aprendió”.
Fallo: seguir el mismo chat “porque ya está el archivo en disco”. Sigue sin la inyección automática.
Ventajas
Desventajas
Setup
En el chat 1 se cambió el MD (por ejemplo: “no crear microservicios”). Se abre el chat 2 sobre el mismo repo.
Qué hace la herramienta
El chat 2 lee el archivo actual en disco al arrancar.
Qué ve el modelo
La versión nueva. El chat 1, si sigue abierto, puede seguir con la versión vieja.
Qué hacer
Cerrar o dejar el chat 1. Trabajar en el 2. Commitear el MD para que el resto del equipo tenga lo mismo.
Fallo: dos personas: una commiteó la regla, la otra tiene un chat de ayer. La segunda no tiene la regla hasta un chat nuevo o un pull + chat nuevo.
Ventajas
Desventajas
Setup
A mitad del chat se agrega “no mezclar UI con negocio”. No se abre chat nuevo.
Qué hace la herramienta
No reinyecta el MD en cada turno. El contexto sigue con la copia inicial.
Qué ve el modelo
Las reglas de cuando empezó el chat, más el hilo. La línea nueva no está, salvo lectura explícita.
Qué hacer
“Leé AGENTS.md otra vez y aplicá la versión actual”, o chat nuevo. Claude Code: /compact o /memory.
Fallo: corregir al modelo de palabra (“te dije que no…”) y no persistir en el MD: el próximo chat volverá a pecar.
Ventajas
Desventajas
Setup
Raíz: mapa general. frontend/AGENTS.md: Angular, sin HTTP en componentes. backend/AGENTS.md o backend/CLAUDE.md: controladores delgados, dominio sin JPA.
Qué hace la herramienta
Al inicio: sobre todo la raíz. Al leer o editar algo bajo frontend/, entra el MD de esa carpeta (Claude: on-demand; Cursor: anidados se combinan, lo específico suele ganar). Fuente Cursor: Nested AGENTS.md.
Qué ve el modelo
Si solo tocó Java en backend/: reglas de backend + raíz, no necesariamente las de Angular, hasta que abra el frontend.
Qué hacer
Poner en la raíz solo lo transversal. El detalle de UI o API, en su carpeta.
Fallo: meter 400 líneas de Angular en la raíz “para que siempre las vea”. Gasta tokens en tickets de backend y se cumple peor.
Ventajas
Desventajas
Setup
Regla Claude con paths: src/api/**/*.java (“validar input, no devolver entidades JPA”). O .mdc Cursor con globs: src/api/**/*.java.
Qué hace la herramienta
La regla condicional no va en todos los chats. Entra cuando el agente trabaja un archivo que coincide (lectura o edición). Un .scss o un HTML no la dispara.
Qué ve el modelo
Con un PedidoController.java: raíz + regla de API. Con styles.css: raíz, sin el párrafo de la API.
Qué hacer
Un archivo de regla por tema. No poner CSS en la regla de API.
Fallo: glob mal escrito (*.java en todo el repo) y la regla de API se cuela en tests o en un CLI.
Ventajas
Desventajas
Setup
El MD cambió, o se sospecha que no cargó. Se escribe: “leé AGENTS.md y aplicá eso”.
Qué hace la herramienta
El agente usa la herramienta de lectura, trae el archivo ahora al contexto de este turno. No es la inyección automática del inicio, pero el contenido queda en el hilo.
Qué ve el modelo
El texto fresco + el resto del chat (incluida la copia vieja, si existía). Si hay contradicción, puede dudar: conviene decir “prevalece el archivo que acabás de leer”.
Qué hacer
Usarlo como parche. Para el día siguiente: chat nuevo.
Fallo: “acordate de las reglas” sin path. Puede alucinar un resumen viejo en lugar de leer el disco.
Ventajas
Desventajas
@AGENTS.md)Setup
El equipo usa las dos herramientas. Hay AGENTS.md canónico. CLAUDE.md solo importa: @AGENTS.md más dos líneas de Claude Code.
Qué hace la herramienta
Cursor inyecta AGENTS.md. Claude Code inyecta CLAUDE.md y, al expandir el import, el mismo AGENTS.md. Un symlink AGENTS.md → un .mdc always-on duplica en Cursor.
Qué ve el modelo
El mismo mapa de arquitectura si no se copió el texto en dos sitios.
Qué hacer
Una fuente. Import o un solo archivo. No copiar + symlink al .mdc.
Fallo: actualizar solo CLAUDE.md y olvidar AGENTS.md (o al revés): cada herramienta “ve” normas distintas.
Ventajas
Desventajas
Setup
Por “por las dudas”, el mismo bloque está en los dos.
Qué hace la herramienta
Cursor inyecta ambas fuentes. Doble de tokens. No mejora el cumplimiento de forma fiable.
Qué ve el modelo
El mismo párrafo dos veces, más cerca del tope de contexto.
Qué hacer
AGENTS.md para lo portable; .mdc solo para globs o reglas que no deban estar siempre.
Fallo: el chat “se olvida” de archivos del ticket porque el contexto se llenó de reglas repetidas.
Ventajas
Desventajas
Setup
Claude Code se lanza en repo/backend/, no en repo/.
Qué hace la herramienta
Carga CLAUDE.md de backend/ y de los padres (incluida la raíz), concatenados. Los hermanos (frontend/CLAUDE.md) no cargan hasta que se lean archivos ahí. Cursor: depende de cuál sea el workspace raíz que se abrió.
Qué ve el modelo
Raíz + backend. No el detalle de Angular, salvo que se añada esa carpeta o se lean esos archivos.
Qué hacer
Abrir el workspace en la raíz del monorepo si el ticket cruza frentes. Anthropic: claudeMdExcludes si un monorepo arrastra MD de otros equipos. Docs.
Fallo: abrir solo frontend/ como proyecto y creer que no existen reglas de API: la raíz puede haber cargado igual (padres), o no, según cómo se abrió el IDE.
Ventajas
Desventajas
/compact o /memory (Claude Code)Setup
Chat largo. Se editó CLAUDE.md. No se quiere perder del todo el hilo.
Qué hace la herramienta
/compact resume el diálogo y relee de disco el CLAUDE.md de la raíz. Anidados y paths vuelven al tocar esos archivos. /memory permite editar y, en la práctica, alinear la sesión con el archivo.
Qué ve el modelo
Resumen del chat + MD actual de la raíz. Detalle fino del hilo puede perderse; las reglas de raíz deberían estar frescas.
Qué hacer
Usarlo cuando el chat es valioso pero el MD cambió. Si el ticket cambió de tema: chat nuevo es más limpio.
Fallo: creer que /compact recarga también todos los MD anidados de una vez. No: esos siguen on-demand.
Ventajas
Desventajas
Setup
El AGENTS.md dice: capas UI → API → dominio → datos; no inventar microservicios; un cambio acotado. Tres chats nuevos, mismo repo, mismo ticket: “agregá un campo al pedido”.
Qué hace la herramienta
Inyecta las mismas reglas. Cambia el modelo que las interpreta.
Qué ve el modelo
El mismo texto. Opus/GPT suelen planear dentro del mapa. Composer/Grok/Auto suelen ejecutar rápido: si el ticket es ambiguo (“mejorá la arquitectura”), un modelo rápido puede crear carpetas nuevas pese al MD.
Qué hacer
Arquitectura y “¿rompemos el patrón?”: Opus o GPT. Bajar un plan ya escrito: Composer, Grok o Sonnet. Auto: rutinario, no rediseño.
Fallo: “el MD no sirve” cuando el problema fue el modelo (o un ticket que pedía rediseñar). El archivo ancla; no obliga.
Ventajas
Desventajas
Arquitectura y patrones
Este capítulo es el ancla del documento. El MD no “inventa” una arquitectura: escribe la que el equipo ya eligió para que el agente no la renegocie en cada chat. Las capas y patrones de abajo son ejemplos frecuentes (consultora Java/Angular/Android), no un estándar obligatorio. Si el repo es un monolito MVC o un Next.js sin “dominio”, el MD debe decir eso, no un libro de texto.
| Término | Qué decide | Ejemplo | ¿Va al MD? |
|---|---|---|---|
| Arquitectura | Partes del sistema y quién puede hablar con quién | UI no accede a la base. El dominio no importa Spring. | Sí, en la raíz, en 10–20 líneas |
| Patrón | Forma repetida de resolver un tipo de problema | MVVM en Android; REST + DTO en la API; caso de uso por acción | Sí, el que el repo ya usa |
| Convención | Dónde vive un archivo y cómo se nombra | *Controller en web/; features Angular en features/pedidos/ |
Sí, si el agente se equivoca de carpeta |
| Guía de estilo | Formato mecánico | 2 espacios, imports, no any |
Casi no: linter / CI |
Esquema frecuente en equipos web y móvil (nombres varían; la flecha no):
UI (Angular / Android)
→ solo habla con Application / API (HTTP, casos de uso)
Application (casos de uso)
→ habla con Domain (reglas) y con puertos (interfaces)
Domain (entidades, reglas)
→ no habla con HTTP, JPA, Angular ni Android
Infrastructure / datos
→ implementa puertos (JPA, REST client, disco)
→ el dominio no la importa
Regla útil para el MD: las dependencias apuntan hacia adentro. La UI y los controladores HTTP dependen del caso de uso. El dominio no depende de frameworks. Si el agente pone un EntityManager en una clase de dominio, rompió el mapa.
| Capa | Puede conocer | No puede conocer |
|---|---|---|
| UI | DTOs, servicios/fachadas, navegación | SQL, entidades JPA, reglas de facturación embebidas en el componente |
| API HTTP | Request/Response, validación de forma, invocar un caso de uso | Consultas SQL, “if negocio” largos |
| Dominio | Reglas, invariantes, IDs, dinero, estados | @Entity, HttpServletRequest, HttpClient |
| Datos | Tablas, mappers, implementaciones de repositorio | Decidir si un pedido se puede cancelar (eso es dominio) |
feature X; no introducir ViewModel ahí sin pedido”..ts de la plantilla.Recursos, verbos HTTP, cuerpos DTO. El agente suele devolver la entidad JPA o inventar URLs. El MD debe fijar: prefijo (/api/v1), “nunca exponer *Entity”, errores con código estable.
El dominio define puertos (interfaces). La infraestructura es el adaptador (JPA, un cliente HTTP). El agente “ayuda” creando un servicio único que habla con el repositorio JPA desde el controlador. La regla: “nuevo acceso a datos = interfaz en dominio/aplicación + implementación en infraestructura. No inyectar JpaRepository en el controlador.”
| Por capas | Por feature | |
|---|---|---|
| Carpetas | controllers/, services/, repos/ |
pedidos/, usuarios/ con sus capas adentro |
| Riesgo del agente | Poner un pedido nuevo en services/ genérico eterno |
Crear un feature paralelo (orders/) cuando ya existe pedidos/ |
| Qué escribir | “Este repo es por capas; no crear features/” |
“Un feature = una carpeta. No crear common-services-2” |
El MD debe elegir uno (el que ya está en el disco). El fallo clásico es que el agente introduzca el otro “porque es más moderno”.
Tres bloques en la raíz suelen bastar:
## Arquitectura (la de *este* repo; no un estándar universal)
Capas: UI → application → domain ← infrastructure.
- Un endpoint nuevo: Controller (web) + UseCase (application) + puerto si hace falta.
- No crear paquetes `modules/`, `hexagon/` ni un microservicio nuevo.
- Domain sin Spring, JPA ni Angular.
- Controllers sin SQL ni reglas de negocio.
- Android: MVVM; el ViewModel no importa Activities/Fragments.
- Angular: el componente no usa HttpClient; pasa por un repositorio/fachada.
Si un pedido requiere romper esto: detenerse y explicarlo. No hacerlo en silencio.
Vago: “respetar clean architecture”. El agente puede interpretar cualquier árbol de carpetas como “clean”.
Raíz AGENTS.md — solo el mapa y Git.
# frontend/AGENTS.md
- Standalone components. Estado local: signals.
- HTTP solo en `*.repository.ts` o `*-api.ts`.
- No agregar NgRx salvo pedido explícito.
# backend/AGENTS.md
- Controllers delgados: mapear request → input, llamar use case, mapear output.
- Tests de dominio sin Spring.
- Persistencia: solo `infrastructure/persistence`.
---
paths:
- "src/test/**/*.java"
---
# Tests
- Un test verifica comportamiento, no la implementación línea a línea.
- No mockear el dominio para “afirmar que se llamó al mock”.
---
description: API HTTP Java
globs: src/main/java/**/web/**/*.java
alwaysApply: false
---
No devolver entidades JPA. Usar *Response. Validación de forma aquí; invariantes en dominio.
src/core/, src/modules/, un segundo árbol paralelo.@Entity o @Service en la clase de regla.HttpClient en el componente; Retrofit en el Fragment.PedidoHelper con reglas que debían ser un caso de uso.El MD debe nombrar estas tentaciones. El modelo de arquitectura (Opus/GPT) las evita mejor; Composer las ejecuta más rápido si el prompt fue “mejorá la estructura”.
| Trabajo | Modelo | Por qué |
|---|---|---|
| ¿Este cambio respeta el mapa? ¿Hay que tocar tres capas? | Claude Opus 5 (u Opus reciente), GPT-5.5, GPT-5.6 Sol | Razonan sobre dependencias; explican el porqué |
| Migración larga, rearmar módulos | Claude Fable 5 u Opus con más esfuerzo | Horizonte largo; Composer se queda corto |
| Plan ya escrito: un endpoint, una pantalla, un test | Composer 2.5, Grok 4.6/4.5, Sonnet 5 | Velocidad; el MD ya fijó el patrón |
| Auto | Rutinario | No usarlo para “rediseñá” o “¿hexagonal?” |
Mismo MD, distinto modelo: ver caso L. Flujo: plan con Opus/GPT → implementación con Composer/Grok/Sonnet. El archivo no sustituye esa elección; la hace estable.
Síntoma
Ticket: “filtrar pedidos por estado”. Stack Java/Spring ya por capas.
El agente: inyecta PedidoRepository (JPA) en el @RestController y escribe la consulta ahí. Compila. Rompe el mapa.
Regla
“Controllers: solo HTTP + un use case. Cero repositorios JPA. La consulta vive en infraestructura, detrás de un puerto.”
Resultado: ListarPedidosUseCase + puerto + query en persistencia. El review deja de pelear la capa.
Síntoma
“Mostrá el detalle del pedido en la ficha.”
El agente: pega this.http.get(...) en el componente. Duplica URLs. Impide reusar y testear.
Regla
“Prohibido HttpClient en componentes. Usar PedidosRepository existente en data/.”
Resultado: el componente llama a la fachada; un test de componente no mockea HTTP crudo.
Síntoma
App Android en MVVM. “Al tocar confirmar, mostrar un diálogo.”
El agente: el ViewModel recibe un Context y abre el diálogo. Impide test unitario y rompe MVVM.
Regla
“ViewModel sin Android UI. Emite un evento (SharedFlow). La Fragment/Activity muestra el diálogo.”
Resultado: el ViewModel se testea sin Robolectric de UI.
Síntoma
“El módulo de notificaciones está acoplado.” El repo es un solo deploy.
El agente (Composer, ticket vago): crea notifications-service/, Docker Compose y un REST interno. El equipo no pidió infra.
Regla
“Un solo artefacto desplegable. Extraer un servicio solo con pedido explícito de arquitectura. Preferir un paquete notifications dentro del monolito.”
Resultado: Opus, con esa línea, propone un paquete y un puerto. No un repo nuevo.
Síntoma
El repo usa web/, application/, domain/, infra/.
El agente: crea src/core/usecases y deja las clases viejas. Dos arquitecturas a la vez.
Regla
“No crear src/core, hexagon ni modules. Extender las carpetas existentes. Si el mapa no alcanza: parar y preguntar.”
Resultado: el diff entra donde el equipo ya busca archivos.
Modelos
Importante — clave 4. Lista: Puntos clave.
No hay un modelo “el mejor”. Cambia si hace falta pensar, hacer rápido o mirar una imagen. Los nombres y el catálogo cambian con la herramienta; la lógica (planificar con uno capaz, ejecutar con uno rápido) se mantiene. Auto, cuando exista, depende del plan y de la UI; no asumas Opus. Útil en lo rutinario. Confirmá en el selector qué hay hoy.
| Situación | Modelos | Por qué |
|---|---|---|
| Arquitectura, patrones, refactor grande | Claude Opus 5 / Opus reciente, GPT-5.5, GPT-5.6 Sol; Fable 5 si es muy largo | Razonan el mapa; no conviene el más rápido |
| Día a día: un archivo, seguir un plan | Composer 2.5, Grok 4.6/4.5, Haiku 4.5, Gemini Flash | Rápidos; malos para diseñar el sistema |
| Bug difícil, muchos archivos, sin rediseñar | Opus, Sonnet, GPT-5.5, GPT-5.6 Sol | Cambiar de familia a veces desbloquea |
| Mails, docs, explicar a no técnicos | GPT-5.5/5.6, Claude Sonnet | Composer/Grok están más orientados a editar código |
| Captura, diseño, repo enorme | Gemini 3.1 Pro; también GPT u Opus | Imagen + mucho contexto |
| Trivial | Haiku, Flash, GPT mini/nano, Composer | Opus/Fable es desperdicio |
Casos de uso
Cada caso une quién, el MD, el chat y el modelo. No son tickets de un cliente concreto. Complementan el catálogo de chats (qué carga la herramienta) con el flujo de trabajo.
Quién: desarrollador que entra al equipo. Contexto: el repo ya tiene AGENTS.md o CLAUDE.md en Git. Objetivo: entender el mapa y hacer un cambio chico sin preguntar lo mismo diez veces.
MD + chat + modelo
El MD de la raíz es el briefing (Anthropic: como el primer día). Chat nuevo en la raíz del repo. Modelo: Sonnet o GPT para preguntar; Composer solo cuando el ticket ya está claro.
Pasos
/context y confirmar Memory files. Cursor: Customize → Rules.Se espera: el mapa coincide con el disco; el primer PR no inventa carpetas.
Fallo: abrir solo un submódulo como proyecto y no cargar el MD de la raíz; o pedir “mejorá la arquitectura” el día uno.
Quién: dev del equipo. Contexto: null pointer / validación en un endpoint o pantalla ya existentes. Objetivo: un diff mínimo que respete capas.
MD + chat + modelo
El MD ya dice dónde va el arreglo (controller vs. dominio). Chat nuevo, un ticket. Composer o Grok (o Auto). Si el bug cruza tres capas sin un plan, subir a Opus.
Pasos
Se espera: 1–3 archivos, test si hay invariante, sin carpetas nuevas.
Fallo: Composer “limpia” el paquete entero. El MD debió prohibir el alcance extra.
Quién: senior o quien revisa el PR. Contexto: un diff grande o una duda de diseño. Objetivo: un veredicto, no un rewrite.
MD + chat + modelo
El MD es el mapa de referencia. Chat nuevo (o Ask). Opus o GPT-5.x, no Composer. Pedir que cite el MD y los archivos.
Pasos
Se espera: lista de violaciones o “alineado”, con paths.
Fallo: el modelo propone hexagonal “mejor” y reescribe. El MD debe decir: parar y preguntar.
Quién: full-stack o pareja front/back. Contexto: un campo nuevo en ficha + endpoint. Objetivo: contrato primero, UI después, cada MD anidado en su zona.
MD + chat + modelo
Raíz: quién habla con quién. frontend/AGENTS.md y backend/AGENTS.md (o rules con glob). Plan con Opus/GPT; implementación por frente con Composer/Sonnet. Abrir el workspace en la raíz para que carguen padres + anidados on-demand.
Pasos
Se espera: un contrato estable; la vista no arma la URL a mano si el MD lo prohíbe.
Fallo: un solo chat con Composer crea el endpoint y pega fetch en el componente.
Quién: cualquiera que escriba para humanos. Contexto: explicar un cambio o pedir ayuda. Objetivo: texto usable, sin inventar cifras.
MD + chat + modelo
El MD de “no inventar” aplica igual. Sonnet o GPT, no Composer (está afinado a editar código). Chat nuevo o Ask.
Pasos
Se espera: un borrador que se puede pegar.
Fallo: Composer “completa” con un +40% o un cliente ficticio.
Quién: front. Contexto: diseño en imagen. Objetivo: maqueta en el stack del repo (React o Angular), no un HTML suelto.
MD + chat + modelo
El MD de frontend fija componentes, tokens, “no CSS modules si usamos Tailwind”, etc. Adjuntar la captura. Probar Gemini Pro primero; Opus/GPT si hay que respetar un design system complejo.
Pasos
frontend/ para cargar el MD anidado.components/; no instales otra librería de UI.”Se espera: una pantalla en el árbol existente.
Fallo: crea src/pages-new/ o un proyecto Vite paralelo.
Quién: quien hizo la review. Contexto: segunda vez que el agente mete JPA en el controller (o HTTP en el componente). Objetivo: que el próximo chat no lo repita. Anthropic: esa es la señal para una línea nueva. When to add.
MD + chat + modelo
Editar el MD (o pedir “agregá esta regla a AGENTS.md”). Commit. Chat nuevo (el actual sigue con la copia vieja).
Pasos
Se espera: el tercer intento ya no viola esa capa.
Fallo: corregir solo de palabra y no persistir: el lunes vuelve el mismo error.
Quién: cualquiera. Contexto: acabás de prohibir NgRx / microservicios. Objetivo: que el modelo use la versión nueva.
MD + chat + modelo
Mismo chat = reglas viejas (no hay relectura por turno). Chat nuevo = inyección fresca. Claude Code: /compact o /memory para el MD de raíz. Ver caso D.
Pasos
Se espera: el siguiente mensaje ya no propone lo prohibido.
Fallo: seguir el hilo largo y creer que “ya está en el archivo”.
Quién: equipo con tres frentes. Contexto: el mismo producto, tres árboles. Objetivo: un mapa común y reglas por frente, sin 400 líneas en la raíz.
MD + chat + modelo
Raíz: capas, “un artefacto / no microservicios sin pedido”, Git. android/AGENTS.md (MVVM), web/AGENTS.md (Angular o React), api/AGENTS.md (controllers delgados). Ticket de un frente: Composer. Ticket que cruza contratos: Opus/GPT para el plan.
Pasos
Se espera: un ticket Android no gasta contexto en convenciones de CSS.
Fallo: un AGENTS.md único de 800 líneas; o tres normas contradictorias (“siempre MVVM” vs. un módulo legacy MVP).
Quién: dev + quien mantiene el pipeline. Contexto: el agente saltea tests o “despliega”. Objetivo: el MD dice qué correr en local; la CI impide merge si falla.
MD + chat + modelo
MD: comando exacto (./mvnw -pl pedidos test, npm test -- pedidos.spec.ts). “No push / no prod”. CI: la red de seguridad. Hooks si hay que bloquear un comando. Composer para el arreglo; no Auto para “subí a prod”.
Pasos
Se espera: el agente corre el test del módulo; CI atrapa si se lo saltó.
Fallo: volcar todo el Jenkinsfile en el MD (ruido) o confiar solo en el Markdown para no tocar prod.
Quién: el equipo comparte un repo. Contexto: unos usan Cursor, otros Claude Code. Objetivo: una fuente de verdad.
MD + chat + modelo
Canónico: AGENTS.md. CLAUDE.md = @AGENTS.md + líneas solo de Claude (plan mode, hooks). Claude Code no lee AGENTS.md solo. Cursor lee AGENTS.md; no dupliques en un .mdc alwaysApply. AGENTS.md en docs Anthropic.
Pasos
/context.Se espera: el mismo mapa en las dos herramientas.
Fallo: actualizar solo CLAUDE.md; en Cursor el equipo sigue con el AGENTS viejo (o al revés).
Quién: la misma persona en dos contextos. Contexto: un side project y un repo compartido. Objetivo: no mezclar gustos personales con normas del equipo.
MD + chat + modelo
Equipo: AGENTS.md / CLAUDE.md en Git. Personal: CLAUDE.local.md (gitignore) o User Rules de Cursor (no van a Inline Edit / Ctrl+K). Side project: un MD corto en ese repo, sin copiar el de la empresa.
Pasos
Se espera: el PR del equipo no trae “respondé en rioplatense” ni URLs de un sandbox casero.
Fallo: commitear CLAUDE.local.md o User Rules como si fueran del proyecto.
React / Java y otros stacks
La regla genérica: escribir el mapa del equipo, no el del libro. Si el servicio es un @RestController que llama a un JpaRepository y así está acordado, el MD lo dice. No impongas hexagonal “porque es best practice”.
Mismo esquema en cada stack: capas típicas → raíz vs. anidado → snippet → fallo del agente → modelo.
Árbol frecuente (no obligatorio): web (controllers) → application / service → domain (si existe) → repository / JPA. Tests: JUnit (y Mockito) junto al módulo; tests de dominio sin levantar Spring si el equipo ya lo hace así.
Raíz: “un deploy; no extraer microservicio sin pedido”; “controller sin SQL”; comando ./mvnw test. Anidado / glob src/main/java/**: DTOs, no devolver *Entity, validación de forma vs. invariante.
# api/AGENTS.md (ejemplo; adaptá a *vuestras* carpetas)
- Controller: request → use case/service → response. Sin EntityManager.
- No crear notifications-service/ ni un segundo Spring Boot.
- Test de regla de negocio: JUnit en domain, sin @SpringBootTest
salvo que el ticket sea de slice web.
Fallo típico: consulta JPQL en el controller; o “pasar a microservicios”. Modelo: endpoint chico → Composer/Grok; ¿rompe capas? → Opus/GPT.
React: componente + hooks; datos en un módulo de API/query (fetch, React Query, etc.), no URLs sueltas en cada JSX. Angular (si el repo lo usa): componente flaco + servicio/repositorio; HttpClient no en el .ts de la plantilla. No mezclar ambos “por si acaso” en el mismo MD si el producto es uno solo.
Next.js vs. SPA: el MD debe fijar el que está en el disco. App Router: rutas en app/, APIs en app/api/ si ya es así. Pages Router: pages/. Una SPA Vite: src/features/.... Cursor Learn usa el ejemplo: tests Vitest (no Jest), Tailwind, APIs en app/api/ — solo si el equipo lo usa. Customizing agents.
# web/AGENTS.md
- Este front es React + Vite (no Next). No crear app/ ni pages/.
- Fetch solo en src/data/* o *Api.ts. Prohibido URL hardcoded en componentes.
- Un feature = src/features/<nombre>/. No crear src/screens-2/.
# Si fuera Next.js (otro repo; no copies esto “por las dudas”)
- App Router. Rutas nuevas en app/(marketing)/ o app/(app)/ según lo existente.
- Route handlers: app/api/<recurso>/route.ts. No pages/api en este repo.
Fallo: instala Next en una SPA; o pega fetch('/api/...') en diez componentes. Modelo: UI de captura → Gemini; feature con contrato → plan Opus, UI Composer.
Alineado al cap. 7. Raíz: “Android nativo, no wrapper”. Anidado: ViewModel sin widgets; UI observa estado; red en data source/repository.
# android/AGENTS.md
- MVVM en features nuevas. Un módulo legacy en MVP: no migrar a ViewModel
sin pedido.
- ViewModel sin android.view.* ni Context para diálogos.
- Retrofit/OkHttp solo en data/.
Fallo: diálogo desde el ViewModel; o Compose “porque es moderno” en una pantalla XML. Modelo: bug de UI → Composer; cambio de navegación/arquitectura → Opus.
Nest: módulos, controllers delgados, providers. Express: routers + services si el equipo los tiene; no un index.js de 2 000 líneas “mejorado” a Nest en un ticket de un bug.
# server/AGENTS.md
- Express + routers en src/routes. Lógica en src/services.
- No migrar a Nest/Fastify en este ticket.
- No devolver el documento Mongo crudo; usar un mapper.
Fallo: reescribe Express a Nest. Modelo: ruta nueva → Composer; “¿módulo Nest?” → Opus y decisión humana.
Un párrafo: FastAPI suele separar routers, schemas (Pydantic) y servicios. Django: views/servicios vs. models; no meter SQL crudo en la view si el equipo usa el ORM. El MD nombra vuestros paquetes.
# api-py/AGENTS.md
- FastAPI: routers en app/api/; reglas en app/services/; schemas en app/schemas/.
- No crear un segundo app Django. Tests: pytest en tests/.
Fallo: mete lógica de negocio en el router; o cambia FastAPI por Django. Modelo: endpoint → Composer; rediseño de paquetes → Opus.
# AGENTS.md (cualquier lenguaje)
- Este repo se organiza así: [pegar el árbol real de 8 líneas].
- Un cambio de <tipo> va en <carpeta>. No crear <carpeta que no existe>.
- No inventar microservicios, frameworks nuevos ni métricas.
- Tests: [comando real]. No commit/push sin pedido.
Si no podés llenar los corchetes mirando el disco, no publiques el MD: primero acordá el mapa con el equipo.
Herramientas y pesos abiertos
Esta guía no es solo de Cursor. El mapa del repo (quién habla con quién, qué no hacer) se puede usar en Claude Code, OpenCode, Copilot, Cline, VS Code, Gemini CLI y otros. Cursor queda como un IDE más: Agent + AGENTS.md y/o .cursor/rules (Rules).
AGENTS.md es la convención portable (agents.md, Agentic AI Foundation / Linux Foundation). No todas las herramientas la leen solas: varias tienen archivo propio. CLAUDE.md es de Claude Code (importá AGENTS si el equipo es mixto). Práctica: un AGENTS.md canónico; adaptadores cortos, no tres tratados.
OpenCode es un agente de código open source (CLI / entorno propio). No es Cursor (IDE comercial con Agent + rules .mdc) ni Claude Code (CLI de Anthropic centrado en CLAUDE.md). Podés apuntarlo a distintos proveedores de modelos (cerrados o abiertos), según la config del producto.
Documentación oficial de reglas: opencode.ai/docs/rules.
/init recorre el repo y crea o mejora un AGENTS.md (comandos, arquitectura no obvia, convenciones; no lo pisa a ciegas).AGENTS.md en la raíz. Personal: ~/.config/opencode/AGENTS.md (no se comparte en Git).AGENTS.md, puede usar CLAUDE.md del proyecto; en global, ~/.claude/CLAUDE.md si no existe el AGENTS de OpenCode. Si hay ambos, gana AGENTS.md. Se puede desactivar con OPENCODE_DISABLE_CLAUDE_CODE (y variantes).opencode.json admite instructions (archivos locales, globs, URL remotas). Se combinan con AGENTS.md. Timeout de URLs: 5 s (doc actual).Hay una línea V2 (opencode.ai/v2/docs/instructions) que, en 2026, describe descubrimiento solo de AGENTS.md (sin fallback CLAUDE.md ni resolución de instructions en json). No inventes paridad: mirá qué binario usás. Ver Alcance y límites.
Agentes Build/Plan y markdown en .opencode/agents/: docs/agents. Eso es config de OpenCode, no reemplaza el AGENTS.md del repo.
Consultar: Rules · Referencias.
Familias que suele verse en coding (nombres y calidad cambian rápido; no es un ranking):
Cuándo alcanzan: un archivo, un rename, un test, un repo que no puede salir de la red (privacidad, air-gap), coste bajo, prototipos. El MD corto y concreto ayuda más acá: el modelo tiene menos “juicio” de arquitectura y se apoya en las reglas.
Cuándo sigue siendo más seguro un frontier cerrado (Opus, GPT-5.x, etc.): “¿rompemos el patrón?”, migraciones, diffs de muchas capas, review de diseño. No afirmamos que un peso abierto iguale a Opus en arquitectura. A veces un DeepSeek/Qwen grande se acerca en un ticket acotado; no lo des por sentado. Probá en vuestro repo.
Dónde corren: Ollama, vLLM, APIs de terceros, o el selector de OpenCode/Continue/Cline. Adaptar pesos (LoRA) no es escribir un MD: ver Entrenar o adaptar un modelo propio. La herramienta inyecta el MD; el modelo lo interpreta peor o mejor. Mismo AGENTS.md, distinto techo.
Tabla de cómo obtienen instrucciones de proyecto. No es un ranking. “Lee AGENTS.md” solo si la doc lo dice. Cursor: una línea — IDE con Agent; AGENTS.md y/o .cursor/rules (Rules).
| Herramienta | Qué es | Instrucciones de proyecto (doc) | Enlace |
|---|---|---|---|
| Claude Code | CLI / agente de Anthropic | CLAUDE.md (no lee AGENTS.md solo; usá @AGENTS.md). Anidados on-demand. .claude/rules con paths. |
CLAUDE.md |
| OpenCode | Agente OSS (CLI) | AGENTS.md de proyecto + ~/.config/opencode/AGENTS.md. Fallback CLAUDE.md si no hay AGENTS (doc estable). V2 puede diferir. |
Rules |
| VS Code + Copilot Chat | Editor Microsoft + chat/agente (no es Cursor) | .github/copilot-instructions.md; AGENTS.md en raíz (setting chat.useAgentsMdFile); anidados experimentales; también puede CLAUDE.md (chat.useClaudeMdFile). |
VS Code custom instructions |
| GitHub Copilot (GitHub.com / cloud agent) | Chat, review y agentes en GitHub | .github/copilot-instructions.md; .github/instructions/*.instructions.md + applyTo. Cloud agent también lista **/AGENTS.md, CLAUDE.md, GEMINI.md en best practices. |
Custom instructions · cloud agent |
| Continue | Extensión OSS de chat/agente en el IDE | .continue/rules/*.md (globs, alwaysApply). La doc de rules no presenta AGENTS.md como nativo. No aplica a autocomplete. |
Continue Rules |
| Cline | Agente en el editor (VS Code, etc.) | Primario: .clinerules/. También detecta .cursorrules, .windsurfrules, y AGENTS.md / ~/.agents/AGENTS.md. Condicionales con paths en frontmatter. |
Cline Rules |
| Roo Code | Agente en VS Code (ecosistema Cline) | Preferido: .roo/rules/ (y ~/.roo/rules/ global). Fallback: .roorules. También carga AGENTS.md (o AGENT.md) de la raíz; se desactiva con roo-cline.useAgentRules. |
Custom Instructions |
| Aider | Agente en terminal (git-centric) | FAQ de agents.md: .aider.conf.yml → read: AGENTS.md. Histórico: CONVENTIONS.md. |
agents.md (FAQ Aider) |
| Windsurf / Devin Desktop (Cascade) | IDE con agente Cascade | Rules: .devin/rules/ (preferido) o .windsurf/rules/; legado .windsurfrules. AGENTS.md entra al mismo motor (raíz = always-on; subcarpeta = glob). Memories automáticas ≠ reglas de equipo. |
Memories & Rules |
| OpenAI Codex / ChatGPT coding agent | CLI, TUI y agentes de OpenAI (2026) | Lee AGENTS.md (y AGENTS.override.md) al arrancar: global ~/.codex/ + cadena desde la raíz del repo hasta el cwd. Anidados: el más cercano pisa. /init genera un scaffold. Límite por defecto ~32 KiB. |
Codex: AGENTS.md |
| Amazon Q Developer | Asistente de AWS en IDE / GitHub / GitLab | Markdown en .amazonq/rules/. La doc de Q no pone AGENTS.md como archivo primario. |
Project rules |
| Gemini CLI | CLI de Google | Por defecto GEMINI.md (global ~/.gemini/, proyecto, JIT). Se puede poner context.fileName a AGENTS.md (o una lista). /memory show / reload. |
GEMINI.md |
| JetBrains AI Assistant / Junie | Chat y agentes en IntelliJ y familia | Agentes (Junie, Codex…): AGENTS.md (Claude Agent: CLAUDE.md). Junie CLI: .junie/AGENTS.md, o raíz AGENTS.md + .junie/playbook.md / .junie/rules/; legado .junie/guidelines.md. Global: ~/.junie/AGENTS.md. El chat de AI Assistant también tiene Project rules en el IDE (no viajan con el repo igual que el MD). |
Agent instructions · Junie guidelines |
| Zed AI | Editor Zed + agente nativo | Personal: ~/.config/zed/AGENTS.md. En el proyecto usa el primer archivo de esta lista: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. |
Zed Instructions |
| Goose (Block / AAIF) | Agente OSS (desktop + CLI) | Hints: .goosehints y/o AGENTS.md. Default de CONTEXT_FILE_NAMES: [".goosehints", "AGENTS.md"]. Se puede ampliar a CLAUDE.md, etc. Algunas páginas también nombran AGENT.md. |
Goosehints · env vars |
Recetas de symlink a diez nombres (blogs, agentssync): no oficiales. El contrato es la doc de cada fila.
AGENTS.md no es un lector universal. Es el formato portable. Claude Code, Amazon Q, Continue y (sin config) Gemini CLI usan otro archivo. En Zed gana el primer nombre de una lista (un .cursorrules viejo puede tapar el AGENTS.md). Un adaptador corto o un import vale más que copiar el tratado.
@AGENTS.md + 5 líneas de Claude Code. OpenCode puede usarlo de fallback si no hay AGENTS..github/copilot-instructions.md si el flujo de GitHub no toma AGENTS. Continue: .continue/rules/. Amazon Q: .amazonq/rules/. Gemini CLI: GEMINI.md o context.fileName.Casos de uso
Situaciones de equipo de software, genéricas. No son un producto de cliente ni un sitio personal.
Síntoma
Se pide un párrafo para un comunicado interno. El agente agrega “+40% de adopción” y un nombre de cliente que nadie dio.
Sin regla: el texto no se puede publicar. Hay que reescribirlo a mano.
Regla
“No inventar cifras, clientes, certificaciones ni resultados. Si falta un dato, omitir o preguntar.”
Resultado: el borrador es corto y usable. El hueco se ve; no se disimula con un número.
Síntoma
“Agregá validación al email del formulario.” El agente suma login social, notificaciones y un panel.
Sin regla: el diff es inrevisable. El ticket de un día se vuelve una semana.
Regla
“Solo lo pedido. Prohibido login, pagos, admin o refactors extra. Si hace falta, proponerlo en una frase y esperar.”
Resultado: un archivo de validación. El review dura minutos.
Síntoma
Cambio de regla de cancelación de pedido. El agente toca dominio y no agrega test.
Sin regla: CI rojo o un bug en el siguiente release.
Regla en tests (paths)
“Todo cambio de invariante de dominio lleva test en domain sin Spring. No cerrar sin eso.”
Resultado: el caso “pedido enviado no se cancela” queda escrito.
Síntoma
“Arreglá el null pointer.” El agente commitea y pushea a la rama compartida.
Sin regla: historial sucio; a veces un hook de secretos o un push a main.
Regla
“No commit, push, rebase ni --no-verify sin pedido explícito.” Complementar con hook si hace falta candado.
Resultado: el diff queda local hasta que alguien lo pide.
Síntoma
Se agregó “no usar NgRx”. El mismo chat sigue proponiendo un store.
Causa: no hay relectura por turno. Ver caso D.
Práctica
Chat nuevo, o “leé AGENTS.md”. Avisar al equipo: pull + chat nuevo.
Resultado: el siguiente hilo ya no propone NgRx.
Casos de uso y flujo de trabajo
Esto no es un mega AGENTS.md. Los bloques para pegar viven en docs/casos/prompts-base.md (prompts de chat) y en las fichas (qué va en el MD). Acá: cómo se usa el chat, qué suele hacer cada familia de modelos, y ventajas / desventajas de cada caso.
AGENTS.md corto en la raíz. Chat nuevo en esa raíz.frontend/AGENTS.md y api/AGENTS.md. Workspace en la raíz para que carguen padres + anidados.Pares anidados vs. un solo archivo, y rápido vs. pensar: #vd-nested · #vd-fast-vs-think. Resumen: tabla.
Producto tipo catálogo B2B. No hay que inventar un panel de admin. Fichas: bug, feature, carpetas.
Setup
FilterBar + ProductList + Pagination. Al cambiar categoría, sigue page=4 y la grilla queda vacía. Chat nuevo, ticket de un síntoma.
Pasos en la herramienta
Cómo suele actuar el modelo
Composer / Grok / Haiku cierran el bug en pocos archivos si el MD nombra los componentes; sin MD, inventan store o login. Opus / GPT explican el dueño del estado; lentos para un reset de página. Sonnet alcanza si el estado está duplicado. Gemini solo si hay captura de la grilla vacía. Auto / local: rutinario; no para “rearmar el catálogo”.
Fallo esperado: Zustand “para el filtro” o una ruta de admin.
Ventajas
Desventajas
Setup
Export CSV de pedidos: misma lista, mismos filtros, GET ya definido. Hay ordersApi.ts y useOrders.
Pasos
fetch en el JSX.Cómo suele actuar el modelo
Composer pega fetch en el onClick si no hay anidado de front. Opus describe bien el flujo y igual puede dejar HTTP en el componente si el MD no lo prohíbe. Gemini ayuda con una captura del botón; no decide el cliente. Local: solo si el plan ya está escrito y el api module es obvio.
Fallo esperado: src/features/export/ con store y URL duplicada.
Ventajas
fetch en la vista.frontend/.Desventajas
Setup
Ticket: badge de stock en ProductCard. El agente mueve a src/features/ y deja fetch en la card.
Pasos
Cómo suele actuar el modelo
Composer / Grok priorizan un árbol “más limpio”. Opus en el mismo chat sigue el árbol nuevo; hace falta chat nuevo. Auto: no; elige rápido y multiplica el atajo.
Fallo esperado: el review valida un rediseño cuando el ticket era un badge.
Ventajas
Desventajas
Setup
Hay Vitest en la lista. El agente arregla el filtro y no toca el spec. DoD del equipo: el caso de regresión en el mismo archivo de test.
Cómo suele actuar el modelo
Composer / Haiku cierran el JSX y declaran listo. Opus / Sonnet agregan el caso si el MD lo exige. Local: peor aún; hay que poner el comando de test en el MD.
Ventajas
Desventajas
Un Spring Boot, un deploy. Fichas: endpoint, legacy, capas.
Setup
GET /api/shipments/{id}/events. Ya hay ShipmentController y repository. Controller → service → repository → DTO.
Cómo suele actuar el modelo
Composer mete @Query en el controller o saltea JUnit. Opus propone hexagonal completo si el MD no dice “este repo es controller + @Service + JPA”. Sonnet suele respetar el trío si hay un endpoint hermano.
Fallo esperado: devolver *Entity o un segundo @SpringBootApplication.
Ventajas
Desventajas
Setup
Campo notes en el DTO de factura y en la tabla existente. Un JAR. El código mezcla un poco las capas; el backlog no pide split.
Cómo suele actuar el modelo
Composer extrae un módulo Maven. Opus / GPT dibujan Kafka si el prompt dice “mejorá”. Local: no diseña el split, pero deja el campo en un mapper y se olvida del DTO.
Ventajas
Desventajas
Setup
Filtrar facturas por estado. El atajo: InvoiceRepository inyectado en el @RestController.
Cómo suele actuar el modelo
Composer / Haiku lo hacen porque es un archivo. Opus a veces lo marca, a veces lo deja “porque es un GET”. El MD tiene que decir “nunca repository en el controller”, no “preferí capas”.
Ventajas
Desventajas
Setup
Invariante: factura pagada no se anula. El agente toca el service y no agrega test. El MD debe exigir JUnit del service (sin Spring) o el slice que el módulo ya usa.
Ventajas
Desventajas
@SpringBootTest de más pone lento el módulo si no era la convención.Nombres de catálogo cambian. La lógica no. No hay porcentajes de acierto: es heurística de equipo.
Ventajas
Desventajas
Ventajas
Desventajas
Ventajas
Desventajas
Ventajas
Desventajas
Ventajas
Desventajas
Ventajas
Desventajas
src/pages-new/ si el MD no fija el árbol.Ventajas
Desventajas
Ventajas
Desventajas
SYSTEM es instrucción, no entrenamiento. Ver #entrenamiento.Ventajas del anidado
Desventajas del anidado
frontend/, esas reglas no entran.Ventajas de separar
Desventajas de no separar
src/features/ o un JAR nuevo.Entrenamiento / modelos propios
AGENTS.md no entrena. Es instrucción inyectada en la ventana de contexto. Los pesos del modelo no cambian. RAG tampoco entrena: recupera texto al vuelo y lo pega al prompt. Fine-tune / LoRA sí toca (o añade) parámetros. Glosario Anthropic: fine-tuning y RAG.
Familias open y dónde corren: capítulo 11. Esto no es receta de cluster ni números de GPU inventados.
| Qué | Cambia pesos | Para qué |
|---|---|---|
| AGENTS.md, prompts, system de un Modelfile | No | Mapa, prohibiciones, comandos. Barato de actualizar. |
| RAG (docs internas al contexto) | No | Hechos que cambian: runbooks, tickets. Calidad = lo que se recupera. |
| Fine-tune / LoRA / QLoRA | Sí (adapter o full) | Estilo, jerga, formato rígido. Coste de datos, eval y legal. |
| Entrenar desde cero | Sí, todo | Casi nunca un equipo de producto: datos, coste, GPUs, gente. |
Ollama: SYSTEM en el Modelfile es lo mismo de familia que el MD (instrucción). ADAPTER es un LoRA ya entrenado sobre la misma base; si la base no coincide, el comportamiento es errático (doc Ollama).
Herramientas típicas de adaptación (open): PEFT (LoRA), TRL SFTTrainer. Papers: LoRA, QLoRA.
Empezá por MD + modelo de frontera. Pasa a LoRA cuando el eval del repo muestra un fallo estable de estilo o formato que el MD no mueve (y tenés datos limpios). No pases a LoRA porque “queremos un modelo de la empresa”.
Ventajas
Desventajas
Ventajas
Desventajas
Ventajas
Desventajas
ADAPTER) o vLLM. Comparar contra frontier + AGENTS.md en el mismo eval. Si no gana, no desplegar.Consultar: referencias de fine-tune / LoRA · modelos abiertos · Anthropic glossary.
Casos de uso y flujo de trabajo
Una línea por caso. El detalle está en el ancla. No hay cifras.
| Caso | Ventaja (una línea) | Desventaja (una línea) |
|---|---|---|
| Catálogo A · MD ya en Git | El mapa llega solo. | No es candado; el workspace mal abierto no carga. |
| Catálogo E · anidado | UI y API no se ensucian entre sí. | On-demand: hay que tocar esa carpeta. |
| Catálogo I · texto duplicado | — | Doble de tokens; peor contexto. |
| Catálogo L · mismo MD, otro modelo | El ancla sirve para plan y para ejecutar. | El modelo rápido igual rompe el mapa si el ticket es vago. |
| React · bug acotado | Diff de componentes existentes. | El rápido inventa store/login sin alcance. |
| React · UI + API client | Reusa el cliente y los filtros. | Un solo chat pega fetch en el JSX. |
| React · reescribe carpetas | Opus en review ve el segundo árbol. | El hilo sucio sigue el árbol nuevo. |
| React · tests | El spec del módulo cubre la regresión. | El MD no corre Vitest. |
| Java · endpoint | Copiar el GET vecino por capas. | SQL en el controller compila igual. |
| Java · legacy | “Un deploy” evita un split fantasma. | Prompt vago autoriza microservicios. |
| Java · controller→DB | La regla vive en el service. | El atajo es el diff más corto. |
| Java · JUnit | El invariante queda escrito. | El rápido saltea “porque es chico”. |
| Composer | Ejecuta un plan con paths. | Ignora capas si le pedís “mejorá”. |
| Opus | Lee el mapa; buen revisor. | Lento; rediseña sin MD. |
| Sonnet | Medio para bugs que cruzan archivos. | Ni el techo de Opus ni la velocidad del rápido. |
| Haiku / Flash | Trivial barato. | Copia atajos del archivo abierto. |
| GPT | Plan y prosa; pareja de review. | Ofrece arquitectura “mejor” que el disco. |
| Gemini | Captura / UI. | No decide HTTP ni Spring. |
| Auto | Rutinario sin elegir modelo. | No lo uses para rediseñar. |
| Open / local | Privacidad y edits chicos. | No iguala a Opus en un diseño nuevo. |
| Anidado vs raíz | Menos tokens, regla del stack correcto. | Hay que abrir la raíz en tickets cruzados. |
| Tokens · MD gordo vs. fino | Raíz corta + glob: cabe y se cumple. | El tratado se paga en cada chat y se ignora el medio. |
| Rápido vs pensar | Plan y parche en chats distintos. | Un solo chat rápido reescribe el árbol. |
| Solo MD + frontier | Commit y chat nuevo. | Se puede ignorar; no entrena Tab. |
| RAG | Docs que cambian sin reentrenar. | Recuperar mal = alucinación segura. |
| LoRA / fine-tune | Estilo y formato de casa. | Datos, licencia, eval; no reemplaza el mapa. |
| Equipo + MD en Git | Una norma versionada; onboarding con chat nuevo. | Hay que revisar el MD como docs; no es candado. |
| Git del MD | Clone → reglas; PR de código y de normas. | Conflicto de merge; no commitear local/secrets. |
Catálogo completo A–L: cada ficha ya tiene tarjetas verdes/ámbar debajo del fallo. Volver al catálogo.
Trabajo en equipo
Importante — clave 2. Tras mergear el MD: chat nuevo (clave 3). Lista: Puntos clave.
El mapa del repo no vive en el historial de chat de cada persona. Vive en Git: AGENTS.md / CLAUDE.md (y anidados). Quien clona y abre un chat nuevo ya tiene las reglas. Pegar cinco versiones distintas en cinco chats es el anti-patrón: se actualiza el archivo, se commitea, se avisa. Bloques listos para cada herramienta: docs/casos/instrucciones-por-herramienta.md.
Lista corta de adopción (después de este capítulo): §17. Flujo de un ticket: §13.
El MD de equipo se trata como documentación: branch, PR, review, merge. El chat es desechable. Si una regla solo existió en un hilo, el lunes el compañero no la tiene.
| Dónde | Qué | Git |
|---|---|---|
AGENTS.md / CLAUDE.md (y anidados) |
Mapa, capas, prohibiciones del producto | Sí |
| Cursor User Rules (Customize) | Tono, idioma, gustos. Solo Agent Chat; no Inline Edit (Ctrl+K). Rules | No (cuenta) |
CLAUDE.local.md |
Igual: personal. Claude Code lo concatena. Docs | No: gitignore |
| Cursor Team Rules (dashboard Team/Enterprise) | Org-wide; pueden ir con glob; “Enforce” impide apagarlas. Precedencia: Team → Project → User. Aplican a todos los repos del equipo. Team Rules | No están en el repo; no reemplazan el AGENTS.md del producto |
Team Rules sirven para cumplimiento transversal (secreto, licencia). El mapa de este servicio sigue en Git: si no, un clone sin Cursor Team no ve el cauce.
Si el agente cometió el mismo error dos veces (SQL en el controller, fetch en el JSX), el PR que corrige el código incluye la línea nueva en el MD. El review valida ambos. No “la regla la subo después”.
Quien abre el PR es responsable del diff, también del que escribió el agente. El modelo no firma el merge.
/context. Cursor: Customize → Rules.La persona dueña de arquitectura usa un chat de review (Opus/GPT): “¿rompe el patrón?”. Quien implementa usa el modelo rápido con el MD ya mergeado. El plan se pega o se linkea; no se improvisa un segundo mapa en el hilo de Composer. Prompts de las dos fases: T8 en prompts-base.md.
Nada de passwords, tokens, .env, claves ni pesos de modelos en el MD. El Markdown no bloquea un push. Hooks, permisos de la herramienta y CI sí. Anthropic: contexto ≠ candado. Cursor: Team Rules enforced no sustituyen el control de secretos.
Segunda vez el mismo fallo en review, o cuando el mapa del disco cambió de verdad. No anticipar diez stacks que el repo no tiene. Anthropic: si dos reglas chocan, el modelo elige cualquiera — recortar, no acumular. Techo útil: ~200 líneas (Claude) / reglas Cursor < ~500. CLAUDE.md · Rules.
Ventajas
Desventajas
Clave 2 El detalle está en §16, no acá otra vez.
AGENTS.md / CLAUDE.md con el código que esas reglas describen. Un repo sin el MD es un mapa que solo existe en un laptop..gitignore: CLAUDE.local.md, User-only, .env, credenciales, pesos (*.gguf, checkpoints). No “por las dudas” un adapter LoRA con datos de cliente.# .gitignore (equipo)
CLAUDE.local.md
.env
.env.*
!.env.example
*.gguf
*.safetensors
Ventajas
Desventajas
CLAUDE.local.md o un .env es un incidente, no un detalle.Consultar: Cursor Rules (proyecto, user, Team) · CLAUDE.md y CLAUDE.local.md · instrucciones por herramienta.
Adopción
AGENTS.md o CLAUDE.md. Si hay dos herramientas: un archivo + import, sin duplicar./init, revisar, borrar lo inventado, commitear.CLAUDE.local.md, .env y pesos: gitignore. Ver Git.Glosario
.md).mdc./init /context /memory /compactAGENTS.md del repo. Ver equipo.Consultar
Páginas oficiales para contrastar esta guía. Si un detalle de producto cambia, prevalece el enlace. El foro no es contrato de producto.
@; Claude Code no lee AGENTS.md salvo import; .claude/rules con paths; /init, /context, /compact; contexto, no candado (hooks)./compact o /memory; /clear; qué poner y qué no.@regla; AGENTS.md vs .mdc; anidados (lo específico suele ganar). Team Rules (planes Team/Enterprise): dashboard; Enforce; glob opcional; precedencia Team → Project → User; aplican a todos los repos del equipo. User Rules no van a Inline Edit (Ctrl+K).read: AGENTS.md, Gemini CLI, anidados, quién adopta). Steward: Agentic AI Foundation / Linux Foundation. No implica que todas las herramientas lo lean solas.AGENTS.md de proyecto y global; /init; fallback CLAUDE.md si no hay AGENTS; opencode.json → instructions.AGENTS.md (puede no aplicar fallbacks de la doc estable)..opencode/agents/, distinto del AGENTS.md del repo..github/copilot-instructions.md; AGENTS.md (chat.useAgentsMdFile); anidados experimentales; CLAUDE.md (chat.useClaudeMdFile). Distinto de Cursor..github/copilot-instructions.md y *.instructions.md con applyTo.AGENTS.md / CLAUDE.md / GEMINI.md..continue/rules/; no autocomplete; no presenta AGENTS.md como nativo..clinerules/; también .cursorrules, .windsurfrules, AGENTS.md y ~/.agents/AGENTS.md..roo/rules/, .roorules, AGENTS.md / AGENT.md..devin/rules/, .windsurf/rules/, AGENTS.md.AGENTS.override.md; /init..amazonq/rules/ (no AGENTS.md como primario).GEMINI.md; context.fileName puede ser AGENTS.md.AGENTS.md / CLAUDE.md; chat: Project rules del IDE..junie/AGENTS.md, raíz AGENTS.md, legado .junie/guidelines.md.AGENTS.md; en proyecto, primer match de una lista de nombres..goosehints / hints de proyecto.CONTEXT_FILE_NAMES default [".goosehints", "AGENTS.md"].SYSTEM es instrucción (no entrena); ADAPTER aplica un LoRA ya entrenado.AGENTS.md y en un .mdc con alwaysApply. Úsalo como pista; verificá en Customize → Rules.También: Alcance y límites (versiones) · cómo usar (5 min) · cuidar los tokens · capítulo 11 · tabla no-Cursor · equipo y Git · cómo se inyecta · CLAUDE vs AGENTS · al abrir un chat.