Um agente de IA trabalha sem todo o contexto do código?

Um agente de IA que vê apenas um ficheiro pode fazer uma alteração local convincente e, ainda assim, danificar o sistema. A falha raramente é uma sintaxe errada ou uma ramificação obviamente incorreta. É um chamador em falta, uma regra codificada nos dados, um trabalho noturno com outro ponto de entrada ou uma dependência operacional que nunca aparece no ficheiro revisto.

Por isso, os limites do contexto determinam se a programação com agentes funciona em software legado. A unidade de trabalho útil é o comportamento que atravessa programas, scripts, objetos de base de dados, agendamentos, ficheiros e procedimentos operacionais. Um ficheiro é apenas um dos locais onde parte desse comportamento foi escrita.

Já vi alterações impecáveis passarem pela revisão porque todas as linhas visíveis faziam sentido. A falha surgiu depois, quando um ficheiro de controlo selecionou um modo antigo, um programa com nome dinâmico recebeu um parâmetro numa posição que ninguém documentou ou uma repetição do lote encontrou registos que o percurso online nunca produz. Editar linhas com mais cuidado não resolve esta classe de problema. O agente tem primeiro de descobrir o sistema que rodeia a linha.

Um ficheiro não é a unidade de comportamento

O comportamento legado raramente cabe no ficheiro que parece ser o seu dono. Um programa COBOL pode calcular um valor, mas o JCL escolhe o conjunto de dados de entrada, um passo SORT altera a ordem dos registos, um copybook fixa as posições dos campos e um programa posterior interpreta o byte de estado da saída. Ler apenas o cálculo dá ao agente uma história coerente, mas incompleta.

O mesmo padrão aparece fora dos mainframes. Um formulário VB6 chama um componente COM cujo registo seleciona uma versão. Um controlador PHP inclui um ficheiro de configuração montado por scripts de implementação. Um programa RPG lê uma área de dados e chama outro programa por um nome guardado num campo. Um pacote PL/SQL depende de um trigger que altera a linha depois de o pacote a escrever. Nenhuma destas dependências tem de se parecer com uma importação normal.

Esta distinção é relevante: proximidade no código-fonte não significa propriedade do comportamento. Duas funções no mesmo ficheiro podem não ter relação em execução, enquanto um membro JCL e um parágrafo COBOL em bibliotecas diferentes formam uma única operação indivisível em produção. Se um agente classificar o contexto sobretudo pela distância entre diretórios, por instruções de importação ou por identificadores iguais, vai ignorar dependências que as operações consideram evidentes.

Antes de alterar um ficheiro, é preciso perguntar o que inicia este comportamento, que entradas selecionam as suas ramificações, que estado persistente lê ou escreve e quem consome o resultado. Essas perguntas produzem um limite do sistema. Pode incluir doze ficheiros ou doze mil. O tamanho acompanha o comportamento, não o separador aberto no editor.

A consequência prática é direta. Uma ferramenta que não consegue pesquisar e raciocinar em todo o repositório, definições de compilação, controlo de trabalhos, esquemas e testes não deve fazer uma alteração autónoma num sistema legado. Pode explicar um parágrafo ou preparar um teste unitário. Não consegue determinar o impacto de uma edição em produção.

Os pontos de chamada ficam fora do grafo de importações

Um grafo de chamadas criado a partir de chamadas explícitas de funções é útil, mas não é o grafo de chamadas do sistema. Sistemas legados resolvem trabalho através de strings, tabelas, agendadores, código gerado, passos de ligação, ficheiros de comandos e convenções. A aresta em falta é muitas vezes a que interessa.

A documentação ILE da IBM dá um exemplo claro. Uma aplicação IBM i pode usar chamadas estáticas de procedimentos, resolvidas quando o programa é ligado, ou chamadas dinâmicas de programas cujo nome de destino é resolvido em execução. Uma análise apenas do código-fonte consegue muitas vezes encontrar a referência estática. Uma chamada dinâmica através de um identificador pode depender de um valor carregado de um ficheiro, mensagem, área de dados ou parâmetro. Pesquisar o nome do programa chamado não encontra um valor que a produção só constrói mais tarde.

O mesmo ponto cego aparece em formas comuns:

