AI-DLC en brownfield: ingeniería inversa, contexto de 1M y la regla del 75%

Un proyecto greenfield no tiene nada que el agente pueda malinterpretar. Un proyecto brownfield tiene años de decisiones que el agente nunca vio. La gestión de contexto es cómo mantienes esas decisiones dentro de la ventana el tiempo suficiente para que importen.

La mayoría de las demos de AI-DLC empiezan desde una carpeta vacía. El tutorial oficial de AWS construye un acertijo de cruzar el río, y lo primero que hace el workflow es detectar que el proyecto es greenfield y saltarse la ingeniería inversa, porque no hay nada que revertir. Queda una demo limpia. No es el trabajo que tenemos la mayoría.

El trabajo que tenemos la mayoría es un servicio que lleva cuatro años en producción, con decisiones que nadie escribió, una suite de pruebas que cubre una parte y un servicio vecino con el que habla por un contrato que vive en la cabeza de alguien. Eso es brownfield, y ahí es donde AI-DLC justifica su ceremonia o la desperdicia.

En los pilotos que seguí dentro de una gran organización de ingeniería, dos cosas decidieron si el brownfield funcionaba. Cómo corría el equipo la ingeniería inversa, y cómo trataba la context window. Ninguna de las dos es un problema de herramienta. Las dos son hábitos, y las dos tienen reglas que se pueden escribir.

La ingeniería inversa es donde el agente conoce tu código

Cuando arrancas un workflow de AI-DLC 2, la fase de Initialization detecta el workspace. Si encuentra código existente, la Inception abre con la etapa 2.1, Reverse Engineering, antes de que el agente pueda hacerte una sola pregunta de requisitos.

La razón es simple. Un modelo que no leyó tu código igual va a proponer cambios sobre él. Va a inventar un patrón que no usas, duplicar un helper que ya tienes y romper un contrato implícito entre dos módulos porque nada le dijo que el contrato existía. El whitepaper original puso la solución en una línea: en brownfield, primero eleva el código a un modelo semántico, uno estático (los componentes y sus relaciones) y uno dinámico (cómo interactúan en los casos de uso que importan), para que el contexto desde el que trabaja la IA sea conciso y preciso.

Piensa en la primera semana de una persona senior recién contratada. No le das un ticket el primer día. La dejas leer el código, dibujar las cajas y preguntar por qué el módulo de pagos habla con el ledger a través de una cola. La ingeniería inversa es esa semana, comprimida en una etapa, con el dibujo guardado en un archivo.

AI-DLC 2 corre esta etapa como un pipeline de dos eslabones. Un agente de desarrollo recorre el código. Un agente de arquitectura lee ese recorrido y escribe la síntesis. Después tú la apruebas, como cualquier otra etapa.

Cómo abre AI-DLC 2 un workflow brownfield

Entrada

Corres /aidlc en un repositorio que ya tiene código

↓

1. 0.2Workspace Detection lo marca como brownfield

   Un escaneo basado en reglas de extensiones de archivo, manifiestos y archivos de configuración conocidos. Sin llamada al modelo, sin gate.

   ↓
2. 2.1aEl agente de desarrollo recorre el código

   Módulos, puntos de entrada, cómo se hablan las piezas entre sí, el stack y sus versiones.

   ↓
3. 2.1bEl agente de arquitectura escribe la síntesis

   Los artefactos de la ingeniería inversa quedan en la carpeta de registro de la intent, donde toda etapa posterior puede leerlos.

   ↓
4. GATEApruebas el retrato de tu propio sistema

   Si el agente leyó mal la arquitectura aquí, cada requisito, diseño y Unit posterior hereda el error.

↓

Salida

Preguntas de requisitos que parten de cómo funciona de verdad tu código, no de cómo funcionaría una codebase promedio.

Ese gate es el más subestimado del ciclo de vida. La gente lo lee por encima porque describe código que ya conoce, y justo por eso merece una lectura de verdad: es el único lugar para contrastar el modelo que el agente hizo de tu sistema con el tuyo, antes de que se construya nada encima.

Acótala a la feature, no al repositorio

El movimiento ingenuo es apuntar la ingeniería inversa al repositorio entero. Más contexto suena más seguro. No lo es.

Cada token de la salida de la ingeniería inversa compite por la misma ventana con los requisitos, el diseño y, más adelante, el código. Un mapa completo de un servicio grande quema una buena parte de esa ventana en módulos que la feature nunca va a tocar. Y cuanto más material irrelevante hay en el contexto, más chances tiene el modelo de meter la pieza equivocada en su respuesta. Uno de los ingenieros que mantenía el setup en el rollout lo dijo sin vueltas: más información es más chance de alucinar.

