Brownfield Adoption

Modo Brownfield — Integracion del Framework en Proyectos Existentes

Companion del AI-First Engineering Framework v7.3.0

Version: 4.0.0 | Fecha: Marzo 2026 Aplica a: Proyectos existentes en produccion que quieren adoptar el framework Fuentes: OpenSpec delta markers, Strangler Fig (Martin Fowler), EPAM ADLC, OWASP MCP Top 10, EU AI Act Novedades v7.3.0: OWASP MCP Top 10 audit para legacy APIs, AIBOM para modernizacion, EU AI Act Art.50/73, DORA metrics, procedimiento de modernizacion legacy, Platform Integration Guide para multi-IDE Novedades v6.4: Data Governance templates, MCP server config, compliance enforcement, cost model, human-agent responsibility matrix

---

1. ESCENARIOS CUBIERTOS

Esta guia cubre tres escenarios de adopcion incremental:

Escenario	Ejemplo tipico	Ruta recomendada
A — Agregar AI a app existente	”Tengo un Django/Spring monolito y quiero agregar RAG, chatbot o agente”	Seccion 4 (Strangler Fig AI)
B — Modernizar con disciplina	”Mi app funciona pero no tiene specs, tests ni ADRs”	Seccion 3 (Adopt & Document)
C — Reescribir incrementalmente	”Quiero migrar un monolito a microservicios AI-native”	Seccion 5 (Modernizacion incremental)

Regla de oro: NO reescribir lo que funciona. Documentar, envolver, evolucionar.

---

2. BOOTSTRAP — INSTALAR EL FRAMEWORK EN UN PROYECTO EXISTENTE

2.1 Via script (recomendado)

# Desde la raiz de tu proyecto existente
cd mi-proyecto-existente

# Descargar y ejecutar el script de adopcion brownfield
git clone https://github.com/aforero22/baseline.git /tmp/baseline
/tmp/baseline/scripts/init-brownfield.sh "Mi Proyecto" "mi-proyecto"
rm -rf /tmp/baseline

El script init-brownfield.sh:

1. Agrega el baseline como submodule en baseline/
2. Copia .claude/ (rules, skills, agents, hooks)
3. Copia CLAUDE.md, AGENTS.md, .claudeignore, HANDOFF.md, DISCOVERIES.md
4. Crea project/ con templates YAML vacios
5. Genera project/project-config.yaml marcado como brownfield: true
6. Genera project/data_classification.yaml — clasificacion de datos 5 niveles (v6.4)
7. Genera project/data_provenance_registry.yaml — registro de fuentes AI (v6.4)
8. Configura .claude/mcp_config.json — MCP server del framework (v6.4)
9. NO toca tu codigo existente — solo agrega artefactos del framework

2.2 Manual (si no quieres submodule)

# 1. Copiar context layers
cp -r baseline/project-template/.claude ./.claude
cp baseline/project-template/CLAUDE.md ./CLAUDE.md
cp baseline/project-template/AGENTS.md ./AGENTS.md
cp baseline/project-template/.claudeignore ./.claudeignore

# 2. Crear estructura de proyecto
mkdir -p project/{F01_strategy,F02_domain,F03_knowledge,F04_architecture}
mkdir -p project/{F05_contracts/.openspec,F06_build,F07_tevv,F08_security}
mkdir -p project/{F09_operations,F10_evolution}
cp baseline/project-template/project/project-config.yaml project/

# 3. Editar project-config.yaml
# Marcar brownfield: true y documentar el stack existente

---

3. ADOPT & DOCUMENT — FOTOGRAFIAR EL ESTADO ACTUAL

3.1 Evaluacion del codebase (1-2 horas)

Antes de adoptar, evaluar el estado real del proyecto:

CHECKLIST DE EVALUACION BROWNFIELD
───────────────────────────────────
□ Tests existentes?         → SI: nivel de coverage? / NO: prioridad alta
□ CI/CD existente?          → SI: que pipeline? / NO: agregar basico
□ Specs/contratos?          → SI: formato? / NO: generar desde codigo
□ Docs de arquitectura?     → SI: actualizadas? / NO: ADRs retroactivos
□ Deuda tecnica conocida?   → SI: documentar / NO: evaluar con @architect
□ Secrets management?       → SI: que herramienta? / NO: mover a .env/vault
□ Monitoring/observability? → SI: que stack? / NO: evaluar en F09
□ Datos sensibles (PII)?    → SI: documentar en F08 / NO: confirmar

3.2 project-config.yaml brownfield

project:
  name: "Mi Proyecto Existente"
  codename: "mi-proyecto"
  status: "production"          # ya esta en produccion
  brownfield: true              # marca explicita
  started: "2024-06-15"         # fecha original del proyecto
  framework_adopted: "2026-03-19" # fecha de adopcion del framework

track:
  current: "lean"               # brownfield suele empezar como lean

brownfield:
  existing_stack:
    backend: "python-django"
    backend_version: "4.2"
    frontend: "react"
    frontend_version: "18"
    database: "postgresql"
    database_version: "15"
    deployment: "aws-ecs"
  existing_tests: true
  test_coverage: 45             # porcentaje estimado
  existing_ci: true
  ci_tool: "github-actions"
  tech_debt_level: "medium"     # low | medium | high | critical
  codebase_size: "medium"       # small (<10K LOC) | medium (10-50K) | large (>50K)
  team_size: 3
  modernization_goal: "add-ai"  # add-ai | discipline | rewrite-incremental

3.3 Delta markers en artefactos

Usar marcadores para distinguir lo existente de lo nuevo:

project/F04_architecture/ai_partition_map.yaml