• Um agendador invoca um script de shell que inicia um programa com um nome alternativo.
• Uma tabela da base de dados associa códigos de transação a nomes de processadores.
• A reflexão carrega uma classe com o nome definido na configuração.
• Uma macro de folha de cálculo chama um método COM através de um objeto com ligação tardia.
• JCL gerado insere o nome de um procedimento apenas depois da substituição simbólica.

É habitual confundir acessibilidade estática com dependência em execução. A acessibilidade estática pergunta se o texto-fonte ou os metadados compilados expõem um caminho. A dependência em execução pergunta se a produção pode encaminhar dados ou controlo por esse caminho em algum estado. Tratar a primeira como prova da segunda produz um diagrama atraente e incompleto.

Um agente precisa de provas das duas. Deve extrair referências explícitas e depois examinar strings literais, chaves de configuração, passos de trabalhos, metadados de ligação, tabelas de despacho na base de dados e rastos de produção. Se não conseguir resolver um destino dinâmico, deve registar uma aresta não resolvida com a expressão e as suas possíveis origens. O silêncio não é uma resolução válida.

Uma pesquisa básica no repositório mostra rapidamente como um símbolo supostamente isolado sai do seu módulo:

rg -n -uu 'CALC-TAX|CALCTAX|calc_tax' .
rg -n -uu 'EXEC PGM=|CALL +[A-Z0-9-]+|CALLP|PROCEDURE DIVISION' .
rg -n -uu 'handler|program_name|transaction_code' config db jobs src

Uma saída real contém caminhos e números de linha, como jobs/NIGHTTAX.jcl:18://STEP20 EXEC PGM=CALCTAX. O artefacto não é sofisticado, mas obriga o revisor a inspecionar chamadores para além do ficheiro aberto. Um agente sério deve criar automaticamente uma versão mais rica deste mapa e guardar as provas por trás de cada aresta.

As regras de negócio viajam nos dados

Muitas regras legadas são valores, formatos e sequências, e não funções com nome. Um agente pode preservar todas as condições visíveis e mesmo assim alterar o resultado se interpretar mal um campo decimal compactado, uma data sentinela, um tipo de registo, uma sequência de ordenação ou o significado de um espaço em branco.

Considere um programa noturno de comissões. O código diz que a classe de conta P recebe uma isenção. A classe não vem diretamente da linha da conta. Uma extração anterior associa códigos de produto através de uma tabela de controlo, escreve uma classe de um byte na posição 47 e ordena as exceções antes dos registos normais. As operações substituem essa tabela antes do fecho do mês. A regra que o revisor julga estar numa única instrução IF atravessa, na verdade, uma tabela, um formato de ficheiro, um contrato de ordenação e um procedimento operacional.

É aqui que agentes limitados a um ficheiro produzem transliterações plausíveis. Convertem corretamente o IF, definem um enum agradável e leem um CSV para um serviço moderno. Depois removem espaços ou interpretam um campo vazio como null. O programa original comparava um espaço em branco de largura fixa, por isso um subconjunto de contas segue outra ramificação. Todos os testes unitários derivados da função reescrita passam porque repetem a nova interpretação.

Um inventário do sistema deve, portanto, incluir a semântica dos dados, não apenas nomes de esquemas. Para cada registo ou tabela numa fronteira, registe posições de campos, codificações, valores predefinidos, tratamento de null, formatos de sinal, arredondamento, ordem, tratamento de duplicados e política para registos inválidos. Se um valor de controlo mudar fora do controlo de versões, registe como é promovido e que trabalho o lê.

Não presuma que um tipo moderno é mais correto do que a representação antiga. Converter 9(7)V99 COMP-3 para um tipo decimal pode fazer sentido, mas só depois de preservar escala, sinal, arredondamento, excesso de capacidade e comportamento de entradas malformadas. Substituir uma data de seis caracteres por uma marca temporal pode retirar ambiguidade ao desenho de destino e, ao mesmo tempo, inventar silenciosamente uma regra de século que a origem nunca teve.

O agente também tem de ligar escritores a leitores. Um campo que parece não ser usado no produtor pode ser preenchimento posicional necessário a um consumidor três passos depois. Eliminá-lo pode deslocar todos os campos seguintes sem causar erro de compilação. A representação mais segura dessa relação é um contrato explícito com bytes de exemplo e valores analisados, não uma nota em prosa a afirmar que os ficheiros são compatíveis.

