Argui

Brownfield — Argui sobre un proyecto que ya existe

El workflow describe un proyecto que nace de cero (greenfield). La mayoría de los equipos no arrancan de cero: tienen un producto en producción y quieren agregarle trabajo nuevo sin reescribirlo. Ese es el caso brownfield.

Brownfield no es un proceso distinto ni una fase nueva — es la misma metodología, con el mismo vocabulario. Es una puesta al día que se hace una vez —recuperar el mínimo de base que el ciclo normal necesita— y, a partir de ahí, cada trabajo nuevo re-entra por la Fase 6 (evolución continua). Un producto que ya existe está, por definición, en evolución continua; lo único que falta es la base sobre la que esa fase opera.

Dos situaciones de partida

Lo que determina cuánto cuesta la puesta al día no es el tamaño del código, sino qué artefactos de la metodología ya existen:

Situación de partida Qué falta Puesta al día
No nació con Argui — legacy, otro proceso, o construido con IA sin estructura Casi todo: no hay specs, ni estándares explícitos, ni agentes, ni red de seguridad Onboarding completo (este documento)
Nació con Argui, versión anterior Los artefactos existen pero están desfasados respecto a la versión actual de la metodología Puesta al día de versión (delta — sección abajo)

Las dos terminan en el mismo lugar: el proyecto al día, re-entrando a la Fase 6. Lo que cambia es la profundidad.

Principio rector: adopción incremental

No se reacondiciona el producto entero antes de empezar. Se recupera el mínimo y el resto crece al tocarlo: las specs nacen cuando se modifica un módulo, el design system se consolida con la primera interfaz de usuario (UI) nueva, los tests de caracterización cubren primero los flujos que el trabajo nuevo va a tocar. Recuperar base que no se va a usar todavía es inversión muerta.

Esto separa lo que se hace una sola vez de lo que es continuo:

  • Una vez (el onboarding): montar la maquinaria (aislamiento, OpenSpec, agentes, red de seguridad) y recuperar los baselines del producto más las zonas de las primeras features.
  • Continuo (la Fase 6): la arqueología y las specs no se “terminan” en el onboarding —siguen creciendo, una zona a la vez, cada vez que el trabajo nuevo toca un módulo aún no recuperado—. Eso no es repetir el onboarding (la maquinaria ya está): es el principio incremental en acción.

Así la puesta al día es proporcional: extender con una feature pequeña pide muy poca recuperación; rescatar un código heredado y caótico pide mucha. La forma es la misma; la profundidad escala.

Las tres capas: negocio, técnica, comportamiento

Argui organiza la definición del producto en tres capas, iguales en greenfield y brownfield:

Capa Qué contiene Greenfield: nace Brownfield: nace
PRD de negocio Por qué / para quién / valor / alcance Diseñado (Fase 2) Recuperado — brief de producto (onboarding)
PRD técnico Stack, arquitectura, estructura, modelo de datos, decisiones transversales Diseñado (Fase 2) Recuperado — arquitectura as-built (onboarding)
Specs Contrato de comportamiento por capacidad Con cada item Se completa al tocar (estrategia de specs)

Las tres son vivas y crecen con el producto. La única diferencia brownfield está en cómo nacen: en greenfield los PRDs (Product Requirements Document, documento de requisitos del producto) se diseñan completos para el Producto Mínimo Viable (PMV) y se validan con prototipo; en brownfield se recuperan incompletos en el onboarding y crecen al tocar/agregar. El comportamiento profundo siempre vive en las specs, no en los PRDs — en las dos modalidades.

El PRD técnico: un mapa vivo