Lo que funcionó fue la ingeniería inversa enfocada. El agente mapea los módulos que la feature va a usar, las fronteras que va a cruzar y los contratos de los que va a depender. El resto lo deja quieto. Pierdes un documento de arquitectura completo. Ganas una ventana con espacio libre para el trabajo.

Córrela antes del mob, no durante

En un repositorio chico, la ingeniería inversa tomó unos veinte minutos. En uno grande, más. Veinte minutos no es nada para un ingeniero. Es mucho para seis personas sentadas en una sesión de Mob Elaboration mirando un indicador de progreso.

El patrón en el que se asentaron los equipos: quien conduce la sesión instala el workflow, lo arranca y deja que la ingeniería inversa termine antes de la reunión. El equipo se suma cuando la síntesis está aprobada y las preguntas de requisitos están listas para responder. El tiempo sincrónico va a decisiones, que es lo único para lo que sirve el tiempo sincrónico.

Una feature, varios repositorios

Las features reales casi nunca viven en un solo repositorio. Un cambio toca la API, el front-end, quizás un cliente mobile y un servicio de otro equipo.

La primera versión de AI-DLC era de un solo repositorio. Los equipos lo resolvían dividiendo el trabajo por stack: una sesión para el back-end, otra para el front-end, con el contrato entre los dos acordado antes de que cualquiera empezara. Cuando el back-end necesitaba entender qué esperaba el front-end, agregaban la carpeta del front-end como un directorio extra de solo lectura en el contexto del agente, para que la ingeniería inversa pudiera ver el mock o el código del cliente sin ser su dueña.

AI-DLC 2 convirtió el trabajo con varios repositorios en una idea de primera clase. Una intent puede registrar el conjunto de repositorios que abarca, de forma explícita o descubriendo repositorios hermanos en el workspace. La ingeniería inversa corre entonces una cadena completa de escaneo y síntesis por repositorio antes de tu aprobación, y Construction ancla cada operación de git al repositorio correcto. También hay una etapa de Contract Design en la Inception para las interfaces entre Units.

Nada de eso quita la parte difícil. Dos repositorios de dos equipos siguen necesitando un contrato que aprueben los dos lados. El motor puede mapear las dos codebases. No puede hacer que el otro equipo esté de acuerdo contigo.

Presupuesta la ventana como memoria, porque lo es

La context window es la memoria de trabajo del agente, y una Inception de AI-DLC la usa mucho. El agente lee cada requisito que le das, la salida de la ingeniería inversa, sus propias preguntas y tus respuestas, y los documentos que genera en el camino.

En el rollout, una Inception completa sobre un servicio real quedó en algún punto entre 500.000 y 600.000 tokens. Eso entra en una ventana de un modelo de un millón de tokens y no entra en una más chica sin que el harness compacte la conversación en el camino. Construction es lo opuesto: cada Unit tiene su propia spec, así que el contexto que necesita cada Unit es chico.

A dónde se va la ventana

La ventana grande es para la fase que más lee. Pagarla durante Construction no te compra nada.

Momento	Qué llena el contexto	Qué funcionó
Inception	Ingeniería inversa, requisitos, preguntas y respuestas, documentos de diseño.	Correrla en una sola ventana, en un modelo de 1M de tokens. Revisar el uso antes de empezar.
Construction, por Unit	La spec de la Unit, el código que toca, las pruebas.	Limpiar entre Units. Un modelo más chico y más barato muchas veces alcanza.
Una conversación larga de discovery	Idas y vueltas, correcciones, direcciones abandonadas.	Escribir las conclusiones en un archivo y empezar limpio. No seguir conversando.

En Claude Code ves qué tan llena está la ventana con /context. Mira antes de empezar una Inception. Darte cuenta al 70% de que estás en la ventana chica es una tarde perdida.

La regla del 75%

Esta es la heurística a la que llegaron los equipos: cuando la ventana pasa de unas tres cuartas partes, la calidad cae. El agente empieza a repetirte tus propias respuestas, pierde el hilo de decisiones tomadas una hora antes e inventa detalles con el mismo tono seguro que usaba cuando tenía razón.

No es una ley, y el número exacto cambia con el modelo. El mecanismo detrás está bien documentado. Los modelos prestan más atención al principio y al final de su contexto y leen por encima el medio, así que la decisión que tomaste en el medio de una sesión larga es la que tiene más chances de perderse. Quienes trabajan con esto llaman context rot a ese deterioro lento. Un ingeniero de uno de los squads del piloto dio la versión práctica: alrededor del medio millón de tokens, limpia y retoma desde el archivo de estado, porque eso es mejor que ver al agente empezar a alucinar.

Limpia en los gates, nunca en medio de una fase

Limpiar el contexto no es rendirse con la tarea. Es tirar el ruido de la sesión: los desvíos, las correcciones, los borradores intermedios que ya nadie necesita. El trabajo vive en archivos. La sesión siempre fue descartable.