O lote noturno é outra aplicação

Um percurso online e um percurso em lote que partilham código continuam a ser aplicações diferentes quando são executados com outras entradas, identidades, horários e regras de recuperação. Passar num teste interativo diz pouco sobre um trabalho que processa estado acumulado depois da meia-noite.

A documentação de z/OS da IBM descreve JCL como o local que indica ao sistema onde encontrar a entrada, como a processar e o que fazer com a saída. As instruções DD ligam os nomes usados pelo programa aos conjuntos de dados reais e especificam pormenores como disposição e formato dos registos. Isso não é embalagem à volta da aplicação. É contexto executável.

Considere uma alteração que acrescenta um estado a uma função de encomendas online. O percurso do pedido escreve H para encomendas retidas, mostra a mensagem certa e passa na revisão. O trabalho noturno de liquidação lê o mesmo ficheiro. O primeiro passo ordena apenas os estados antigos para a entrada da liquidação, enquanto um passo de erro copia todos os restantes para um conjunto de dados temporário com DISP=(NEW,PASS). Um passo posterior só é executado quando uma condição do código de retorno corresponde. O novo estado não entra na liquidação, fica no ficheiro temporário e desaparece quando o trabalho termina normalmente. Nenhum ficheiro-fonte do serviço revisto mostra este resultado.

A falha pode esperar pelo volume ou por um estado do calendário. Um teste diurno usa um registo e uma base de dados limpa. O lote encontra duplicados acumulados durante novas tentativas, fecha uma data contabilística antes do processamento e confirma a transação a cada alguns milhares de registos. Um reinício começa depois do último ponto de controlo, não depois da transação esperada pelo teste. A correção inclui o comportamento de reinício, porque as operações acabarão por repetir um trabalho parcialmente concluído.

Para cada fluxo agendado, o agente deve modelar cinco factos:

1. O acionador, calendário, identidade e ambiente.
2. Os passos ordenados e as condições que os ignoram ou repetem.
3. As entradas e saídas concretas, incluindo conjuntos de dados temporários.
4. O comportamento de confirmação, ponto de controlo, nova tentativa e repetição.
5. A prova que as operações usam para declarar sucesso.

Um código de saída verde pode não ser a condição de sucesso. Algumas equipas aceitam códigos de aviso definidos, inspecionam contagens de registos ou conciliam um total de controlo num relatório posterior. Um agente que só vê código-fonte e testes unitários otimiza o sinal errado.

A configuração executa políticas

A configuração merece a mesma análise que o código-fonte, porque seleciona o comportamento, fornece valores de negócio e liga componentes em execução. Chamar-lhe "apenas configuração" facilita a aprovação de uma alteração sem rever a regra que será realmente executada.

A configuração legada raramente vive num diretório arrumado. Pode ser um parâmetro simbólico de JCL, uma área de dados de IBM i, um ficheiro INI junto de um executável de desktop, uma linha mantida por um formulário Access, um valor do registo, um membro de ambiente ou uma folha de cálculo copiada para uma pasta vigiada. Alguns valores estão no controlo de versões. Outros chegam por ferramentas de implementação ou por um procedimento operacional. O agente tem de encontrar e distinguir ambos.

Imagine que um programa de sinistros escolhe uma rotina de preços numa tabela. O código tem um valor predefinido inofensivo, por isso o agente reescreve e testa essa ramificação. Em produção há linhas regionais que indicam quatro rotinas antigas, uma das quais recebe um argumento extra através de uma memória intermédia partilhada. O novo serviço inicia sem erros e processa os casos predefinidos. O primeiro sinistro dessa região não chama qualquer processador ou chama o novo com um contrato incompleto. O ponto de chamada em falta era uma linha da tabela, não uma linha de código.

Trate os valores de configuração de acordo com o efeito. Um valor que muda o detalhe dos registos tem pouco risco de comportamento. Um valor que escolhe um programa, altera um limiar, controla o arredondamento, concede acesso, define uma versão do formato de ficheiro ou altera a frequência de confirmação pertence ao mapa de impacto. A distinção segue a consequência, não a extensão do ficheiro.

O agente deve responder a quatro perguntas para cada valor que seleciona comportamento:

