Casos prácticos: legacy vs. proyecto nuevo

Un síntoma. Los componentes ya existen.

Contexto

Catálogo en producción. Al cambiar la categoría con página > 1, la grilla queda vacía: FilterBar actualiza el filtro y ProductList sigue pidiendo page=4. El contrato HTTP no cambia. No hay ticket de login ni de rediseño.

Pasos

1. Chat: nuevo, workspace en la raíz. Un síntoma. No reusar el hilo de ayer.
2. Modelo: rápido (Composer / Grok). pensar solo si el estado vive en tres padres.
3. AGENTS.md: mapa src/pages/, src/components/, src/api/; “solo lo que el ticket nombra”; no store ni admin; si hay spec, extenderlo.

Prompt

Plantilla completa: prompts-base R1. Corto:

Bug acotado. No rediseñes.
Síntoma: [al cambiar categoría con page>1 la grilla queda vacía].
Componentes: [FilterBar, ProductList, Pagination].
Tocá solo esos archivos y el spec si existe.
Al cambiar filtro, page = 1. Sin login, store ni cliente HTTP nuevo.

DoD

Categoría con page > 1 vuelve a página 1. Mismos componentes, mismo rol. Spec tocado en rojo→verde si existía. Sin commit.

Ver más: #tr-react-bug · ficha react-bug-acotado.md.

GET nuevo. Mismo controller, service y repository.

Contexto

Spring Boot en marcha. Ticket: GET /api/shipments/{id}/events. Ya existen Shipment, el repository y un controller con el GET del envío. Hay que agregar lectura, no un bounded context.

Pasos

1. Chat: nuevo. Nombrá el GET vecino a copiar. Un solo artefacto.
2. Modelo: rápido con el vecino. pensar si propone módulo Maven o hexagonal.
3. AGENTS.md: controller delgado → service → repository → DTO; no *Entity en JSON; JUnit del patrón del módulo; un deploy.

Prompt

prompts-base J1. Corto:

Endpoint nuevo, mismas capas que el vecino. Un Spring Boot.
GET /api/shipments/{id}/events. Paquete de shipments, no "events-service".
Controller sin SQL. JSON = DTO. JUnit como el GET vecino.

DoD

El GET responde DTO. Tres tipos (controller / service / repository). Camino feliz + “no existe” si ese 404 ya es convención. ./mvnw test en el módulo. Sin segundo Boot.

Ver más: #tr-java-endpoint · java-spring-endpoint.md.

Un campo. Un JAR. Nadie pidió Kafka.

Contexto

Facturación: un deploy, un esquema, paquetes invoice, customer, mail. Ticket: persistir notes (texto corto) en la tabla que ya existe. El código mezcla un poco las capas; el backlog no pide split.

Pasos

1. Chat: ticket literal (“campo notes, mismos archivos que dueDate”). Si ya apareció un *-service, chat nuevo, no negociar el split.
2. Modelo: rápido para el campo. pensar solo para decir “no hace falta un proceso nuevo”.
3. AGENTS.md: “un Spring Boot, un artefacto”; campo en el paquete dueño; prohibido segundo Boot, Kafka, hexagonalizar de paso.

Prompt

prompts-base J2.

DoD

Campo ida y vuelta en el API existente. Migración solo si el equipo ya versiona schema. Cero procesos nuevos. Sin commit.

Ver más: #tr-java-legacy · java-spring-legacy.md.

Copiá el archivo de al lado. No el del tutorial.

Contexto

App Android en MVVM, o front Angular con features por carpeta. Ticket chico: un campo más en la lista, un diálogo de confirmación, un método en el servicio que ya lista. Hay un vecino que hace exactamente eso. El riesgo no es “no saber el framework”: es que el agente traiga Compose Navigation nueva, un HttpClient en el componente, o una Activity gorda “porque es más simple”.

Pasos

