| name | modernizacao-legado |
| description | Metodologia Codex para arqueologia de dominio e modernizacao de sistemas legados. Use quando a tarefa envolver sistema legado, codigo antigo em producao, auditoria tecnica, extracao de regras de negocio a partir de codigo e banco, avaliacao de camada intermediaria/MVC parcial, migracao, reescrita para stack moderna, plano conceitual de migracao de dados, ou reconstrucao recomendada em PHP 8.4+ / Laravel / Filament. Produz documentacao tecnica rastreavel; nao altera codigo legado, banco, configuracao nem dados. |
Modernizacao de Sistemas Legados
Use esta skill para conduzir uma missao de arqueologia de dominio: observar o sistema real, separar regra de negocio de acidente de implementacao e produzir documentacao suficiente para reconstruir o sistema em uma arquitetura moderna.
A saida normal vive em docs/legacy-modernization/. A missao e documental: nao editar codigo legado, nao alterar banco, nao executar DML/DDL e nao tratar comportamento defeituoso como requisito.
Contrato Operacional
- Comecar por reconhecimento read-only: arvore do projeto, pontos de entrada, stack, configuracoes mascaradas, banco disponivel e camada intermediaria se existir.
- Registrar progresso em
docs/legacy-modernization/_progresso.md; toda retomada le esse arquivo antes de continuar.
- Escrever documentos incrementalmente. Nao acumular uma fase inteira apenas no contexto.
- Citar evidencia em cada conclusao relevante:
arquivo:linha, tabela.coluna, query de leitura, contagem ou amostra anonimizada.
- Usar
HIPOTESE, VALIDAR COM OWNER, FORTE INDICIO ou DECISAO CANONICA quando a confianca importar.
- Preservar dados pessoais e segredos: anonimizar exemplos e mascarar credenciais.
- Para missoes longas, manter plano visivel e validar consistencia entre documentos antes do fechamento.
Parametros Da Missao
Inferir do repositorio sempre que possivel; perguntar apenas quando a resposta for bloqueante:
- raiz do legado;
- local de camada intermediaria, por exemplo
app/, se existir;
- forma de acesso ao banco: dump, replica, cliente read-only ou phpMyAdmin;
- se a base e producao; producao exige autorizacao explicita;
- stack de destino;
- diretorio de documentacao, padrao
docs/legacy-modernization/;
- idioma, padrao idioma do usuario.
Referencias Sob Demanda
- Antes de analisar banco ou dump SQL, ler
references/inspecao-banco.md.
- Se a stack de destino for PHP 8.4+ / Laravel / Filament, ler
references/perfil-laravel-filament.md antes das etapas 7, 8, 9 e ao complementar testes.
- Para executar a missao como persona especializada local, usar tambem
.codex/agents/arquiteto-modernizacao-legado.md quando existir no workspace.
Separacoes Obrigatorias
Nunca misturar:
regra de negocio real != implementacao legada
fluxo operacional real != ordem das telas
entidade de dominio != tabela existente
campo existente != campo necessario
camada intermediaria != arquitetura final
SQL legado != regra canonica
tela antiga != caso de uso
comentario no codigo != documentacao confiavel
Marcadores
Confianca e decisao: DECISAO CANONICA, FORTE INDICIO, HIPOTESE, REGRA CONFLITANTE, LEGADO A PRESERVAR, LEGADO A DESCARTAR, REESCREVER, VALIDAR COM OWNER, RISCO CRITICO.
Classificacao de legado: REGRA CANONICA, COMPORTAMENTO LEGADO, GAMBIARRA, DUPLICIDADE, RISCO, CANDIDATO A DESCARTE, CANDIDATO A REESCRITA, CANDIDATO A PRESERVACAO.
Classificacao de regras: REGRA CANONICA, REGRA PROVAVEL, HIPOTESE, REGRA DUPLICADA, REGRA CONFLITANTE, REGRA OBSOLETA, REGRA PERIGOSA.
Mapeamento com a versao Claude (acentuacao plena -> ASCII puro): CANÔNICA -> CANONICA, PRESERVAÇÃO -> PRESERVACAO, PROVÁVEL -> PROVAVEL, INDÍCIO -> INDICIO, CRÍTICO -> CRITICO. Mesmo semantico, representacao diferente por encoding policy.
Etapas E Entregaveis
Preservar a numeracao porque ela codifica dependencias. As etapas 1-3 podem intercalar; a etapa 4 depende delas; etapas 5-6 dependem da 4; etapas 7+ dependem de 5-6. Escrever 00-resumo-executivo.md por ultimo.
- Reconhecimento e plano: criar
README.md e _progresso.md.
01-inventario-legado.md: paginas, includes, autenticacao, permissoes, formularios, relatorios, uploads, rotinas, integracoes.02-banco-de-dados-atual.md: tabelas, colunas, volumes, estados reais, relacionamentos explicitos e implicitos.03-camada-intermediaria.md: classes, responsabilidades reais, divergencias e reaproveitamento possivel.04-comparativo-legado-banco-intermediario.md: funcionalidade x codigo x banco x camada intermediaria x regra canonica.05-dominio-canonico.md: modulos, entidades, agregados, value objects, enums, eventos e de-para de nomes. Detalhes em references/etapa-5-dominio-canonico.md.06-regras-de-negocio.md: regras com evidencia, criticidade, risco e recomendacao. Detalhes em references/etapa-6-regras-negocio.md.07-modelagem-banco-novo.md: modelo novo orientado a dominio, nao copia do schema atual.08-camada-de-aplicacao.md: actions, services, policies, queries, DTOs, eventos e testes necessarios.09-ui-administrativa.md: UI derivada do dominio; telas legadas sao evidencia, nao molde.10-perfis-acesso-auditoria.md: matriz de permissoes, acoes criticas, justificativas e trilha.11-plano-conceitual-migracao.md: de-para, transformacoes, saneamento, validacoes e riscos.12-testes.md: testes de dominio, regras, autorizacao, relatorios, calculos, migracao e regressao observada.13-roadmap-modernizacao.md: fases, dependencias, tarefas pequenas, entregaveis, riscos e aceite.14-decisoes-arquiteturais.md: ADRs com contexto, decisao, alternativas rejeitadas e consequencias.15-riscos-pontos-abertos.md: riscos, perguntas ao owner e pendencias consolidadas.- Fechamento:
00-resumo-executivo.md, README atualizado e verificacao de consistencia.
Modelos De Registro
Os 6 modelos (item de inventario, tabela, classe intermediaria, entidade canonica, regra, ADR) estao detalhados em references/modelos-registro.md. Carregue esse arquivo ao iniciar a etapa correspondente.
Disciplina Codex
- Usar
rg/rg --files para reconhecimento.
- Usar
apply_patch para escrever documentacao gerada no workspace.
- Nao alterar codigo de producao, dados, migracoes, seeds ou configuracao do legado.
- Se uma validacao precisar de banco de producao, parar e pedir autorizacao explicita.
- Se encontrar credenciais, nao transcrever; registrar apenas a existencia mascarada.
- Quando delegar a subagente/CLI, passar escopo fechado e exigir escrita direta no documento-alvo; revisar antes de integrar.
- Encoding policy: esta skill e suas references usam ASCII puro (sem acentos). Marcadores canonicos sao grafados sem acentuacao (
CANONICA, PRESERVACAO, PROVAVEL, INDICIO). A versao Claude do mesmo skill usa acentuacao plena; isso e intencional e o mapeamento Claude->Codex vive na secao "Marcadores" deste arquivo. Qualquer divergencia alem das listadas ali e drift a ser corrigido.
Fechamento
A missao esta pronta quando outra pessoa consegue, lendo apenas docs/legacy-modernization/, responder: o que o sistema faz, quais regras sao reais, quais sao acidentais, quais tabelas sustentam cada funcionalidade, quais entidades devem existir na arquitetura nova, o que migrar, sanear ou descartar, o que aproveitar da camada intermediaria, como testar e por onde comecar a reconstrucao.