• Onde é definido o valor e quem o pode alterar?
• Que código o lê e quando acontece essa leitura?
• Que valores apareceram em ambientes reais?
• O que acontece quando está vazio, desatualizado, é desconhecido ou não está disponível?

Os valores predefinidos exigem desconfiança especial. Uma alternativa que torna um teste unitário cómodo pode ocultar uma falha de carregamento da configuração em produção. O sistema de origem pode parar quando falta um membro de controlo, enquanto a reescrita escolhe silenciosamente um valor predefinido. Ambas as implementações produzem uma saída válida para casos configurados, mas os seus contratos de falha são diferentes. Os testes de paridade devem incluir configuração ausente e malformada, não apenas os valores esperados.

Capture uma imagem da implementação junto da revisão do código usada na análise. Sempre que possível, atribua um hash ou versão à exportação do agendador, às tabelas de controlo, ao esquema e aos ficheiros de ambiente. Se o revisor não consegue saber que configuração o agente assumiu, a afirmação de impacto não pode ser reproduzida. Um índice completo do código combinado com configuração de produção desconhecida continua a ser contexto parcial, e o agente deve dizê-lo claramente.

Construa o mapa antes de pedir uma alteração

O agente deve criar um mapa de impacto sustentado por provas antes de propor código. Não é um cartaz de arquitetura. É um conjunto de trabalho composto por nós e arestas ligados a ficheiros, definições, observações em execução e questões por resolver.

Comece pelos pontos de entrada: rotas online, consumidores de mensagens, trabalhos agendados, programas de comandos, procedimentos armazenados, eventos de desktop e comandos de operadores. Depois ligue chamadas de programas, leituras e escritas de ficheiros, acessos a tabelas, artefactos gerados, seleção de configuração e ligações de implementação. Marque as arestas como estáticas, configuradas, observadas ou inferidas. Estas etiquetas impedem que uma suposição ganhe a autoridade de um facto.

Uso um registo compacto para cada alteração proposta:

{
  "change": "add held order status H",
  "entry_points": ["POST /orders/{id}/hold", "NIGHTSET STEP20"],
  "writers": ["OrderStatus.bas", "HOLDORDR.cbl"],
  "readers": ["SETTLE.cbl", "RECON.sql"],
  "contracts": ["ORDER-REC copybook", "status_control table"],
  "unresolved": ["Does restart input retain H records?"],
  "required_evidence": ["online trace", "nightly replay", "reconciliation totals"]
}

Este objeto é intencionalmente desconfortável. Torna visíveis o segundo ponto de entrada e a questão do reinício antes de alguém aprovar a alteração. Os nomes exatos dos campos não interessam. O que importa é obrigar o agente a indicar pontos de entrada afetados, leitores, contratos e provas em falta.

A alternativa popular é a revelação progressiva: entregue ao agente o ficheiro de destino, deixe-o pedir ficheiros relacionados e pare quando disser que tem o suficiente. Poupa tokens e parece eficiente numa demonstração. É errada para descobrir impacto, porque o primeiro ficheiro molda todos os pedidos seguintes. Se não contiver qualquer pista de que existe um agendador, uma tabela de controlo ou um procedimento gerado, o agente nunca os vai pedir.

A revelação progressiva é útil depois da descoberta, quando o agente precisa de texto detalhado para uma parte conhecida do mapa. A própria descoberta exige indexação de todo o repositório e análise entre linguagens. O agente pode concentrar o raciocínio, mas o espaço de pesquisa não pode começar no limite do ficheiro.

O mapa também oferece aos humanos uma melhor superfície de revisão. Um revisor pode questionar uma aresta em falta, pedir provas de uma inferência ou acrescentar um procedimento operacional que não está no repositório. Rever apenas a diferença final obriga a pessoa a reconstruir este mapa mentalmente, precisamente o trabalho em que o agente devia ajudar.

O contexto precisa de camadas, não de um pedido gigante

Contexto do sistema inteiro não significa colar um milhão de linhas num único pedido. Significa que o agente consegue recuperar e analisar o sistema completo através de representações adequadas a perguntas diferentes, sem perder o caminho de volta às provas no código-fonte.