components:
  - name: "user-service"
    marker: "EXISTING"        # ya existia antes del framework
    type: "deterministic"
    notes: "Django REST, en produccion desde 2024"

  - name: "recommendation-engine"
    marker: "ADDED"           # nuevo componente AI
    type: "ai"
    intelligence_level: 1     # RAG-Augmented
    notes: "Nuevo, sigue framework desde F01"

  - name: "auth-module"
    marker: "MODIFIED"        # existente pero actualizado
    type: "deterministic"
    notes: "Refactorizado para soportar MCP"

  - name: "legacy-reports"
    marker: "REMOVED"         # programado para eliminacion
    type: "deterministic"
    timeline: "Q3 2026"
    replacement: "ai-dashboard"
    notes: "Reemplazado por dashboard AI"

  - name: "search-api"
    marker: "NEEDS_REVIEW"    # existente, requiere evaluacion
    type: "deterministic"
    notes: "Candidato a reemplazar con RAG semantic search"

Markers disponibles

Marker	Significado	Accion
EXISTING	Ya existe, documentar como esta	Solo documentar, no cambiar
ADDED	Nuevo componente o artefacto	Seguir framework completo
MODIFIED	Existente pero cambiado	Documentar cambio y razon
REMOVED	Programado para eliminacion	Documentar timeline y reemplazo
NEEDS_REVIEW	Existente, requiere evaluacion	Evaluar si cumple framework

3.4 ADR retroactivo (template)

Para decisiones que ya se tomaron pero no estan documentadas:

# ADR NNN — [Titulo de la decision]

## Estado
Aceptado (retroactivo — decision tomada en [fecha original])

## Contexto
[Describir el contexto original de la decision]

## Decision
[Que se decidio y por que]

## Consecuencias conocidas
[Que ha pasado desde que se tomo la decision]
[Deuda tecnica acumulada, si existe]

## Reevaluacion
[Sigue siendo la decision correcta? Que cambiaria?]

3.5 Fases de adopcion gradual

No intentar llenar las 10 fases de golpe. Priorizar:

  SEMANA 1 (obligatorio)          SEMANA 2-3 (recomendado)       SEMANA 4+ (incremental)
  ──────────────────────          ────────────────────────       ──────────────────────
  F01 — Problem statement         F02 — Capability map            F03 — Knowledge sources
  F04 — ADRs retroactivos         F05 — OpenAPI desde codigo      F07 — Test strategy
  F08 — Compliance matrix         F09 — Operating baseline        F10 — Improvement backlog

Semana 1 — Minimo viable:

1. F01 Strategy — Documentar el problema original y el estado actual
2. F04 Architecture — Documentar stack y decisiones con ADRs retroactivos
3. F08 Security — Compliance matrix del estado actual

Semana 2-3 — Contratos y operacion: 4. F05 Contracts — Generar OpenAPI spec desde el codigo existente 5. F02 Domain — Mapear capacidades actuales (MoSCoW) 6. F09 Operations — Documentar operating baseline actual

Semana 4+ — Resto: 7. Las demas fases se adoptan segun necesidad

---

4. STRANGLER FIG AI — AGREGAR INTELIGENCIA A UNA APP EXISTENTE

Patron inspirado en Martin Fowler: envolver el sistema existente con una capa nueva que gradualmente asume funcionalidad, hasta que el legacy se puede retirar.

4.1 El patron

ANTES                               DESPUES (Strangler Fig AI)
──────                               ───────────────────────────

  [Cliente]                           [Cliente]
     │                                    │
     ▼                                    ▼
  ┌──────────┐                     ┌──────────────┐
  │  Legacy   │                     │  AI Gateway  │ ← nuevo (proxy inteligente)
  │  Monolith │                     │  / Router    │
  │           │                     └──────┬───────┘
  │  Django   │                            │
  │  Spring   │                     ┌──────┴───────┐
  │  Rails    │                     │              │
  └──────────┘                      ▼              ▼
                              ┌──────────┐   ┌──────────┐
                              │  Legacy   │   │    AI    │
                              │  Monolith │   │ Services │ ← nuevos
                              │ (EXISTING)│   │ (ADDED)  │
                              └──────────┘   └──────────┘

4.2 Pasos del Strangler Fig AI

Paso 1 — Facade/Gateway (1-2 dias)

Crear un reverse proxy o API gateway delante del legacy.
Todo el trafico pasa por el gateway sin cambios.
Esto permite interceptar y redirigir requests individuales.

Paso 2 — Primera capacidad AI (1-2 semanas)

Elegir UNA capacidad bien acotada para implementar con AI:
- Busqueda semantica (reemplazar search basico con RAG)
- Chatbot de soporte (nueva funcionalidad, no reemplaza nada)
- Clasificacion automatica (mejorar un proceso manual)
- Resumen de contenido (agregar valor a datos existentes)

Regla: elegir la que tenga menor riesgo y mayor valor visible.

Paso 3 — Coexistencia (continuo)