La regla es sobre cuándo. Limpia en un checkpoint: después de que se aprueba la ingeniería inversa, después de que se aprueban los requisitos, entre Units de Construction. Nunca en medio de una fase que todavía está produciendo su artefacto, porque entonces el razonamiento a medias no queda guardado en ningún lado.

AI-DLC mantiene un archivo de estado por intent, aidlc-state.md, con la fase actual, la etapa y el estado de cada etapa. En AI-DLC 2 vive en la carpeta de registro de la intent, junto a un log de auditoría de solo agregado, y un hook escribe un punto de recuperación antes de que el harness compacte. Eso es lo que hace segura la limpieza. Una sesión nueva lee el estado y sigue donde se quedó la anterior.

Cómo limpiar sin perder trabajo

1. 01

   Haz commit y push antes de limpiar.

   Los artefactos son la memoria. Si no están commiteados, limpiar borra la única copia del razonamiento que los produjo.

   Escribe esto

   Commit the approved artifacts for this stage with a message that names the stage, then push.

2. 02

   Limpia solo en un gate.

   Un gate significa que el artefacto está terminado y aprobado. Lo que esté en curso termina antes.

   Escribe esto

   /clear

3. 03

   Retoma desde el archivo de estado, no desde tu memoria de la sesión.

   El archivo de estado sabe la fase, la etapa y lo que está hecho. Tú recuerdas lo que te pareció importante.

   Escribe esto

   /aidlc --status

4. 04

   Antes de limpiar una sesión trabada, haz que el agente escriba lo que aprendió.

   Una sesión de debugging que no llegó a ningún lado igual descartó hipótesis. Guarda eso, tira el ruido, y la sesión nueva arranca con la misma profundidad y nada de la confusión.

   Escribe esto

   Do not change any code. Write a summary of this issue to notes/issue-summary.md: what we tried, what we ruled out, and what we still suspect.

La compactación rompe tus reglas en silencio

Cuando la ventana se llena y no la limpias, el harness hace algo por ti. Compacta: reemplaza la conversación anterior por un resumen para que la sesión pueda seguir. Suena inofensivo. No lo es.

Un resumen está optimizado para continuar la tarea. Conserva lo que parece central y descarta lo que parece periférico. Y una restricción que dijiste una vez, al principio de la sesión (“no toques el módulo de facturación”, “nunca borres una migration”), parece periférica hasta el momento en que el agente la viola.

Esto dejó de ser una corazonada. Dos papers de 2026 lo midieron.

Qué le hace la compactación a las restricciones

0% a 30%

violaciones de restriccionesantes y después de compactar, en siete familias de modelos

59%

peor casotasa de violación en algunos modelos

17%

restricciones conservadasen promedio, por los compactadores actuales

El estudio Governance Decay corrió 1.323 episodios de agentes en siete familias de modelos. Con la política completa en el contexto, los agentes la violaron el 0% de las veces. Después de la compactación, el 30%, y el 59% en algunos modelos. Cuando la restricción sobrevivía al resumen, las violaciones se quedaban en cero. Cuando el resumen la descartaba, se disparaban. Los autores proponen fijar las restricciones de gobernanza fuera del resumen con pérdida, lo que devolvió las violaciones a cero en su benchmark.

El estudio Lost in Compaction miró las instrucciones que los usuarios dan para el resto de la sesión, como “no borres ningún correo hasta que yo confirme”. Los compactadores actuales conservaron en promedio el 17% de ellas, y la mayoría lo hizo peor que no compactar nada. Un extractor que saca esas restricciones antes de la compactación conservó más del 90%.

La lección práctica para el trabajo en brownfield es corta. Una regla que escribiste en el chat vive dentro de la conversación que se va a resumir. Una regla en un archivo que el harness carga por su cuenta, tu AGENTS.md o CLAUDE.md, o los archivos de reglas que AI-DLC 2 guarda en la memoria del espacio, vive fuera de ella. Pon en un archivo toda restricción que importe. La guía de AGENTS.md cubre qué va ahí.

Una ventana más grande trata el síntoma

Cuando un agente empieza a repetirse en una sesión larga, el reflejo es cambiar a un modelo con una ventana más grande. Una persona de producto en el rollout hizo exactamente eso durante un discovery largo: el agente se rompió, empezó a devolver como eco las respuestas que recibía, y un modelo más grande lo arregló.

Arregló el síntoma. La causa era una sesión que seguía acumulando contexto que debía haberse escrito y descartado. Una ventana más grande te deja acumular por más tiempo antes de la misma falla. No la evita, y cuesta más por turno mientras la esperas.