Uma camada contém o inventário: linguagens, unidades de compilação, esquemas, trabalhos, pontos de entrada, ficheiros, procedimentos e fontes de configuração. Outra contém relações como chamadas, leituras, escritas, agendamentos, inclusões, ligações e geração. Uma camada semântica regista contratos e responsabilidades prováveis. As provas de execução acrescentam rastos, exemplos semelhantes aos de produção, registos de trabalhos e destinos de despacho observados.

Estas camadas servem perguntas diferentes. Para mudar o nome de um campo, o agente precisa das definições de formato e de todos os leitores. Para alterar um cálculo, precisa de chamadores, origem dos dados, regras de arredondamento e saídas de comparação. Para dividir um trabalho em lote, precisa de condições dos passos, duração dos recursos temporários, comportamento dos pontos de controlo e recuperação operacional. Nenhuma estratégia fixa de divisão responde às três.

Os resumos ajudam, mas são uma memória intermédia com perdas. Podem dizer ao agente que um programa calcula comissões e omitir a ramificação que só se aplica a transações anuladas durante o fecho. Cada afirmação resumida deve manter referências para trechos concretos do código ou registos de execução. Quando uma alteração toca nessa afirmação, o agente deve reabrir as fontes, em vez de raciocinar apenas a partir do resumo.

A atualidade do contexto também importa. Copybooks gerados, definições da base de dados, exportações do agendador e configuração implementada podem divergir do repositório principal. O agente deve mostrar a imagem que analisou. Misturar um ficheiro COBOL atual com a exportação JCL do trimestre anterior cria um sistema sintético que nunca foi executado em lado nenhum.

A análise do repositório também não consegue saber tudo. Um operador pode editar um membro de controlo durante um incidente. Um parceiro pode enviar variantes de registos sem documentação. Uma aplicação de desktop pode depender do registo da máquina. A resposta correta é identificar a lacuna e exigir provas de execução, não preenchê-la com uma suposição confiante.

Esta abordagem em camadas controla o custo sem sacrificar o âmbito. Índices amplos identificam candidatos de forma barata. A recuperação direcionada fornece o código exato quando o agente raciocina sobre uma aresta. A repetição em execução testa o comportamento resultante. O sistema continua disponível para o agente mesmo sem ter todos os tokens ativos ao mesmo tempo.

A paridade é provada no limite do comportamento

Testes escritos apenas para a nova implementação provam consistência interna, não preservação. Uma reescrita pode passar uma nova bateria completa de testes unitários e discordar da produção exatamente nos casos que interpretou mal.

O oráculo prático mais forte é o próprio sistema antigo. Capture entradas representativas nos seus limites reais, execute-as nas duas implementações, normalize apenas valores intencionalmente não determinísticos e compare as saídas observáveis. Podem incluir corpos de resposta, alterações na base de dados, ficheiros emitidos, mensagens, códigos de retorno, totais de controlo e registos que as operações tratam como contratuais.

Um caso de paridade deve guardar detalhe suficiente para reproduzir uma diferença:

{
  "case_id": "nightly-held-order-restart",
  "entry_point": "NIGHTSET",
  "input_refs": ["orders.dat#sha256:...", "status_control#2026-08-01"],
  "source": {"rc": 4, "settled": 812, "held": 17, "control_total": "194033.22"},
  "target": {"rc": 0, "settled": 829, "held": 0, "control_total": "196801.04"},
  "comparison": "mismatch"
}

O exemplo mostra por que fazer corresponder códigos de saída é uma prova fraca. A origem considera aceitável o código de retorno 4 e preserva os registos retidos. O destino devolve zero depois de os liquidar. Uma verificação de estado convencional prefere o resultado incorreto.

O tráfego gravado exige disciplina. Remova ou proteja valores sensíveis, preserve a ordem quando esta afeta o comportamento e inclua falhas e novas tentativas, em vez de recolher apenas pedidos bem-sucedidos. As amostras de lote precisam de categorias de volume semelhantes às de produção, datas-limite, duplicados, registos malformados e pontos de reinício. Não é necessário ter todos os registos de produção, mas é preciso cobrir todas as classes de comportamento conhecidas.

A paridade não proíbe alterações de arquitetura. Separa as alterações intencionais das acidentais. Pode substituir processamento sequencial de ficheiros por transações na base de dados, dividir um monólito em serviços ou mover um núcleo numérico para Rust. A comparação mostra onde o comportamento visível mudou. Uma pessoa pode então aprovar uma diferença deliberada com um motivo, em vez de a descobrir na conciliação.