El gateway rutea:
- /api/search → AI Service (nuevo, RAG-augmented)
- /api/* → Legacy (todo lo demas, sin cambios)

Feature flag para rollback instantaneo:
- AI_SEARCH_ENABLED=true → AI service
- AI_SEARCH_ENABLED=false → legacy search

Paso 4 — Expansion gradual (semanas/meses)

Repetir paso 2-3 para cada capacidad nueva.
El legacy se "estrangula" gradualmente.
Cada capacidad migrada se marca como REMOVED en ai_partition_map.yaml.

4.3 Arquitectura de coexistencia

project/F04_architecture/ai_partition_map.yaml

routing:
  gateway: "nginx"  # o API gateway, Envoy, Kong
  strategy: "path-based"  # path-based | header-based | percentage

routes:
  - path: "/api/search"
    target: "ai-search-service"
    marker: "ADDED"
    feature_flag: "AI_SEARCH_ENABLED"
    fallback: "legacy-search"

  - path: "/api/chat"
    target: "ai-chatbot"
    marker: "ADDED"
    feature_flag: "AI_CHAT_ENABLED"
    fallback: null  # nueva funcionalidad, no hay legacy

  - path: "/api/*"
    target: "legacy-monolith"
    marker: "EXISTING"
    notes: "Catch-all para todo lo que aun no se migra"

4.4 Evaluacion de candidatos a AI

Para decidir que migrar primero:

Criterio	Peso	Pregunta
Valor de negocio	Alto	Mejora KPIs visibles?
Riesgo de fallo	Alto	Si falla el AI, hay fallback?
Datos disponibles	Medio	Hay datos suficientes para entrenar/grounding?
Independencia	Medio	Se puede desacoplar del monolito facilmente?
Complejidad	Medio	Requiere cambios en el schema de DB?
Visibilidad	Bajo	El usuario final lo nota? (para buy-in)

---

5. MODERNIZACION INCREMENTAL — REESCRIBIR SIN ROMPER

5.1 Cuando reescribir (y cuando NO)

REESCRIBIR SI:                          NO REESCRIBIR SI:
─────────────                           ─────────────────
- Tech debt >60% del esfuerzo           - Funciona y el equipo lo entiende
- Stack sin soporte (Python 2, etc.)    - Solo necesitas agregar AI
- No hay tests ni docs                  - El costo de reescribir > beneficio
- Performance inaceptable               - Deadline < 3 meses
- Compliance imposible en stack actual  - Equipo de 1 persona

5.2 Plan de modernizacion (template)

project/F04_architecture/modernization_plan.yaml

modernization:
  approach: "strangler-fig"  # strangler-fig | parallel-run | big-bang (NO recomendado)
  timeline: "6 meses"

  phases:
    - phase: 1
      name: "Foundation"
      duration: "2 semanas"
      tasks:
        - "Instalar framework (init-brownfield.sh)"
        - "Documentar estado actual (ADRs retroactivos)"
        - "Generar OpenAPI spec desde codigo existente"
        - "Agregar gateway/proxy delante del legacy"
      deliverables:
        - "project-config.yaml (brownfield: true)"
        - "adr_001_stack_selection.md (retroactivo)"
        - "api-spec.yaml (generado desde codigo)"

    - phase: 2
      name: "First AI Capability"
      duration: "2-4 semanas"
      tasks:
        - "Elegir capacidad AI candidata (evaluacion §4.4)"
        - "Implementar con feature flag"
        - "Tests de contrato (legacy vs nuevo deben ser compatibles)"
        - "Deploy en paralelo con monitoring"
      deliverables:
        - "ai_partition_map.yaml"
        - "Servicio AI desplegado con feature flag"

    - phase: 3
      name: "Expand & Stabilize"
      duration: "continuo"
      tasks:
        - "Migrar capacidades adicionales"
        - "Reducir trafico al legacy"
        - "Documentar learnings en DISCOVERIES.md"
      deliverables:
        - "ai_partition_map.yaml actualizado"
        - "DISCOVERIES.md con patrones encontrados"

5.3 Generar OpenAPI spec desde codigo existente

Para proyectos sin specs, generarlas automaticamente:

# Django REST Framework → OpenAPI
python manage.py generateschema --format openapi3 > project/F05_contracts/.openspec/api-spec.yaml

# FastAPI → OpenAPI (ya incluido)
curl http://localhost:8000/openapi.json | python -m json.tool > api-spec.json

# Spring Boot → OpenAPI (springdoc-openapi)
curl http://localhost:8080/v3/api-docs > api-spec.json

# Express.js (con swagger-jsdoc)
npx swagger-jsdoc -d swaggerDef.js -o api-spec.yaml

# Rails (con rswag)
rails rswag:specs:swaggerize

Una vez generada, la spec se convierte en source of truth. Futuros cambios al API deben empezar por la spec (spec-first), no por el codigo.

---

6. CONTEXT LAYERS PARA BROWNFIELD

6.1 CLAUDE.md brownfield

Agregar una seccion al CLAUDE.md que documente el estado legacy:

## Estado Legacy (Brownfield)

### Stack existente
- Backend: Django 4.2 + DRF
- Frontend: React 18 + Next.js
- DB: PostgreSQL 15
- Deploy: AWS ECS + RDS

### Codigo existente — NO tocar sin aprobacion
- `apps/users/` — servicio de usuarios (EXISTING, estable)
- `apps/billing/` — facturacion (EXISTING, deuda tecnica media)
- `apps/reports/` — reportes legacy (NEEDS_REVIEW, candidato a AI)

### Codigo nuevo — seguir framework completo
- `apps/ai_search/` — busqueda semantica (ADDED, spec-first)
- `apps/chatbot/` — chatbot de soporte (ADDED, spec-first)

### Reglas especiales brownfield
- NO refactorizar codigo EXISTING sin ADR aprobado
- Nuevos componentes AI siguen spec-first completo
- Feature flags obligatorios para cualquier cambio al API existente
- Tests de regresion DEBEN pasar antes de cualquier merge

6.2 .claudeignore brownfield

Agregar al .claudeignore las carpetas del legacy que no deben cargarse en contexto:

# Legacy code (no cargar en contexto AI por defecto)
apps/legacy_*/
migrations/
static/vendor/

---

7. GATE CHECK PARA BROWNFIELD

El script gate-check.sh funciona igual, pero los criterios son mas flexibles:

Gate	Greenfield	Brownfield
A (Strategy)	Problema definido desde cero	Problema documentado + estado actual
B (Domain)	Domain modeling completo	Capability map de lo existente
C (Architecture)	ADRs de nuevas decisiones	ADRs retroactivos + nuevos
D (Contracts)	OpenAPI escrito a mano	OpenAPI generado desde codigo
E (TEVV)	Tests desde cero	Tests existentes + nuevos para AI
F (Operations)	Deploy nuevo	Operating baseline del estado actual