En brownfield el PRD técnico nace como as-built: la descripción de lo que el sistema ya es. De ahí en adelante se mantiene como cualquier PRD técnico vivo:

  • Es un mapa. Se corrige para seguir siendo verdad cuando el sistema cambia o cuando se aprende algo nuevo. Siempre es un snapshot actual — el historial vive en git.
  • Lo profundo va a las specs. El comportamiento detallado de un módulo, cuando se recupera, vive en su spec; el PRD técnico solo gana correcciones estructurales (una relación descubierta, el estado de una zona de riesgo).
  • Se divide por área si crece. Si hasta el mapa pesa demasiado, se parte en varios archivos, como cualquier artefacto de Argui.

Cómo se garantiza que cambie bien —sin mecanismo nuevo, reusando lo que ya existe—:

  • Definition of Done (DoD): todo cambio que el gate de impacto arquitectónico marque arquitectónico actualiza el PRD técnico como parte de su DoD —igual que la DoD del prototipo obliga a tocar PRD, design system y specs juntos—. Sin esa actualización, el change no está terminado.
  • Auditoría: la auditoría periódica specs↔código (operations.md) verifica que el PRD técnico refleje la arquitectura real.
  • Dueño: la corrección estructural es juicio del arquitecto; el agente PRD mantiene el de negocio.

El onboarding paso a paso

Para un proyecto que no nació con Argui. Cada paso reusa la maquinaria de una fase que ya existe; la diferencia de fondo con greenfield es que aquí se extrae y audita lo que ya existe, en vez de inventarlo y diseñarlo. Cada paso es una unidad de trabajo —su propia sesión, con limpieza de contexto al cerrarla (operations.md)—; van en este orden, cada uno alimenta al siguiente.

Aislar la herramienta de IA

Como en la Fase 0: confinar el asistente al repositorio antes de tocar nada. Ver operations.md → Aislamiento del entorno de IA y templates/aislamiento/. El asistente va a leer mucho código ajeno; no debe poder salirse del proyecto mientras lo hace.

Inicializar OpenSpec y decidir la estrategia de specs

Inicializar OpenSpec con la versión fijada (nunca @latest). La personalización del schema (verify + qa) se arma al llegar al ciclo, igual que en la Fase 4 del workflow.

El comportamiento existente no tiene specs, y completar las specs del producto entero rara vez compensa. Se elige una estrategia y se registra como política en el CLAUDE.md:

Estrategia Cuándo Costo
Lazy / al tocar (default) La mayoría de los casos Bajo — la spec nace solo para lo que se modifica
Solo críticos Flujos sensibles (pagos, autenticación) que no se van a tocar pronto pero conviene documentar por su riesgo Medio
Sin specs Cambios muy aislados, sin intención de evolucionar el módulo Mínimo
Completo Rara vez; rescate que va a reescribir casi todo Alto

La estrategia lazy documenta solo lo que se toca: un flujo crítico que nadie toca se queda sin contrato escrito y su blast-radius se evalúa a ciegas. Por eso, en productos de alto riesgo o regulados, se prefiere “solo críticos” aunque no se vayan a tocar pronto. Subir de estrategia (lazy → críticos → completo) es completar más specs como items de backlog; es aditivo y se registra en decisiones.md.

Entender el producto y su negocio

El equivalente brownfield de entender el problema (en greenfield, la Fase 1): acá el producto ya existe, pero su razón de negocio no está en el código —vive en las personas y en el uso—. Se hace conversacional, como esa fase. El agente PRD todavía no existe (se crea más adelante), así que el brief inicial lo levanta la sesión principal en conversación, apoyándose en /opsx:explore si hace falta. Tres fuentes:

  • Quien conoce el producto: el cliente, si es un producto de cliente; o el dueño de producto / el propio equipo, si se adopta la metodología sobre algo propio. De ahí salen qué problema resuelve, para quién, el modelo de negocio y las restricciones.
  • Usar el propio producto: lo que ya hace, visto desde el usuario.
  • initial-references/: la carpeta donde se deja el material que aporte el negocio —documentos, notas, manual de marca, métricas, requerimientos previos—. Misma convención que en la Fase 1: va en .gitignore por defecto (suele ser confidencial); solo se versiona si se confirma que no hay nada sensible.