CodeHero usa este limite de forma deliberada: a sua plataforma lê todo o código em todas as linguagens e depois verifica o sistema reescrito com um mecanismo de paridade face a tráfego de produção gravado. Esse mecanismo importa mais do que o código gerado parecer idiomático num pedido de alteração.

Reveja a afirmação de impacto, não apenas a diferença

A revisão com agentes deve avaliar a afirmação do agente sobre o impacto no sistema. A diferença continua a ser necessária, mas é o último artefacto de uma cadeia que começa com descoberta e termina com provas de comportamento.

Um pacote de revisão útil contém o comportamento pedido, os pontos de entrada afetados, os contratos alterados, os consumidores descobertos, as arestas não resolvidas, as provas de teste e quaisquer diferenças aceites. Cada afirmação deve ser rastreável. Se o agente disser que um campo tem um leitor, o revisor deve conseguir abrir a pesquisa ou o rasto que sustenta essa contagem.

Isto muda a conversa de aprovação. Em vez de perguntar se a nova função parece razoável, o revisor pergunta por que razão RECON.sql não é afetado, se o reinício noturno foi repetido e que prova cobre valores de estado em branco. É mais difícil para um agente fingir respostas a estas perguntas e mais fácil para um engenheiro experiente responder com precisão.

Procure três sinais de alerta no trabalho do agente. Primeiro, descreve dependências sem distinguir factos observados de inferências. Segundo, os testes vêm totalmente do novo desenho, em vez do comportamento legado capturado. Terceiro, usa expressões como "todos os chamadores" sem expor o limite da pesquisa. Cada sinal significa que a afirmação sobre o contexto é mais forte do que as provas.

Os revisores também precisam de uma regra de paragem. Bloqueie a alteração quando uma aresta não resolvida puder mudar dinheiro, permissões, registos regulados, saídas irreversíveis ou recuperação. Para um defeito de visualização com baixo risco, uma inferência limitada pode ser aceitável. A completude do contexto não é binária: as provas exigidas aumentam com a consequência de um erro.

Não avalie um agente pelo número de linhas aceites nem pela velocidade dos pedidos de alteração. Essas métricas recompensam plausibilidade local. Avalie quantas previsões de impacto correspondem aos efeitos observados, quantas diferenças de paridade escapam e se as repetições e controlos operacionais se comportam como esperado. Mesmo sem uma pontuação formal, estas perguntas separam assistência de escrita de trabalho de engenharia.

O âmbito do sistema inteiro muda os custos

A descoberta em todo o repositório custa mais antes da primeira edição, e é precisamente por isso que poupa tempo no trabalho com sistemas legados. As falhas caras acontecem depois de uma alteração local barata atravessar um limite invisível: durante o fecho, numa janela de lote, na conciliação ou depois de sair a única pessoa que conhecia a sequência de reinício.

O custo não é apenas a reparação. Uma má modernização ensina a organização a desconfiar do sistema de destino. As equipas mantêm a aplicação legada como sombra, comparam resultados manualmente e recusam alterações posteriores. A reescrita nominal termina, mas a migração operacional nunca fica concluída.

A análise do sistema inteiro também evita um desperdício mais subtil: transliterar arquitetura obsoleta porque o agente não vê por que existe. Se só vir um programa, a opção aparentemente mais segura é reproduzir os seus parágrafos noutra linguagem. Se vir os chamadores, contratos de dados, fluxo de trabalhos e comportamento no limite, consegue preservar os resultados necessários enquanto substitui estrutura acidental.

É esse o padrão que aplicamos quando a CodeHero reescreve sistemas legados em Go, Rust, TypeScript e Postgres em menos de 30 dias. O prazo curto só é credível quando descoberta, raciocínio entre linguagens e verificação de paridade trabalham sobre o sistema inteiro, em vez de esperar que pessoas forneçam ficheiros um a um.

Um agente de IA não precisa de uma compreensão mística de todas as decisões históricas. Precisa de um limite honesto, provas para as arestas dentro dele e testes nos pontos onde o comportamento o atravessa. Se o seu agente de programação não consegue dizer que trabalho noturno lê o registo que quer alterar, ainda não ganhou o direito de o alterar.