Regla: Gates A y C son los minimos obligatorios en brownfield. El resto se adopta gradualmente.

---

8. LEGACY LANGUAGE MIGRATION PATTERNS (COBOL → Java/Python)

GAP-25: patrones especificos para migrar sistemas en lenguajes legacy (COBOL, RPG, Fortran, PL/I, Natural/ADABAS) a lenguajes modernos con asistencia AI. Basado en: AWS COBOL Migration (Julia White, Feb 2026), IBM Brownfield AI Modernization (Feb 2026).

8.1 El Problema

Millones de lineas de COBOL siguen ejecutando el 95% de las transacciones ATM y el 80% de transacciones presenciales globalmente. Migrar es necesario pero riesgoso:

• El conocimiento del negocio esta embebido en el codigo, no documentado externamente.
• Los desarrolladores originales estan retirados o inaccesibles.
• Los tests son escasos o inexistentes (sistemas de 30+ anos).
• Las reglas de negocio son implicitas (ej: formatos de fecha, redondeo bancario).

8.2 Estrategias de Migracion

Estrategia	Descripcion	Riesgo	Costo	Cuando usar
Rehost (Lift & Shift)	Mover COBOL a cloud sin cambiar	Bajo	Bajo	Legacy estable, sin cambios previstos
Replatform	Compilar COBOL en JVM/CLR (Micro Focus, BluAge)	Medio	Medio	Necesitas cloud pero no puedes reescribir
Refactor AI-Assisted	AI traduce COBOL → Java/Python	Alto	Medio	Tienes ventana de modernizacion
Rewrite Incremental	Strangler-Fig por modulo	Alto	Alto	Modulos independientes identificados
Replace (SaaS)	Sustituir por producto comercial	Medio	Variable	Funcionalidad commoditizada

8.3 AI-Assisted Migration Workflow

┌──────────────────────────────────────────────────────────────┐
│            COBOL → Modern Language Pipeline                    │
│                                                                │
│  Fase 1: COMPRENSION (AI Lee)                                │
│  ┌──────────────────────────────────┐                         │
│  │ 1. Ingesta de copybooks (.cpy)    │                         │
│  │ 2. Parse COBOL → AST             │                         │
│  │ 3. AI genera documentacion:      │                         │
│  │    - Business rules extraidas    │                         │
│  │    - Data flow diagrams          │                         │
│  │    - Dependency graph            │                         │
│  │ 4. Identificar modulos aislados  │                         │
│  └──────────────────────────────────┘                         │
│                    │                                           │
│  Fase 2: TRADUCCION (AI Genera)                               │
│  ┌──────────────────────────────────┐                         │
│  │ 5. AI traduce modulo → Java/Py   │                         │
│  │ 6. Genera tests a partir de:     │                         │
│  │    - Business rules documentadas │                         │
│  │    - Test cases existentes       │                         │
│  │    - Edge cases inferidos        │                         │
│  │ 7. Human review obligatorio      │                         │
│  └──────────────────────────────────┘                         │
│                    │                                           │
│  Fase 3: VALIDACION (AI + Human Verifican)                    │
│  ┌──────────────────────────────────┐                         │
│  │ 8. Run parallel: COBOL + nuevo   │                         │
│  │ 9. Compare outputs (diff)        │                         │
│  │ 10. Numeric precision tests      │                         │
│  │ 11. Edge case regression         │                         │
│  │ 12. Performance benchmarks       │                         │
│  └──────────────────────────────────┘                         │
│                    │                                           │
│  Fase 4: CUTOVER (Strangler-Fig)                              │
│  ┌──────────────────────────────────┐                         │
│  │ 13. Deploy nuevo detras de proxy  │                         │
│  │ 14. Shadow traffic (log-only)     │                         │
│  │ 15. Canary: 5% → 25% → 50% → 100%│                        │
│  │ 16. Decomission COBOL module      │                         │
│  └──────────────────────────────────┘                         │
└──────────────────────────────────────────────────────────────┘

8.4 Herramientas para Migracion AI-Assisted

Herramienta	Tipo	Lenguajes Source	Target	Pricing
AWS Mainframe Modernization	Cloud service	COBOL, PL/I, JCL	Java (BluAge/Micro Focus)	Pay-per-use
Amazon Q Transform	AI-assisted	COBOL	Java	Incluido en Q Developer
IBM watsonx Code Assistant for Z	AI-assisted	COBOL	Java	Enterprise license
Google Cloud COBOL Modernization	AI-assisted	COBOL	Java, C#	Enterprise
Anthropic Claude (manual)	General AI	Cualquier legacy	Cualquier moderno	Per-token
Micro Focus (OpenText)	Replatform	COBOL	JVM/.NET	Enterprise license
BluAge (AWS)	Refactor	COBOL, RPG	Java Spring	Via AWS

8.5 Prompt Engineering para Migracion COBOL

# Fase 1: Comprension (pegar programa COBOL)
---
Analiza este programa COBOL. Genera:
1. Lista de business rules implementadas (una por linea)
2. Data structures (equivalente a un JSON schema)
3. Flujo de control principal (pseudocodigo)
4. Dependencias externas (archivos, DB, CICS calls)
5. Edge cases criticos (overflow, fecha, redondeo)

No traduzcas aun. Solo documenta.
---

# Fase 2: Traduccion (con business rules ya documentadas)
---
Traduce este modulo COBOL a [Java/Python].

Reglas:
- Mantener EXACTA la logica de negocio documentada en [business_rules.md]
- COMP-3 (packed decimal) → BigDecimal (Java) / Decimal (Python)
- Formato fecha YYMMDD → ISO 8601, manejar Y2K correctamente
- COPY statements → imports del modulo correspondiente
- PERFORM → metodos/funciones con nombres descriptivos
- EVALUATE/WHEN → switch/match
- Preservar TODOS los redondeos (ROUNDED, TRUNCATION)
- Generar tests unitarios para cada business rule