El resultado es el PRD de negocio inicial —un brief de producto liviano, no un PRD completo reconstruido por ingeniería inversa (el producto ya existe; no se valida que deba existir)—, con confirmación humana ligera ✋. Es la semilla del PRD de negocio; lo mantiene de aquí en adelante el agente PRD —el mismo que lleva los dos PRDs, creado en Crear los demás agentes— y crece en la Fase 6.

Crear el arquitecto

En greenfield el arquitecto diseña y se crea sobre los PRDs (F4.2 del workflow). En brownfield se crea primero y su identidad es otra: ingeniería inversa y auditoría de un sistema que ya existe, no diseño desde cero. Es la única perspectiva que se convoca antes que los estándares, porque no implementa —no fija patrones de código— sino que entiende y juzga.

  1. Escaneo rápido de stack: leer los manifiestos (package.json, requirements.txt, pom.xml, Gemfile…), el README y la estructura de carpetas. Suficiente para saber lenguajes, frameworks, base de datos e infra.
  2. Escribir el agente arquitecto (agents.md, modelo opus) anclado a ese stack. Su Expertise: “arquitecto senior que hereda y audita sistemas en [stack]; su trabajo es entender por qué el código es como es y señalar riesgos, no rediseñarlo.”

Recuperar la arquitectura: el PRD técnico

Primero, crear el explorador de código. Es un agente económico (modelo haiku) cuyo trabajo es recorrer el código y extraer datos crudos, sin interpretarlos. Se crea siguiendo agents.md; su Expertise es la de un analista que lista e inventaría: “recorre el repositorio y devuelve inventarios verificables —archivos, dependencias con versiones, cobertura de tests, conteos, patrones que se repiten—; no saca conclusiones, eso es del arquitecto.” Se reutiliza en cada arqueología puntual de la Fase 6, así que conviene definirlo bien.

Luego, el proceso entre los dos produce el PRD técnico inicial (su forma as-built):

  1. El explorador entrega los inventarios crudos: árbol de archivos, modelo de datos (tablas/entidades y relaciones), dependencias internas y externas con versiones, cobertura de tests y los patrones de UI que se repiten.
  2. El arquitecto (creado en el paso anterior) los interpreta y redacta el PRD técnico:
    • Mapa de módulos: de qué se encarga cada parte.
    • Modelo de datos y dependencias, tal como están.
    • Zonas de riesgo: código sin tests, módulos que tocan dinero/datos sensibles, acoplamientos peligrosos.
    • Código muerto / deuda visible y estado de la red de seguridad (¿hay integración continua (CI)?, ¿qué cubren los tests?).
    • La semilla del design system: las convenciones visuales de facto del frontend —componentes, colores, tipografía— que ya viven en el código. Acá se recupera (la primera de sus tres etapas); todavía no es canónica.

Se trabaja a dos profundidades. Somera sobre todo el producto —mapa, modelo de datos, dependencias y zonas de riesgo se relevan completos, porque sin el panorama no se puede enrutar trabajo ni evaluar el blast-radius (el radio de impacto: a qué módulos, datos y usuarios llega un cambio y qué puede romper)—. Profunda solo en las zonas que las primeras features van a tocar. Las demás se profundizan cuando se tocan (ver El trabajo nuevo entra por la Fase 6).

Capturar el estado al CLAUDE.md

Crear el mantenedor del CLAUDE.md. Es el agente económico (haiku) que claude-md.md ya define: su tarea es resumir y podar para mantener el CLAUDE.md conciso y actualizado. Se crea siguiendo agents.md; en proyectos chicos puede ser el mismo documentador.

