Alucinações arquiteturais

A arquitetura precisa apontar para artefatos

Uma alucinação arquitetural ocorre quando uma proposta trata como existente um arquivo, serviço, função, rota ou estado que não foi confirmado. Ela pode surgir de um nome plausível, de uma versão antiga ou da tentativa de completar uma narrativa. O problema não é sugerir algo novo: uma criação pode ser necessária. O problema é usar uma criação ainda não decidida como se já fizesse parte do sistema.

Na Oficina Caracol, GET /api/casos existe no contrato e deve ser localizado em src/servidor.mjs. A função listarAtivos existe em src/catalogo.mjs. Um banco remoto e uma rota de login não pertencem ao projeto. Se uma ferramenta disser que o banco já está configurado, peça o caminho, a configuração e a prova. Se ela disser que precisamos criar um banco para filtrar três casos fictícios, avalie a necessidade antes de aceitar o aumento de escopo.

Inventário mínimo e graus de afirmação

A busca precisa de escopo. Dizer “não localizado” depois de procurar apenas em public/app.js não autoriza concluir que a rota não existe: ela pode estar no servidor. Registre quais diretórios, extensões e configurações foram examinados. Quando não for possível inspecionar uma dependência externa, a limitação deve acompanhar a decisão que depende dela.

Lacuna impeditiva e lacuna tolerável

Uma lacuna é uma informação ou prova necessária ainda ausente. Sua classificação depende do objetivo e do risco, não do conforto da equipe. É impeditiva quando o resultado obrigatório depende dela ou quando não há base para aceitar o risco. É tolerável para uma liberação específica quando o item não é obrigatório naquele escopo, o impacto está delimitado e a autoridade competente aceita explicitamente a limitação. Registrar uma lacuna não a transforma em tolerável.

A mesma condição pode mudar de classe quando muda a promessa. A ausência de persistência não inviabiliza a demonstração em memória se seu limite está claro. Inviabiliza anunciar que reservas sobreviverão a uma queda do processo. O gate precisa ser escrito para a promessa realmente feita.

Procedimento para impedir a arquitetura imaginada

• Identifique a versão recebida e faça o inventário dos caminhos oficiais. Diferencie arquivo encontrado de arquivo proposto.
• Localize exports, imports e handlers antes de citar suas capacidades. Inspecione também quem os consome.
• Execute testes ou uma requisição local para confirmar comportamentos materiais. A existência de uma função não comprova o que ela faz.
• Registre cada lacuna com item afetado, impacto, classificação, decisão responsável e próxima ação.
• Autorize criações necessárias como mudança de escopo identificada, em vez de escondê-las no diagnóstico.
• Libere somente quando dependências obrigatórias estiverem confirmadas e as exceções não impeditivas tiverem aceitação explícita.

Um veredito limitado e honesto

Exemplo de veredito de planejamento: “O contrato exige listarAtivos e GET /api/casos. Seus caminhos oficiais são conhecidos pelo pacote; a evidência desta unidade ainda aguarda execução no ambiente do leitor. Não há requisito de login ou banco remoto. A proposta de acrescentá-los foi retirada do escopo. A reserva permanece uma simulação em memória.” Essa redação distingue fatos do pacote, prova local pendente e decisão de não ampliar o sistema.

Não escreva “LIBERADO porque todas as dependências foram localizadas ou registradas como lacuna”. Uma dependência obrigatória apenas registrada continua faltando. O resultado aceitável exige capacidade demonstrada no conjunto obrigatório, e não uma documentação completa sobre sua impossibilidade.

Exercício com resolução

A IA propõe modificar src/auth.mjs para corrigir a lista. O inventário completo dos caminhos oficiais não contém esse arquivo. Nenhum requisito solicita autenticação. Ao mesmo tempo, falta executar o teste HTTP do catálogo. Classifique as duas questões e proponha uma ação para cada uma.

Leitura técnica relacionada

S19: Node.js, módulos e HTTP, para conferir imports e rotas executáveis. O inventário e a classificação de lacunas desta seção são instrumentos de rastreabilidade da Engenharia Caracol.