Incluir comentarios que referencien la seccion COBOL original.
---

# Fase 3: Validacion (generar test comparativo)
---
Genera un test harness que:
1. Lee los mismos inputs de test que el programa COBOL original
2. Ejecuta la version [Java/Python]
3. Compara outputs campo por campo con precision de 2 decimales
4. Reporta cualquier diferencia con el input que la causa
---

8.6 Trampas de Migracion COBOL (Lecciones AWS)

Basado en Julia White (VP AWS), “COBOL Migration: What We’ve Learned” (Feb 2026)

Trampa	Descripcion	Mitigacion
Packed Decimal precision	COBOL COMP-3 tiene precision exacta; float/double no	Usar BigDecimal (Java) o Decimal (Python) siempre
REDEFINES	Misma memoria, multiples interpretaciones	Mapear a union types o clases separadas con factory
COPY members	Include files compartidos entre programas	Crear modulo/paquete compartido, importar
88-levels	Condiciones nombradas en COBOL	Mapear a enums con metodos de validacion
CICS/IMS	Transaction middleware	Spring Transactions / SQLAlchemy + message queue
JCL / Job scheduling	Batch processing	Apache Airflow, AWS Step Functions, cron
Implicit rules	Reglas de negocio no documentadas	Fase 1 (comprension AI) es critica — no saltar
Date formats	YYMMDD, windowing, leap years	Tests exhaustivos con dates criticas (2000, 2038, 2100)

8.7 project-config.yaml para Migracion Legacy

# project/project-config.yaml (seccion legacy_migration)
legacy_migration:
  enabled: true
  source_language: "COBOL"
  target_language: "Java 21"
  strategy: "refactor_ai_assisted"  # rehost | replatform | refactor_ai_assisted | rewrite

  source_inventory:
    total_programs: 342
    total_lines: 1_200_000
    copybooks: 89
    jcl_jobs: 156
    cics_transactions: 45

  migration_phases:
    phase_1_understand:
      status: "in_progress"
      modules_documented: 47
      modules_total: 342
      tool: "Claude + custom COBOL parser"

    phase_2_translate:
      status: "pending"
      approach: "module_by_module"
      priority_order: "business_impact DESC, dependency_count ASC"

    phase_3_validate:
      status: "pending"
      parallel_run_duration: "4 weeks per module"
      precision_tolerance: "0.00 (exact match for financial)"

    phase_4_cutover:
      status: "pending"
      strategy: "strangler_fig"
      canary_percentages: [5, 25, 50, 100]

  risk_mitigations:
    - "Packed decimal → BigDecimal (never float)"
    - "Parallel run with output comparison"
    - "Business rules documented before translation"
    - "Human review mandatory for financial calculations"
    - "Date edge cases: Y2K, 2038, leap years"

8.8 Checklist Migracion Legacy

Pre-Migracion

• Inventario completo de programas, copybooks, JCL
• Identificar modulos candidatos (bajo acoplamiento, alto valor)
• Definir precision numerica requerida (financial = exact)
• Setup entorno de parallel run (COBOL + target ejecutan en paralelo)

Por Modulo

• Fase 1: AI documenta business rules (NO traducir aun)
• Human valida business rules contra SMEs
• Fase 2: AI traduce modulo → target language
• Human review de traduccion (especialmente: decimals, dates, REDEFINES)
• Fase 3: Tests unitarios + parallel run pasan al 100%
• Performance benchmark: target <= 1.2x latencia COBOL
• Fase 4: Canary deployment 5% → 25% → 50% → 100%
• Decomission modulo COBOL original

---

9. OWASP MCP TOP 10 — CONSIDERACIONES PARA BROWNFIELD

v7.3.0: Cuando se envuelven APIs legacy con MCP servers (ej: exponer un servicio Django como tool MCP), se introducen riesgos de seguridad especificos que deben auditarse.

9.1 Riesgos al exponer APIs legacy via MCP

Cuando un sistema legacy se expone como MCP server para que agentes AI lo consuman, los riesgos incluyen:

Riesgo OWASP MCP	Aplicacion brownfield	Mitigacion
Tool Poisoning	El legacy puede retornar datos maliciosos que el agente interpreta como instrucciones	Validar y sanitizar outputs del legacy antes de exponerlos via MCP
Excessive Agency	El agente AI obtiene acceso a operaciones del legacy que no deberia (write, delete)	Principio de minimo privilegio: exponer solo operaciones read al inicio
Rug Pull	El MCP server que envuelve el legacy cambia comportamiento sin notificar	Versionado estricto del MCP wrapper, tests de contrato
Server Compromise	El legacy tiene vulnerabilidades conocidas que se heredan al wrapper MCP	SAST/SCA del legacy ANTES de exponerlo via MCP
Indirect Prompt Injection	Datos del legacy (ej: contenido de usuarios) contienen instrucciones maliciosas	Sanitizar datos del legacy que fluyen hacia el agente

9.2 Auditoria de seguridad MCP para wrappers legacy

Ejecutar el script de auditoria antes de exponer cualquier API legacy via MCP:

# Auditar el MCP server que envuelve el legacy
python3 baseline/scripts/mcp-security-audit.py \
  --config .claude/mcp_config.json \
  --focus legacy-wrappers \
  --output project/F08_security/mcp_legacy_audit.json

El script mcp-security-audit.py verifica:

• Source trust: Origen del MCP server (propio vs tercero)
• Auth: Autenticacion entre agente y MCP server
• Transport: Cifrado de comunicacion (TLS obligatorio para legacy expuesto)
• Tool permissions: Operaciones expuestas vs minimo privilegio
• Input validation: Sanitizacion de inputs hacia el legacy