Capturar el estado. Con ese agente se puebla el CLAUDE.md vivo por ingeniería inversa, destilando lo recuperado. Sobre la plantilla estándar, el CLAUDE.md de un proyecto brownfield contiene además:

  • Punteros a los dos baselines: el PRD de negocio (brief) y el PRD técnico (as-built); el detalle vive en ellos, el CLAUDE.md solo apunta y se mantiene conciso.
  • Las zonas peligrosas: las 3–5 cosas que un agente debe saber para no romper algo heredado (“el módulo de pagos no tiene tests; caracterízalo antes de tocarlo”).
  • Dos políticas declaradas: la versión de Argui contra la que corre el proyecto y la estrategia de specs elegida.

Extraer los estándares

En greenfield los estándares se inventan antes de los agentes (F4.6 del workflow); en brownfield ya existen implícitos en el código y se codifican. Es una pasada de extracción por cada dominio que reveló la recuperación de la arquitectura (base/proyecto, backend, frontend, tests, infra) — actividades, no roles permanentes. Por dominio:

  1. El explorador de código lista, sin interpretar, todas las formas en que el código hace una misma cosa —cada manera de manejar errores, cada patrón de endpoint— para que las inconsistencias salten.
  2. El arquitecto redacta el estándar a partir de esas listas y del código representativo: naming, estructura, patrones de API (interfaz de programación de aplicaciones), manejo de errores y estilo de tests. En frontend, el estándar codifica la semilla de design system recuperada en el paso anterior —sus tokens y patrones visuales de facto— (segunda etapa): es la referencia de apariencia que el frontend sigue hasta que el primer incremento visible la consolide.
  3. Cada inconsistencia se resuelve con una decisión humana ✋: cuál es el estándar oficial de aquí en adelante, y si lo divergente se conserva o se corrige al pasar por esos módulos — incremental, nunca un refactor masivo de entrada.

El resultado son los estandares/ del proyecto, anclados al código real. Son el insumo de la Expertise de los agentes, así que van antes de crear los implementadores: si se crean primero, cada uno improvisa patrones sobre los que ya existen.

Auditar la arquitectura

El arquitecto pasa de describir a juzgar, una sola vez. Se le da el PRD técnico inicial y los estándares extraídos. El resultado se reparte en los documentos del proyecto:

  • Las restricciones (deuda estructural, acoplamientos riesgosos, decisiones heredadas que condicionan el trabajo, qué respetar vs. qué mejorar al pasar) → se incorporan al PRD técnico, que deja de ser pura descripción del as-built.
  • Los flujos críticos a caracterizar → se vuelven items de backlog (los de la red de seguridad, paso siguiente).
  • La deuda que no toca el trabajo inmediato → candidatos de backlog para la Fase 6.
  • Si la auditoría cambia una decisión de arquitectura → además a decisiones.md (ver operations.md).

No toca el PRD de negocio: la auditoría es técnica.

Estos hallazgos inicializan el backlog del proyecto (backlog.md.template): el backlog brownfield nace acá —con los items de la red de seguridad primero— y de ahí crece por la Fase 6.

  • Si ya hay features en mente (el caso común: se adopta Argui porque viene trabajo nuevo), la auditoría se enfoca por su blast-radius: se prioriza entender y caracterizar lo que ese trabajo va a tocar.
  • Si todavía no hay features (se adopta la metodología solo para ordenar el producto), no hacen falta: la auditoría es una lectura general de riesgo, y los flujos críticos a caracterizar se eligen por su riesgo inherente (pagos, autenticación), no por lo que se va a tocar. Todo el trabajo profundo se difiere a la Fase 6, cuando aparezca trabajo real (principio incremental).

Crear los demás agentes

Con los mismos arquetipos y la misma guía de greenfield (agents.md, agentes/README.md) —no hay plantilla distinta para brownfield—. Se deciden desde los dominios que reveló la arquitectura más el trabajo que viene: los mínimos son implementador(es), revisor(es) y tester(s). El arquitecto, el explorador de código y el mantenedor del CLAUDE.md ya existen; acá se crea el resto, incluido el agente PRD, porque los baselines (brief de producto + PRD técnico) son su primer material —el mismo disparador de greenfield, que lo crea tras el primer borrador—. El agente UX/UI espera a la Fase 6: nace cuando el primer incremento visible necesita prototipo (como greenfield lo crea en la Fase 3 para la primera UI).

