Editar um gerador de documentos com agentes de IA sem confundir a pilha atual e a legada

## Achar primeiro no código os comandos de início e a configuração reais Comece pelos metadados dos pacotes, pontos de entrada do console, carregadores de configuração, tratamento de variáveis de ambiente e código que cria espaços de trabalho durante a execução. Quando houver conflito, essas superfícies executáveis prevalecem sobre a documentação textual. - Confirme qual comando inicia a aplicação principal. - Confirme qual comando expõe qualquer serviço legado ou compatível com MCP. - Rastreie cada comando até seu módulo e sua função reais. - Localize os arquivos-modelo de configuração e o comportamento padrão do espaço de trabalho. - Verifique se todos os caminhos mencionados existem na cópia de trabalho atual. Trate uma visão geral desatualizada como contexto histórico, não como prova do caminho de inicialização atual. ## Decidir se a mudança pertence à pilha atual ou à legada Um repositório pode distribuir a pilha atual do produto junto de uma biblioteca de geração anterior que ainda atende a um endpoint especializado. Identifique a pilha responsável antes de editar. A pilha atual pode ser responsável por: - a interface de linha de comando e o fluxo de configuração inicial; - a orquestração e a execução com vários agentes; - os agentes de pesquisa, geração e design; - ferramentas no estilo MCP para pesquisa, reflexão, conversão e gerenciamento de tarefas; - utilitários de configuração, registro de eventos e espaço de trabalho; - conversão de HTML baseada em navegador e um auxiliar em Node; - testes voltados à integração. A pilha legada ainda pode ser responsável pela geração orientada por arquivos-modelo, inferência de leiaute, análise sintática, avaliação e um servidor de compatibilidade. Não suponha que alterar um conceito compartilhado em uma pilha atualize a outra. ## Manter o design simples, com menos casos especiais e funções curtas Prefira projetos que transformem casos extremos em casos comuns, em vez de acumular ramificações condicionais. Resolva o problema real do repositório, não um problema hipotético de arquitetura. - Escolha uma solução direta e operacionalmente leve quando ela satisfizer o requisito real. - Mantenha as funções curtas, focadas e com nomes claros. - Trate a complexidade desnecessária como defeito. - Mais de 3 níveis de recuo indicam que o código deve ser reestruturado. - Não esconda o fluxo de controle normal em envoltórios amplos de exceções sem um modo concreto de falha. - Mantenha as críticas técnicas e direcionadas ao código, ao projeto ou às premissas, não às pessoas. O bom julgamento aparece em menos casos especiais, superfícies menores e comportamentos fáceis de verificar. ## Adicionar anotações de tipo e manter as dependências no mínimo Aplique convenções uniformes em toda a pilha mantida: - adicione anotações de tipo a funções e métodos; - escreva a documentação técnica e os comentários de código no idioma declarado pelo repositório; - use o gerenciador de dependências atual, as ferramentas de busca do repositório, os recursos da linguagem e as APIs de biblioteca compatíveis; - prefira as interfaces atuais de serialização e validação às formas descontinuadas; - minimize as dependências e o volume total de código; - mantenha a definição do pacote raiz concentrada no produto principal; - coloque as dependências de subprojetos realmente isolados nos arquivos locais de dependências correspondentes. Não mova uma dependência apenas para deixar a estrutura mais organizada. Separe-a somente quando a fronteira de execução e manutenção for real. ## Seguir uma mudança por todas as partes ligadas, incluindo Python e Node Examine todo o caminho responsável pelo comportamento que será alterado: - para comportamentos de linha de comando, examine em conjunto as definições dos comandos, os auxiliares compartilhados e o carregamento da configuração; - para orquestração, examine o coordenador principal e a implementação do agente pertinente; - para comportamentos MCP, determine se a responsabilidade pertence aos servidores de ferramentas atuais ou ao servidor legado de compatibilidade; - para exportação e conversão, examine tanto o lado da orquestração em Python quanto o lado da conversão em Node; - para conceitos de geração duplicados, altere apenas a pilha responsável, a menos que a tarefa abranja explicitamente ambas. Mantenha a alteração dentro do seu alcance. Não refatore as duas pilhas apenas porque aparecem nomes semelhantes em ambas. ## Manter os nomes de configuração e os locais de workspace existentes As chaves de configuração existentes, variáveis de ambiente, comportamento da configuração inicial, exemplos de configuração e locais dos espaços de trabalho formam um contrato de execução. Preserve seus nomes, a menos que a tarefa inclua explicitamente uma migração. Dependências de navegador e contêiner podem ser requisitos normais de execução para caminhos de conversão, não extras opcionais de desenvolvimento. Ferramentas nativas de conversão, credenciais de modelos, automação de navegador e imagens de contêiner também podem determinar quais testes de integração podem ser executados. Ao alterar um caminho de execução: 1. Identifique todas as fontes de configuração e seus padrões. 2. Rastreie como a configuração inicial e os exemplos preenchem esses valores. 3. Verifique o chamador em Python e qualquer auxiliar externo de conversão. 4. Preserve a compatibilidade ou forneça um caminho explícito de migração. ## Conferir documentos antigos com o código e separar os testes pelo que precisam Confira as afirmações da documentação em relação à árvore de arquivos atual e aos pontos de entrada executáveis antes de confiar nelas. Documentos antigos ainda podem explicar conceitos úteis, mesmo citando arquivos removidos ou fluxos de inicialização obsoletos. Classifique os testes conforme seus requisitos: - testes de unidade para lógica isolada; - testes de analisador sintático ou testes marcados para caminhos de dados especializados; - testes de integração para ferramentas de ambiente isolado, conversão por navegador ou de PDF, processamento de imagens e utilitários externos; - testes apoiados por modelos que exigem credenciais ou serviços em rede. A ausência de um navegador, uma imagem de contêiner, um conversor nativo ou uma credencial de modelo é uma limitação da validação, não uma evidência de que código sem relação esteja com defeito. ## Rodar os menores testes úteis e relatar o que não pôde rodar Use uma sequência de alteração focada: 1. Confirme qual pilha e qual ponto de entrada são responsáveis pelo comportamento. 2. Edite a menor superfície completa. 3. Execute o menor subconjunto significativo de testes. 4. Amplie apenas para caminhos diretamente acoplados de Python, Node, navegador, contêiner ou compatibilidade. 5. Informe qualquer requisito de dependência ou ambiente que tenha impedido a validação. Revise a diferença final em busca de alterações acidentais na outra pilha, contratos de configuração renomeados, referências desatualizadas na documentação, refatorações sem relação e fronteiras entre linguagens que não foram testadas. Informe o que mudou, qual caminho foi exercitado, quais verificações passaram e quais não puderam ser executadas. Não declare validação completa quando uma dependência de execução obrigatória não estava disponível.