Codex em sistemas legados: mapeie antes de alterar

Introdução

Quando um sistema existe há anos, uma mudança pequena pode passar por scripts, integrações e regras que não estão reunidos em um único lugar. Alterar o fluxo antes de entender essas relações aumenta a chance de mudar um comportamento que ainda é necessário.

Um agente de programação pode ajudar a percorrer os arquivos do projeto e organizar o que encontrou. Para isso, comece com uma tarefa de leitura e delimite um fluxo. O objetivo inicial é produzir um mapa que alguém da equipe possa conferir, não pedir ao agente que substitua o sistema.

Escolha um fluxo que possa ser delimitado

Em vez de pedir “explique todo o sistema”, escolha uma operação que tenha começo e resultado identificáveis. Pode ser a abertura de uma solicitação, a atualização de um cadastro ou o envio de dados para outro sistema.

Registre o que caracteriza esse fluxo:

• qual evento ou operação inicia o processamento;
• quais arquivos, componentes ou serviços parecem participar;
• quais dados entram e quais resultados são esperados;
• que integrações, permissões e regras de negócio podem ser afetadas.

O Codex pode analisar o repositório ao qual foi conectado, mas não conhece automaticamente configurações de produção, tabelas fora do projeto, conversas da equipe ou comportamentos que não estejam documentados. Anote essas lacunas para confirmar com as pessoas responsáveis pelo sistema.

Peça primeiro um inventário verificável

Na primeira tarefa, peça uma análise sem alterações. Solicite referências a arquivos e trechos de código para que outra pessoa consiga acompanhar o caminho descrito. Também peça que o agente diferencie o que encontrou no repositório do que está inferindo.

Um pedido inicial pode ser adaptado assim:

Analise o fluxo [nome do fluxo] neste repositório. Não altere arquivos. Identifique os pontos de entrada e acompanhe o caminho até a saída ou efeito principal. Liste os arquivos e símbolos relevantes, os dados de entrada e saída, as regras de negócio visíveis, as chamadas externas, as permissões, o tratamento de erros e os testes encontrados. Para cada conclusão, cite o arquivo e o trecho que a sustenta. Separe fatos observados de inferências e encerre com as perguntas que dependem de documentação externa ou confirmação da equipe.

Adapte os termos ao projeto. Em uma aplicação Fluig, por exemplo, pode ser útil pedir que o agente procure eventos de processo, formulários, datasets e integrações se esses elementos estiverem presentes no repositório. Se não encontrar algum deles, o resultado deve registrar essa ausência em vez de presumir como o ambiente funciona.

Transforme o inventário em um mapa de trabalho

Leia o resultado junto com o código referenciado. Confirme se o caminho de execução está completo e se há configuração, consulta ao banco ou chamada de serviço fora dos arquivos analisados. Registre as dúvidas que o código não resolve, como quem pode iniciar uma operação ou qual sistema mantém o dado como fonte oficial.

Para deixar a revisão útil, organize o material em uma página curta com:

1. objetivo e limite do fluxo;
2. sequência dos componentes e arquivos encontrados;
3. entradas, saídas e efeitos colaterais;
4. regras e contratos que precisam continuar válidos;
5. lacunas, riscos e perguntas ainda abertas.

O artigo Como iniciar processo recorrente por dataset? é um exemplo do acervo que descreve um fluxo de trabalho associado ao Fluig. Conteúdos desse tipo podem servir como contexto para escolher o que mapear, desde que a implementação atual também seja conferida no repositório e no ambiente responsável.

Aplicação a um processo do Fluig

O acervo também tem um tutorial sobre atualizar o script de um processo no Fluig. Ele descreve eventos de processo, versões e uma alternativa de ajuste direto no banco, indicada no próprio texto apenas para testes. Como o artigo é de 2020, use-o como referência histórica e confirme o procedimento compatível com a versão e o ambiente atuais antes de qualquer intervenção.

Para começar uma análise com um agente de programação, delimite o processo e peça uma leitura sem alterações. Por exemplo:

Analise o processo [nome], na versão [versão], neste repositório Fluig. Não altere arquivos nem execute comandos que modifiquem dados. Localize o evento de processo envolvido e siga as dependências encontradas em scripts, formulários, datasets e serviços externos. Para cada achado, cite o arquivo e o símbolo correspondente. Separe fatos visíveis no código de inferências, registre as configurações que dependem do ambiente e liste os testes e as perguntas que ainda precisam de confirmação da equipe. Se algum componente não estiver no repositório, registre a ausência em vez de presumir seu comportamento.

Compare o mapa com o ambiente responsável e com a documentação da versão em uso. Essa primeira etapa serve para entender o fluxo; uma proposta de mudança deve vir depois, com escopo e critérios de validação definidos.

Defina como conferir o comportamento

Antes de alterar o fluxo, escolha cenários que mostrem o que deve acontecer. Inclua o caminho normal, entradas inválidas, falhas de integração e permissões relevantes quando se aplicarem. Use testes existentes ou prepare exemplos de entrada e saída que possam ser comparados.

O guia oficial da OpenAI sobre modernização com Codex usa um fluxo piloto e separa inventário, desenho da solução e plano de validação. Para migrações, também recomenda definir como comparar o comportamento antigo e o novo. Esse recorte ajuda a fazer uma mudança por vez e cria evidências para revisar o resultado.

Só então planeje a alteração

Com o mapa e os critérios de validação revisados, transforme a próxima etapa em uma tarefa pequena. Peça ao agente que proponha o plano e os arquivos que pretende mudar antes de implementar. Confira se o plano respeita contratos externos, permissões e regras que a equipe confirmou.

Se o objetivo for modernizar um componente, mantenha claro o que fica fora do piloto. Uma mudança limitada facilita investigar diferenças e voltar atrás se o comportamento não corresponder ao esperado. Depois da implementação, revise o diff e execute as validações definidas para o fluxo.

Conclusão

Use o Codex primeiro como apoio para entender uma parte do sistema legado. Escolha um fluxo, peça um inventário com referências verificáveis e confirme as lacunas com quem conhece o ambiente.

Quando o mapa e os critérios de comportamento estiverem claros, avance para uma mudança delimitada e valide o resultado. Assim, o agente ajuda na exploração e na execução sem substituir o conhecimento do negócio nem a revisão da equipe.

Referências

• Modernizing your Codebase with Codex — OpenAI — fluxo piloto, inventário e validação de paridade; consulta em 12 out. 2026.