La Expertise de cada agente lleva las convenciones existentes del proyecto explícitas —no patrones genéricos del stack—: “sigue el patrón de repositorios que ya usa este código”, “respeta el manejo de errores existente (estándar §X)”. El revisor carga más peso que en greenfield: su trabajo incluye cazar regresiones e inconsistencias con lo heredado.

Montar la red de seguridad

Greenfield construye los tests junto con el código; brownfield hereda código sin red. Sin línea base, el verify y el qa del ciclo no tienen contra qué comparar. Antes de modificar nada, se monta el mínimo (todo definido en standards.md):

  • CI funcionando y, si faltan, la versión/SHA (el hash del commit) y el /health expuestos (§7), más el monitoreo mínimo (§9) —disponibilidad + error tracker—, proporcional a un PMV.
  • Tests de caracterización de los flujos críticos que marcó la auditoría: pruebas que congelan el comportamiento correcto de hoy para detectar regresiones.

La construyen los agentes recién creados: el tester escribe los tests de caracterización; un implementador de backend o infra cablea CI, /health, versión y el SDK (kit de desarrollo) del error tracker. Sus tareas salen del backlog —los items que la auditoría inicializó—, que se trabajan antes que cualquier feature (el análogo del CHQ-002 (CI/CD) de greenfield). Si al montarla aparecen flujos críticos o huecos que la auditoría no había visto, se agregan al backlog (capturados en el origen): el backlog es la única cola de trabajo, también para la red de seguridad. En código que toca dinero o datos sensibles, no se aplaza.

No esperes a entenderlo todo para empezar: recupera lo mínimo más las zonas que tus primeras features tocan, y sigue. El resto se recupera cuando llegues a él, tirado por el trabajo.

El trabajo nuevo entra por la Fase 6

Con la maquinaria montada y los baselines recuperados, el proyecto opera en evolución continua. Cada feature nueva entra por el intake, se tría por carril (cambio chico / feature visible / área nueva) y pasa el gate de definición validada antes de construirse. Es el mismo loop de greenfield — con tres deltas.

Cómo difiere la Fase 6 en brownfield

  1. Recuperar la zona antes de tocarla. Antes de modificar un módulo que el onboarding no exploró a fondo, se hace una arqueología puntual de ese módulo —el explorador de código lista, el arquitecto interpreta—, se completa su spec y se corrige el PRD técnico si cambió la estructura. No es repetir el onboarding ni re-mapear todo: es recuperar, una zona a la vez, lo que se va a tocar. Si el módulo ya fue recuperado, este paso no aplica. Es un ritual repetido: se opera con el comando recuperar-zona.
  2. Los PRDs nacen recuperados, no diseñados. Los primeros incrementos a veces completan el baseline tanto como agregan. El loop es el mismo; el punto de partida no.
  3. Reflejo de red de seguridad más afilado. Un incremento que toca un camino crítico (pagos, checkout) exige caracterizar ese flujo antes de tocarlo, aunque el onboarding no lo hubiera cubierto.

Cómo crecen los PRDs por incremento

Cada incremento hace crecer los PRDs vivos (negocio y técnico) y agrega sus specs, según el carril (los mismos de la Fase 6):

  • Cambio chico / bug → sin tocar PRD; el change spec es la definición.
  • Feature visible → crece el PRD de negocio (el agente PRD, desde el pedido del stakeholder + el brief; /opsx:explore si es difuso) y el PRD técnico (desde el PRD de negocio + el PRD técnico actual + la arqueología puntual de los módulos que toca + el arquitecto si el gate marcó arquitectónico) + el slice de prototipo validado ✋.
  • Área nueva → se re-corren las fases 1–4 del workflow para esa rebanada, con PRDs completos de esa área.