La cura es la que el método ya tiene. Toda etapa de AI-DLC guarda su artefacto en un archivo, y la etapa siguiente lee el archivo en lugar de la conversación. Dentro de una etapa, haz lo mismo a mano: cuando un hilo de discusión llega a una conclusión, escribe la conclusión y empieza limpio. Eso es context engineering aplicado a un ciclo de vida. El chat es papel borrador. Los archivos son la memoria. Si algo que la próxima sesión necesita solo existe en la conversación, está a una compactación de desaparecer.

¿Tu repo brownfield está listo para AI-DLC?

Preparación para brownfield

• ✓Obligatorio:
  El repo tiene un AGENTS.md o CLAUDE.md corto con el stack, los patrones, las librerías prohibidas y por qué, y un ejemplo de cada patrón.Cada hueco aquí se vuelve una pregunta que el agente hace durante la Inception o, peor, una suposición que hace sin preguntar.
• ✓Obligatorio:
  La ingeniería inversa está acotada a los módulos que toca la feature.Un mapa completo del repo gasta la ventana en código que la feature nunca va a llamar.
• ✓Obligatorio:
  La ingeniería inversa corre antes del mob, no durante.El equipo se suma cuando la síntesis está aprobada y las preguntas están listas.
• ✓Obligatorio:
  Los contratos entre repositorios se acuerdan antes de que empiecen las sesiones.AI-DLC 2 puede escanear varios repositorios en una intent. No puede negociar con el equipo dueño del otro.
• ✓Obligatorio:
  La Inception corre en un modelo de 1M de tokens, y alguien revisa la ventana antes de empezar.Entérate de que estás en la ventana chica al principio, no al 70%.
• ✓Obligatorio:
  El equipo limpia en los gates, alrededor de tres cuartos de la ventana, después de commit y push.Nunca en medio de una fase. Retoma desde el archivo de estado.
• ✓Obligatorio:
  Toda restricción que importa vive en un archivo, no solo en el chat.La compactación conserva una fracción de lo que dijiste. No toca lo que está en disco.

Preguntas frecuentes

¿Qué es context rot?+

La caída gradual de calidad de un agente de IA a medida que se llena su context window. El modelo presta más atención al principio y al final de su contexto, así que los detalles del medio de una sesión larga se pierden, y el agente empieza a repetirse o a contradecir decisiones anteriores.

En la práctica, se hace visible en algún punto después de tres cuartos de la ventana. La solución es sacar las decisiones a archivos y limpiar el contexto en checkpoints naturales.

¿Qué es la compactación de contexto, y por qué es un riesgo?+

La compactación es lo que hace un harness cuando la ventana se llena: reemplaza la conversación anterior por un resumen para que la sesión pueda seguir. El resumen conserva lo que parece central y descarta el resto.

El riesgo es que las restricciones que dijiste una vez parecen periféricas. Un estudio de 2026 midió las violaciones de restricciones pasando del 0% al 30% después de compactar, y hasta el 59% en algunos modelos. Guarda las reglas importantes en archivos que el harness cargue por su cuenta.

¿AI-DLC funciona con código legado?+

Sí, y fue diseñado para eso. En proyectos brownfield la Inception empieza con una etapa de Reverse Engineering que modela el código existente antes de proponer cualquier cambio. La calidad de esa etapa, y del AGENTS.md o CLAUDE.md que ya tiene el repo, decide cuánto tiene que adivinar el agente.

¿AI-DLC 2 soporta varios repositorios?+

Sí. Una intent de AI-DLC 2 puede registrar los repositorios que abarca, de forma explícita o descubriendo repositorios hermanos en el workspace. Reverse Engineering corre una cadena completa por repositorio, y Construction ancla las operaciones de git a cada repositorio. La primera versión era de un solo repositorio.

¿Qué tamaño de context window necesito para AI-DLC?+

Para la Inception sobre un servicio real, planea una ventana de un millón de tokens. La Inception completa en el rollout que seguí quedó entre 500.000 y 600.000 tokens. Las Units de Construction necesitan mucho menos, así que ahí un modelo más chico y más barato suele funcionar.

¿Uso /compact o /clear?+

En un workflow de AI-DLC, prefiere /clear en un gate, después de commitear los artefactos aprobados, y retoma desde el archivo de estado. La compactación resume la sesión y puede descartar restricciones en silencio. Limpiar tira el ruido y conserva el trabajo, porque el trabajo ya está en archivos.

A dónde ir ahora

Brownfield es donde AI-DLC se paga o quema dinero, y la diferencia es casi toda higiene. Mapea solo lo que toca la feature, mapéalo antes de la reunión, dale la ventana grande a la Inception, limpia en los gates y deja en disco toda regla que importe. El agente no necesita recordar tu sistema. Necesita poder leerlo de nuevo.