1. Chat: nombrá el path del vecino. “Mismo paquete, mismo estilo. No inventes capa.”
2. Modelo: rápido si el vecino es obvio. pensar (T3) si duda entre Activity gorda y ViewModel.
3. AGENTS.md: Android: ViewModel sin Views; HTTP en el repositorio/capa de datos. Angular: el componente no usa HttpClient; pasa por fachada/repositorio. “No crear árbol features/ o módulo nuevo si el disco no lo tiene.”

Prompt

Angular: A1. Android: D1. Si reescribe el toolkit: D2 / A3. Corto:

Mismo patrón que el vecino. No el del tutorial.

Vecino a copiar: [OrderListViewModel / pedidos.service.ts / path].
Ticket: [campo visible en la fila / diálogo al confirmar].
Android: el ViewModel no importa Activity/Fragment; el diálogo lo muestra la vista.
Angular: HTTP solo en el servicio/fachada, no en el .ts de la plantilla.
No Navigation Component nuevo, no módulo Angular nuevo, no librería.
Listá archivos (máximo los del paquete) y esperá OK de una línea.

DoD

El diff se lee al lado del vecino: mismos nombres, misma capa. Cero librerías nuevas. El diálogo o el campo se puede demo en el flujo existente.

Ver más: #arquitectura · Angular A1 · Android D1 · si duda el patrón, T3.

El módulo viejo casi no tiene specs. Un caso del invariante.

Contexto

El arreglo ya está (o va en el mismo PR). El módulo tiene cero tests, o tres verdes que no cubren el síntoma. El equipo no pidió “cobertura del paquete” ni migrar de JUnit 4 a 5, ni de Jest a Vitest.

Pasos

1. Chat: “un caso en el spec que ya existe, o un archivo junto al código, estilo vecino”. Corré solo ese path.
2. Modelo: rápido. pensar solo si hay que elegir unit vs. e2e — y igual no instales Playwright de paso.
3. AGENTS.md: comando (npm test / ./mvnw test); “no reescribir tests verdes”; “cambio de invariante → test”; runner del disco, no otro.

Prompt

Front: prompts-base R5. Java: J4.

DoD

El caso nuevo falla en HEAD (o si revertís el fix) y pasa con el arreglo. Comando y salida pegados. Cero infra nueva de test. Sin commit.

Ver más: #tr-react-tests · #tr-java-junit.

Exploración de solo lectura. Plan cerrado. Chat B implementa.

Contexto

El módulo es grande y el síntoma no es obvio (estado duplicado, regla de anulación, un job que toca mail y persistencia). Un solo hilo “pensá y codeá” termina moviendo carpetas. El equipo quiere entender el cauce y luego un diff acotado.

Pasos

1. Chat A: pensar (Opus / GPT). Ask o “no edites”. Paths, qué no tocar, tests, riesgo de capas. Máximo 6 pasos.
2. Chat B nuevo: rápido (Composer / Grok). Pegá el plan. “No lo mejores. No agregues archivos que el plan no nombra.”
3. AGENTS.md: mapa y prohibiciones ya mergeados (valen en ambos chats). El plan no vive en el MD; caduca con el ticket.

Prompt

Los dos bloques: prompts-base T8.

DoD

Plan con paths, sin snippets masivos. Lista de files del Chat B = lista del plan. Tests del plan corridos. Review humano (R6 / J5 si el diff lo escribió el agente).

Ver más: #vd-fast-vs-think · #flujo-dia-0.

Host, timeout o un envío de prueba. El mailer ya existe.

Contexto

El servicio Java ya manda notificaciones (JavaMail, Spring Mail, o un cliente SMTP del módulo mail). El ticket es ops: timeout, From, o un envío de prueba desde el mismo entry point que el equipo ya usa en no-prod (un main de herramienta, un job, un perfil dev). No es “plataforma de mail”. No hay nombres de cliente ni de un banco en el prompt.

Pasos