9.3 Checklist MCP para brownfield

• Inventario de APIs legacy que se exponen via MCP
• SAST/SCA del codigo legacy antes de exponerlo (sast-sca-scanner.py)
• MCP security audit ejecutado (mcp-security-audit.py)
• Solo operaciones read expuestas inicialmente
• Rate limiting configurado en el wrapper MCP
• Logging de todas las invocaciones del agente al legacy
• Tests de contrato entre MCP wrapper y API legacy

---

10. AIBOM PARA MODERNIZACION BROWNFIELD

v7.3.0: El AI Bill of Materials (AIBOM) documenta todos los componentes AI agregados durante la modernizacion brownfield, su procedencia, modelos usados y datos de entrenamiento.

10.1 Por que AIBOM en brownfield

En brownfield, la distincion entre componentes EXISTING y ADDED es critica para:

• Trazabilidad: Saber exactamente que componentes AI se agregaron al sistema legacy
• Compliance: EU AI Act Art.50 requiere transparencia sobre componentes AI
• Auditoria: Responder “que modelos usa tu sistema, con que datos, desde cuando”
• Incidentes: Si un componente AI falla, saber su procedencia exacta

10.2 Generar AIBOM desde artefactos del proyecto

# Generar AIBOM automaticamente desde los artefactos del framework
python3 baseline/scripts/aibom-generator.py \
  --project-dir . \
  --output project/F08_security/aibom.yaml \
  --format yaml

El script aibom-generator.py escanea:

• ai_partition_map.yaml — componentes marcados como ADDED (AI)
• project-config.yaml — configuracion de modelos y providers
• knowledge_sources.yaml — fuentes de datos para RAG/grounding
• .claude/mcp_config.json — MCP servers configurados

10.3 AIBOM template para brownfield

# project/F08_security/aibom.yaml (generado por aibom-generator.py)
aibom:
  project: "mi-proyecto"
  generated: "2026-03-22"
  brownfield: true

  ai_components:
    - name: "ai-search-service"
      marker: "ADDED"
      type: "rag"
      model: "claude-sonnet-4-20250514"
      provider: "anthropic"
      added_date: "2026-03-20"
      data_sources:
        - "knowledge_base_v2 (internal docs)"
        - "product_catalog (PostgreSQL)"
      purpose: "Busqueda semantica para reemplazar search legacy"
      risk_level: "limited"  # EU AI Act classification

    - name: "chatbot-soporte"
      marker: "ADDED"
      type: "conversational"
      model: "claude-sonnet-4-20250514"
      provider: "anthropic"
      added_date: "2026-03-22"
      data_sources:
        - "faq_database (internal)"
        - "ticket_history (Zendesk export)"
      purpose: "Chatbot de soporte al cliente"
      risk_level: "limited"

  legacy_components_exposed:
    - name: "user-service"
      marker: "EXISTING"
      exposed_via: "mcp-wrapper"
      operations_exposed: ["read_user", "search_users"]
      mcp_audit_date: "2026-03-20"

---

11. EU AI ACT — COMPLIANCE DURANTE ADOPCION BROWNFIELD

v7.3.0: Al agregar componentes AI a un sistema legacy, las obligaciones del EU AI Act aplican a los componentes ADDED, no necesariamente a los EXISTING.

11.1 Art.50 — Obligaciones de transparencia

Cuando se agregan componentes AI a un sistema en produccion:

Obligacion Art.50	Aplicacion brownfield	Artefacto requerido
Marcar contenido AI	Outputs generados por componentes ADDED deben identificarse como AI-generated	Metadata de respuesta con flag ai_generated: true
Informar al usuario	Los usuarios deben saber cuando interactuan con AI (chatbot, search AI)	UI disclosure en puntos de contacto AI
Documentar capacidades	Registrar que puede y no puede hacer cada componente AI	AIBOM + ai_partition_map.yaml

11.2 Art.73 — Reporte de incidentes

Los componentes AI en produccion (ADDED) tienen obligacion de reporte:

# project/F08_security/compliance_matrix.yaml (seccion EU AI Act)
eu_ai_act:
  applies: true
  scope: "componentes ADDED solamente"

  art_50_transparency:
    ai_content_marking: true
    user_disclosure: true
    capability_documentation: "aibom.yaml"

  art_73_incident_reporting:
    enabled: true
    reporting_channel: "security@empresa.com"
    reporting_sla: "72 horas"
    components_covered:
      - "ai-search-service"
      - "chatbot-soporte"
    incidents_reportable:
      - "Output AI incorrecto que afecta decision del usuario"
      - "Bias detectado en respuestas"
      - "Fuga de datos via componente AI"
      - "Indisponibilidad del servicio AI >4h"

11.3 Checklist EU AI Act para brownfield

• Clasificar cada componente ADDED segun nivel de riesgo EU AI Act
• Documentar transparencia Art.50 en cada punto de contacto AI
• Configurar reporte de incidentes Art.73 para componentes AI
• AIBOM generado y actualizado (aibom-generator.py)
• Compliance matrix actualizada con seccion EU AI Act

---

12. MEDIR MODERNIZACION CON DORA METRICS

v7.3.0: Usar DORA + SPACE metrics para medir el progreso de la modernizacion brownfield y la atribucion de AI en las mejoras.

12.1 DORA baseline antes de adopcion

Antes de adoptar el framework, capturar el estado actual de las metricas DORA:

# Capturar baseline de metricas DORA del proyecto legacy
python3 baseline/scripts/dora-metrics.py \
  --repo . \
  --period 90 \
  --output project/F09_operations/dora_baseline.json \
  --ai-attribution

El script dora-metrics.py calcula desde el historial de git:

