Projeto Brownfield

Entrando ou aprimorando um codebase existente com o AIOS. Este guia cobre o processo de avaliacao Brownfield Discovery de 10 fases e as tres variantes de implementacao para projetos existentes.

Quando Usar um Workflow Brownfield

Use um workflow brownfield quando estiver trabalhando com um codebase existente. Cenarios tipicos incluem:

• Migrar projetos do Lovable, v0.dev ou outro codigo gerado por IA
• Auditar e modernizar um codebase legado
• Adicionar novas funcionalidades significativas a uma aplicacao existente
• Due diligence tecnica pre-investimento
• Onboarding em um projeto construido por outra equipe

Brownfield Discovery: Avaliacao de 10 Fases

Antes de fazer alteracoes em um projeto existente, execute o workflow Brownfield Discovery para produzir uma avaliacao abrangente de divida tecnica. Este e o primeiro passo recomendado para qualquer engajamento brownfield.

*workflow brownfield-discovery

Duracao estimada: 4-8 horas dependendo da complexidade do projeto.

Coleta de Dados (Fases 1-3)

Rascunho e Validacao (Fases 4-7)

Se o QA gate retornar NEEDS WORK, o processo retorna a Fase 4 para retrabalho. O architect incorpora o feedback do QA, e o rascunho passa por revisoes especialistas novamente.

Finalizacao (Fases 8-10)

Estrutura de Saida do Discovery

Apos a conclusao do workflow de descoberta, seu diretorio docs/ contera:

docs/
  architecture/
    system-architecture.md        # Fase 1
  frontend/
    frontend-spec.md              # Fase 3
  reviews/
    db-specialist-review.md       # Fase 5
    ux-specialist-review.md       # Fase 6
    qa-review.md                  # Fase 7
  prd/
    technical-debt-DRAFT.md       # Fase 4
    technical-debt-assessment.md  # Fase 8
  reports/
    TECHNICAL-DEBT-REPORT.md      # Fase 9
  stories/
    epic-technical-debt.md        # Fase 10
    story-1.1-*.md

Variantes de Implementacao

Apos o discovery (ou para aprimoramentos que nao exigem uma descoberta completa), o AIOS oferece tres workflows de implementacao brownfield:

Classificacao de Enhancement

Os workflows brownfield full-stack e service comecam com uma etapa de classificacao pelo @analyst:

Para enhancements grandes, o workflow verifica a adequacao da documentacao existente. Se a documentacao estiver desatualizada ou ausente, @architect *document-project e executado primeiro.

Fases de Implementacao

Todas as variantes de implementacao brownfield compartilham estas fases:

1. Planejamento — @architect analisa o sistema existente; @pm cria um PRD brownfield; @architect cria arquitetura (se mudancas arquiteturais forem necessarias)
2. Validacao — @po valida todos os artefatos com o po-master-checklist; problemas sao corrigidos pelo agente relevante
3. Ciclo de Desenvolvimento — @po fragmenta documentos; @sm cria stories; @dev implementa; @qa revisa
4. Finalizacao — Retrospectiva de epic opcional pelo @po

Consideracoes Especificas de Brownfield

Diferente dos workflows greenfield, os workflows brownfield incluem salvaguardas adicionais:

• Validacao de seguranca de integracao — @po verifica que mudancas nao quebrarao funcionalidades existentes
• Avaliacao de risco de regressao — @qa avalia o risco de regressoes
• Feature flags — Considere rollout gradual para mudancas significativas
• Padroes existentes — Decisoes de arquitetura respeitam padroes de codigo existentes quando possivel

Comandos de Inicio Rapido

# Avaliacao completa de divida tecnica (primeiro passo recomendado)
*workflow brownfield-discovery

# Aprimoramento full-stack
*workflow brownfield-fullstack

# Aprimoramento de servico backend
*workflow brownfield-service

# Aprimoramento de frontend/UI
*workflow brownfield-ui

# Rapido: criar uma unica story brownfield
@pm *brownfield-create-story

# Rapido: criar um pequeno epic brownfield (1-3 stories)
@pm *brownfield-create-epic

Priorizacao Apos o Discovery

Apos completar o Brownfield Discovery, trabalhe com @po para priorizar stories com base em:

• Impacto no negocio — Quais dividas afetam mais os usuarios
• Risco tecnico — Vulnerabilidades de seguranca e problemas de integridade de dados primeiro
• Dependencias — Resolva dividas bloqueantes antes das dependentes
• Quick wins — Itens de baixo esforco e alto impacto para gerar momentum

Solucao de Problemas