1. Chat: path del mailer actual + qué cambia (propiedad, timeout, comando de prueba). “No inventes un microservicio de correo.”
2. Modelo: rápido para el parche. pensar solo si el agente propone broker o segundo Boot.
3. AGENTS.md: un deploy; secretos por variable de entorno, no en código; no loguear destinatarios ni el cuerpo; no tocar prod; el test de envío usa el mecanismo que el módulo ya tiene.

Prompt

Cambio SMTP en el mailer que YA existe. No un producto de correo.

Path: [paquete mail / MailSender / application-*.yml del perfil no-prod].
Cambio: [timeout / From / comando de prueba en el entry point que ya usa el equipo].
Prohibido: segundo Boot, Kafka "de mail", librería nueva, hardcodear host/password,
loguear destinatario o cuerpo, tocar prod, inventar nombres de cliente.
Secretos: solo env vars que el módulo ya lea.
DoD: el envío de prueba usa el mismo cliente; diff en el paquete mail + config;
sin commit. Si hace falta un dato de host, preguntá; no lo inventes.

DoD

La propiedad o el comando de prueba está en el módulo mail existente. Cero secretos en Git. Logs sin destinatario ni cuerpo. Sin push a prod. El equipo corre la prueba en el entorno que ya usa para eso.

Ver más: capas y un deploy en #tr-java-legacy · Git/secretos #equipo.

Un campo o un diálogo. El NgModule (o la carpeta) ya existe.

Contexto

Front Angular en producción. Ticket: un campo más en la lista de pedidos, o un diálogo de confirmación en la pantalla que ya lista. El módulo pedidos (o la carpeta feature del disco) ya tiene componente, servicio y rutas. No hay ticket de standalone, de signals en todo el árbol, ni de un segundo SPA.

Pasos

1. Chat: nombrá el componente y el servicio vecinos. “Mismo módulo. No crees otro.”
2. Modelo: rápido si el vecino es obvio. pensar (T3) si propone HttpClient en el .ts de la plantilla o un módulo nuevo.
3. AGENTS.md: componente flaco; HTTP en servicio/fachada, no en el componente; “no módulo Angular nuevo si el disco no lo tiene”; no mezclar React.

Prompt

Plantilla completa: prompts-base A1. Si duda el patrón: T3. Corto:

Cambio Angular en el módulo que YA existe. No reescribas el front.

Módulo / carpeta: [src/app/pedidos/ o el path del disco].
Vecino a copiar: [pedidos-list.component.ts / pedidos.service.ts].
Ticket: [campo en la fila / diálogo al confirmar].
El componente no usa HttpClient; pasa por el servicio/fachada que ya lista.
No módulo nuevo, no tree features/ si el disco no lo tiene, no React, no librería.
Listá archivos (máximo los del módulo) y esperá OK de una línea.

DoD

El diff vive en el módulo existente. Cero HttpClient en el componente. Cero módulo o librería nueva. El campo o el diálogo se ve en el flujo que ya está.

Ver más: L4 (vecino) · #arquitectura · A1 / T3.

Un campo o un diálogo. MVVM (o el que ya está) se queda.

Contexto

App Android nativa. Ticket chico: un campo más en la fila, o un diálogo al confirmar. El paquete ya tiene pantalla + ViewModel + repositorio. El riesgo no es Kotlin: es que el agente migre a Compose Navigation, meta lógica en la Activity, o reescriba XML a Compose “de paso”.

Pasos

1. Chat: nombrá el ViewModel vecino. “Misma capa. No Navigation nuevo.”
2. Modelo: rápido si el vecino es obvio. pensar (T3) si duda entre Activity gorda y ViewModel.
3. AGENTS.md: ViewModel sin Views; HTTP en repositorio/capa de datos; “no Compose Navigation / no librería si el disco no lo tiene”.

Prompt

Plantilla completa: prompts-base D1. Si reescribe el toolkit: D2. T3 solo si duda el patrón. Corto:

Cambio Android en el paquete que YA existe. No reescribas la arquitectura.