• Deployment Frequency: Frecuencia de deploys al ambiente de produccion
• Lead Time for Changes: Tiempo desde commit hasta deploy
• Change Failure Rate: Porcentaje de deploys que causan incidentes
• Time to Restore Service: Tiempo promedio de recuperacion

12.2 Tracking de mejora durante modernizacion

Ejecutar metricas periodicamente para medir el impacto de la adopcion:

# Metricas despues de 30 dias de adopcion
python3 baseline/scripts/dora-metrics.py \
  --repo . \
  --period 30 \
  --compare project/F09_operations/dora_baseline.json \
  --ai-attribution \
  --output project/F09_operations/dora_month1.json

12.3 AI Attribution en DORA

El flag --ai-attribution agrega metricas especificas de AI:

• AI-assisted commits: Porcentaje de commits con co-author AI
• AI component deploy frequency: Frecuencia de deploy de componentes ADDED vs EXISTING
• AI failure rate: Change failure rate de componentes AI vs legacy
• AI lead time: Lead time de features AI vs features tradicionales

Esto permite responder: “La adopcion de AI esta mejorando o empeorando nuestras metricas?“

12.4 Dashboard de modernizacion

# project/F09_operations/factory_dashboard.yaml (seccion brownfield)
brownfield_metrics:
  dora_baseline_date: "2026-03-20"
  dora_current:
    deployment_frequency: "2/semana"      # era: 1/semana
    lead_time_for_changes: "2 dias"       # era: 5 dias
    change_failure_rate: "8%"             # era: 12%
    time_to_restore: "45 min"             # era: 2 horas

  modernization_progress:
    components_total: 15
    components_existing: 10
    components_added: 4
    components_removed: 1
    ai_coverage: "27%"                    # componentes AI / total

---

13. PROCEDIMIENTO DE MODERNIZACION LEGACY

v7.3.0: Procedimiento completo de 4 fases para modernizar un sistema legacy usando el framework, scripts de enforcement y FABs autonomos.

13.1 Fase 0 — Assessment (1-2 dias)

Evaluacion completa del sistema legacy antes de iniciar la modernizacion:

# Paso 1: Instalar framework en el proyecto existente
cd mi-proyecto-existente
/ruta/baseline/scripts/init-brownfield.sh "Mi Proyecto" "mi-proyecto"

# Paso 2: Escaneo de seguridad del codebase legacy
python3 baseline/scripts/sast-sca-scanner.py \
  --project-dir . \
  --output project/F08_security/sast_sca_initial.json

# Paso 3: Verificacion OWASP ASI (si hay componentes AI existentes)
python3 baseline/scripts/owasp-asi-checker.py \
  --project-dir . \
  --output project/F08_security/owasp_asi_initial.json

# Paso 4: Capturar baseline de DORA metrics
python3 baseline/scripts/dora-metrics.py \
  --repo . \
  --period 90 \
  --output project/F09_operations/dora_baseline.json

Entregables Fase 0:

• project-config.yaml con brownfield: true y stack existente
• Reporte SAST/SCA del codebase legacy
• Reporte OWASP ASI (si aplica)
• Baseline de metricas DORA

13.2 Fase 1 — Strangler Fig Setup (1 semana)

Documentar el estado actual y preparar la infraestructura de coexistencia:

FASE 1 — ENTREGABLES
─────────────────────
1. F01: problem_statement.yaml
   - Problema original del sistema
   - Objetivo de la modernizacion
   - Criterios de exito medibles

2. F04: ai_partition_map.yaml
   - TODOS los componentes marcados como EXISTING
   - Componentes candidatos a AI marcados como NEEDS_REVIEW
   - Dependencias entre componentes documentadas

3. .claude/mcp_config.json
   - MCP server del framework configurado
   - MCP wrappers para APIs legacy (si aplica)
   - MCP security audit ejecutado

4. Compliance baseline
   - compliance_matrix.yaml del estado actual
   - EU AI Act risk classification de componentes planificados

Criterios para pasar a Fase 2:

• problem_statement.yaml aprobado por stakeholder
• ai_partition_map.yaml con todos los componentes existentes
• Baseline DORA metrics capturado
• SAST/SCA sin vulnerabilidades criticas (o plan de mitigacion)

13.3 Fase 2 — Modernizacion Incremental (continuo)

Implementar componentes AI incrementalmente, usando intents y FABs:

POR CADA COMPONENTE A MODERNIZAR:
──────────────────────────────────

1. Crear intent document
   intent/intent-add-[componente].yaml
   - Objetivo del componente AI
   - Criterios de aceptacion
   - Riesgo y rollback plan

2. Ejecucion FAB (si Factory OS esta habilitado)
   - FAB ejecuta F01→F10 para el componente
   - Checkpoints cada 60 min
   - fab-gate-check.py valida cada fase

3. Gate check incremental
   bash baseline/scripts/gate-check.sh \
     --project-dir . --track lean --brownfield

4. Actualizar ai_partition_map.yaml
   - Componente cambia de NEEDS_REVIEW → ADDED
   - Feature flag documentado
   - Fallback al legacy configurado

5. Deploy con feature flag
   - Canary: 5% → 25% → 50% → 100%
   - Monitoring comparativo (AI vs legacy)
   - Rollback automatico si error rate > threshold

Herramientas de enforcement por componente:

# Validar gates del componente nuevo
bash baseline/scripts/gate-check.sh --project-dir . --track lean --brownfield

# Evaluar compliance del componente AI
python3 baseline/scripts/compliance-linter.py --project-dir . --brownfield

# Verificar seguridad MCP si el componente expone/consume MCP
python3 baseline/scripts/mcp-security-audit.py --config .claude/mcp_config.json

# Generar AIBOM actualizado
python3 baseline/scripts/aibom-generator.py --project-dir . --output project/F08_security/aibom.yaml

13.4 Fase 3 — Cutover (por componente)