Design system y prototipo

  • Design system: la semilla recuperada (en el PRD técnico) y codificada (en el estándar de frontend) llega acá a su tercera etapa — el primer incremento visible la consolida a artefacto canónico (documento + tokens en código), como en prototype.md. Si el producto ya traía un design system formal, se reusa y no hay nada que consolidar.
  • Prototipo: solo para incrementos visibles nuevos —nunca para maquetar lo que ya existe y se puede clicar—.

La puesta al día de versión

Para un proyecto que sí nació con Argui pero con una versión anterior. No hay arqueología ni extracción de estándares: los artefactos ya existen. Falta aplicar el delta entre tu versión y la actual — la misma disciplina anti-obsolescencia que se usa para subir OpenSpec (openspec.md → Mantenimiento al subir de versión), elevada a la metodología completa:

  1. Identificar la versión de Argui — está declarada como política en el CLAUDE.md.
  2. Leer el CHANGELOG desde esa versión hasta la actual.
  3. Clasificar cada delta por si afecta a un proyecto en marcha. La clasificación la hace el arquitecto en una pasada y la decisión es humana ✋:
    • Cambios sobre cómo se arranca un proyecto (Fases 0–4) → no afectan; esa etapa ya está hecha.
    • Estándares, stages, plantillas o disciplinas nuevas → candidatos a incorporar (p. ej. monitoreo §9, evals/guardrails §10, el stage qa, el diagrama de dependencias, el aislamiento del entorno, las métricas de proceso, el intake de Fase 6).
  4. Incorporar los que apliquen como items de backlog, en orden de valor — entran por el intake de Fase 6 como cualquier trabajo nuevo.
  5. Re-validar el ciclo end-to-end con un item de prueba.
  6. Actualizar en el CLAUDE.md / decisiones.md contra qué versión de Argui corre ahora el proyecto.

La mayoría de los deltas son aditivos (versiones MINOR/PATCH de SemVer, Semantic Versioning): incorporación barata, item por item. Un cambio MAJOR es raro, el CHANGELOG lo marca, y puede pedir repensar algo de fondo —pero sigue siendo trabajo de backlog, no un reinicio.

Un proyecto Argui que solo se desfasó de sus propios artefactos (specs viejas, CLAUDE.md inflado) no necesita esto: lo cubre la auditoría periódica de operations.md. La puesta al día de versión es para cuando cambió la metodología, no el proyecto.

Qué cambia respecto a greenfield

Aspecto Greenfield Brownfield
PRD de negocio Se diseña (Fase 2) Nace recuperado (brief de producto) y crece
PRD técnico Se diseña (Fase 2) Nace recuperado (as-built) y crece
Arquitecto Se crea sobre PRDs y diseña (F4.2) Se crea primero y audita el as-built
Estándares Se inventan (F4.6) Se extraen del código existente
Tests Nacen con el código Red de seguridad sobre código heredado, antes de toda feature
Specs Nacen con cada item Lazy: nacen al tocar el módulo
Entrada al ciclo Fases 1→6 en orden Onboarding → entrar por Fase 6

Lo que no cambia: las tres capas (PRD de negocio, PRD técnico, specs), el ciclo de Fase 5 (gate → apply → verify → qa → archive), los puntos de aprobación humana ✋, el modelo de eficiencia por agente, los arquetipos de agente y el prototipo trazable de cada slice visible. Brownfield es un lente sobre la misma metodología, no otra metodología.

Relación con el resto de la documentación

  • El flujo base y la Fase 6: workflow.md.
  • Las tres capas y los PRDs: workflow.md (fases 2–3).
  • Estándares que se extraen / la red de seguridad: standards.md (§4, §7, §9).
  • Crear los agentes: agents.md, agentes/README.md.
  • El CLAUDE.md y las políticas del proyecto: claude-md.md.
  • El comando del ritual repetido: recuperar-zona.
  • Disciplina anti-obsolescencia que reusa la puesta al día de versión: openspec.md, dependencies.md.