Paquete: [ui.orders / data.orders o el path del disco].
Vecino: [OrderListViewModel].
Ticket: [campo en la fila / diálogo al confirmar].
El ViewModel no importa Activity/Fragment; el diálogo lo muestra la vista.
HTTP en el repositorio, no en la Activity.
No Navigation Component nuevo, no migrar XML→Compose, no librería.
Listá archivos (máximo los del paquete) y esperá OK de una línea.

DoD

El diff se lee al lado del vecino. Cero librerías nuevas. Cero rewrite de UI toolkit. El diálogo o el campo se puede demo en el flujo existente.

Ver más: L4 · #arquitectura (MVVM) · D1 / D2.

El efecto se dispara en círculo, o el click ve el filtro de hace tres renders.

Contexto

Lista de pedidos en producción. OrderList ya existe. Al montar (o al cambiar un filtro) el useEffect vuelve a pedir la lista en loop: depende de un objeto/array creado en cada render, o el setState del efecto entra en las deps. Variante: el botón “Reintentar” usa un handler que cierra sobre el filtro viejo. No hay ticket de React Query, de extraer un hook genérico ni de rediseñar el estado.

Pasos

1. Chat: nuevo. Un síntoma (loop o dato viejo). Nombrá el componente y, si lo viste, el efecto. No el hilo del filtro de ayer.
2. Modelo: rápido. pensar solo si el estado vive en tres padres y hay que elegir dueño — igual no inventes store.
3. AGENTS.md: mapa src/pages/, src/components/, src/api/; “solo lo que el ticket nombra”; no store; HTTP sigue en el cliente que ya usa la lista.

Prompt

Plantilla completa: prompts-base R7. Corto:

Bug de efecto. No rediseñes. No React Query.

Síntoma: [OrderList refetch en loop / Reintentar usa el filtro viejo].
Componente: [src/pages/OrderList.tsx]. Cliente HTTP: el que YA usa la lista.
Arreglá deps, identidad del objeto, o leé el filtro actual. Sin store nuevo.
Tocá ese archivo y el spec si existe. Sin login ni hook genérico.

DoD

Un cambio de filtro dispara un fetch (o el que el vecino ya haga). “Reintentar” usa el filtro actual. Mismo componente, mismo cliente. Spec tocado si existía. Sin commit.

Ver más: L1 · #tr-react-bug · R7.

Un input más. Misma validación, mismo submit. No hay ticket de login.

Contexto

ContactForm (o el alta de pedido) ya está en producción: campos, validación local, submit al cliente HTTP que ya existe. Ticket: agregar phone o notes, mismo patrón que el campo vecino. El contrato del POST ya acepta esa clave, o el ticket dice que el back ya puede. Nadie pidió auth, React Hook Form, ni un wizard de tres pasos.

Pasos

1. Chat: nombrá el form y el campo vecino a copiar. “No inventes login.”
2. Modelo: rápido si el vecino es obvio. pensar si el agente propone otra lib de forms o un store.
3. AGENTS.md: UI no pega URLs; HTTP en src/api/; “solo lo que el ticket nombra”; no auth ni admin.

Prompt

Plantilla completa: prompts-base R8. Corto:

Campo extra en el form que YA existe. No reescribas el form.

Form: [src/components/ContactForm.tsx]. Campo nuevo: [phone / notes].
Copiá validación y markup del campo vecino [email / dueDate].
Mismo submit, mismo cliente HTTP. Sin login, sin React Hook Form,
sin wizard. Spec del form si existe: un caso del campo nuevo.

DoD

El campo se ve, valida como el vecino y viaja en el mismo submit. Diff en el form + cliente si hace falta la clave + spec si existía. Cero auth. Sin commit.

Ver más: L1 · R8 · ficha react-bug-acotado.md.

Un badge o una prop. La class se queda class.

Contexto