Cuando un componente AI esta estable y los gates pasan:

CUTOVER POR COMPONENTE
──────────────────────
1. Verificar gates completos
   - Gate A (Strategy): ✅
   - Gate C (Architecture): ✅ ADR del cambio
   - Gate E (TEVV): ✅ Tests pasan, parallel run exitoso
   - Gate F (Operations): ✅ Monitoring activo

2. Reemplazar legacy
   - Feature flag → 100% trafico al componente AI
   - Periodo de observacion (1-2 semanas en 100%)
   - Si estable → remover feature flag

3. Actualizar markers
   - Componente legacy: EXISTING → REMOVED
   - Componente AI: mantener ADDED
   - Timeline de decomission del legacy

4. Regenerar AIBOM
   python3 baseline/scripts/aibom-generator.py \
     --project-dir . \
     --output project/F08_security/aibom.yaml

5. Actualizar DORA metrics
   python3 baseline/scripts/dora-metrics.py \
     --repo . --period 30 \
     --compare project/F09_operations/dora_baseline.json \
     --ai-attribution

13.5 Diagrama del procedimiento completo

  FASE 0: ASSESSMENT          FASE 1: SETUP            FASE 2: INCREMENTAL       FASE 3: CUTOVER
  ─────────────────          ─────────────            ──────────────────        ───────────────
  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────────┐   ┌──────────────────┐
  │ init-brownfield  │    │ problem_statement│    │ Intent por componente│   │ Gates pasan      │
  │ sast-sca-scanner │───▶│ ai_partition_map │───▶│ FAB execution        │──▶│ Feature flag 100%│
  │ owasp-asi-checker│    │ MCP config       │    │ gate-check.sh        │   │ EXISTING→REMOVED │
  │ dora-metrics     │    │ compliance base  │    │ compliance-linter    │   │ AIBOM regenerate │
  └─────────────────┘    └─────────────────┘    │ mcp-security-audit   │   │ DORA metrics     │
                                                 └──────────────────────┘   └──────────────────┘
                                                          │                          │
                                                          └──── repetir ─────────────┘
                                                          (por cada componente)

---

14. ANTI-PATRONES

Anti-patron	Problema	Solucion
Big Bang adoption	Intentar documentar todo a la vez	Gradual: semana 1 minimo, luego expandir
Framework police	Bloquear deploys por falta de artefactos	Warn, no block. Adopcion es incremental
Rewrite trap	Querer reescribir todo para que “cumpla”	Documentar y envolver, no reescribir
Phantom specs	Inventar specs que no reflejan la realidad	Generar desde codigo existente
AI everywhere	Agregar AI a todo sin evaluar valor	Evaluacion §4.4 antes de cada componente
Legacy shame	Tratar el codigo viejo como inferior	El legacy funciona; el framework lo complementa
Flag cemetery	Feature flags que nunca se limpian	Revisar flags mensualmente, eliminar los estables

---

15. CHECKLIST DE ADOPCION BROWNFIELD

Dia 1 — Bootstrap

• Ejecutar init-brownfield.sh (o setup manual)
• project-config.yaml con brownfield: true y stack existente
• .claudeignore configurado para excluir legacy pesado del contexto

Semana 1 — Minimo

• F01: problem_statement.yaml con estado actual
• F04: Al menos 1 ADR retroactivo (adr_001_stack_selection.md)
• F04: ai_partition_map.yaml con markers EXISTING/ADDED
• F08: compliance_matrix.yaml basica

Semana 2-3 — Contratos

• F05: OpenAPI spec generada desde codigo existente
• F02: Capability map (3-5 capacidades principales)
• F09: Operating baseline documentado

Mes 1 — Primera capacidad AI

• Candidato AI elegido (evaluacion §4.4)
• Feature flag implementado
• Tests de contrato: legacy y nuevo compatibles
• Deploy en paralelo con monitoring

Continuo

• DISCOVERIES.md actualizado con learnings
• ai_partition_map.yaml actualizado con cada cambio
• Gates revisados trimestralmente

---

16. REFERENCIAS

• Martin Fowler, “Strangler Fig Application” (2004, aplicado a AI 2026)
• OpenSpec delta markers — marcado de cambios en specs existentes
• EPAM ADLC — AI Development Lifecycle para modernizacion
• framework/core/F00_Foundation/CORE_F00_Multi_Track_Execution.md — Tracks
• framework/core/F04_.../CORE_F04_Software_Survival_Assessment.md — 6 Levers
• framework/guides/Context_Engineering_Guide.md — Context layers
• framework/guides/Platform_Integration_Guide.md — Kiro IDE y multi-IDE setup para brownfield
• scripts/mcp-security-audit.py — Auditoria de seguridad MCP para wrappers legacy
• scripts/aibom-generator.py — Generacion automatica de AI Bill of Materials
• scripts/dora-metrics.py — Metricas DORA + SPACE con atribucion AI
• scripts/owasp-asi-checker.py — Verificacion OWASP ASI para componentes AI
• OWASP MCP Top 10 (2025) — Riesgos de seguridad en integraciones MCP
• EU AI Act, Art. 50 (Transparencia) y Art. 73 (Reporte de incidentes)

Nota multi-IDE (v7.3.0): Para configurar brownfield en entornos con Kiro IDE, Cursor u otros IDEs AI-native ademas de Claude Code, consultar framework/guides/Platform_Integration_Guide.md. La guia incluye mapeo de context layers entre plataformas y configuracion de hooks compartidos.

---

Guia operativa del AI-First Engineering Framework v7.3.0 — Modo Brownfield. Incluye Data Governance, MCP config, compliance enforcement, OWASP MCP Top 10, AIBOM, EU AI Act, DORA metrics y procedimiento de modernizacion legacy. Documentar primero, envolver despues, evolucionar siempre