UserCard o FilterPanel es un class component de hace años. Ticket: un badge de estado, un texto, una prop más. El agente “aprovecha” y lo pasa a función + hooks, o reescribe componentDidMount a tres useEffect. El backlog no pide migración. Los tests del class, si hay, usan el API viejo.

Pasos

1. Chat: “es una class. Dejala class. Solo el badge/prop.” Si ya empezó la migración, chat nuevo, no negociar el rewrite.
2. Modelo: rápido para el parche. pensar (review) si el PR ya convirtió el archivo.
3. AGENTS.md: “no convertir class→función ni XML de UI de paso”; mapa de carpetas; solo lo que el ticket nombra.

Prompt

Plantilla completa: prompts-base R9. Corto:

Cambio en una class que YA existe. No la pases a hooks.

Archivo: [src/components/UserCard.jsx]. Ticket: [badge de estado / una prop].
Dejá class, lifecycle y this.state. No useEffect, no extraer hooks.
Si el spec monta la class, extendelo; no lo reescribas a Testing Library "moderna".

DoD

El badge o la prop se ve. El archivo sigue siendo class. Cero useState/useEffect nuevos en ese componente. Spec extendido, no reescrito. Sin commit.

Ver más: L3 (no partir) · R9 · react-arquitectura.md.

El tema, el carrito o el filtro ya tienen dueño. No un store “de verdad”.

Contexto

El front ya guarda tema (o carrito, o filtros de la lista) en React.createContext, o la página usa useState en el padre. Ticket chico: un toggle, un chip, un valor más. El agente instala Zustand o Redux Toolkit “porque el Context no escala”. Nadie pidió store global ni una carpeta src/store/.

Pasos

1. Chat: nombrá el Context o el state del padre. “Extendé eso. No instales store.”
2. Modelo: rápido. pensar solo para decir “no hace falta Redux” si el PR ya lo metió.
3. AGENTS.md: “no Redux/Zustand/Jotai si el disco no los tiene”; estado en el Context o el padre que ya existe.

Prompt

Plantilla completa: prompts-base R10. Corto:

Estado que YA existe. No instales store.

Dueño actual: [ThemeContext / el useState de OrderList].
Ticket: [toggle dark / un filtro más].
Extendé ese Context o ese state. Prohibido zustand, redux, jotai,
src/store/, providers nuevos. Sin login.

DoD

El cambio usa el Context o el useState existente. package.json sin store nuevo. Cero src/store/. Sin commit.

Ver más: L1 · R10 · R4.

Copiá la ruta hermana. No migres el router de paso.

Contexto

SPA con React Router ya cableado: o <Routes>/<Route> en App.tsx, o createBrowserRouter en un archivo de rutas. Ticket: pantalla de detalle /orders/:id (o el path del equipo). Ya hay una lista en /orders y un vecino de detalle en otro recurso. Nadie pidió data APIs, loaders, ni pasar de v5 a v6 (ni al revés).

Pasos

1. Chat: nombrá el archivo de rutas y la ruta vecina a copiar. “Mismo helper, mismo layout.”
2. Modelo: rápido si el vecino es obvio. pensar si propone createBrowserRouter en un repo que usa Routes.
3. AGENTS.md: “rutas donde el disco ya las declara”; no Next app/; HTTP en src/api/, no en el loader si el equipo no usa loaders.

Prompt

Plantilla completa: prompts-base R11. Corto:

Ruta nueva, mismo patrón que las que YA hay. No migres el router.

Archivo de rutas: [src/App.tsx o src/routes.tsx].
Vecina a copiar: [/orders → OrderList / /customers/:id].
Nueva: [/orders/:id → OrderDetail]. Página en [src/pages/], HTTP en [src/api/].
No createBrowserRouter si el disco usa Routes (ni al revés).
No loaders, no Next app/, no auth. Listá files y esperá OK.

DoD

La URL nueva abre la página del mapa. Misma API de Router que el resto. Cero loaders/data APIs si el disco no los tiene. HTTP en src/api/. Sin commit.

Ver más: L4 · R11 · NR2.