2026-06-18 Revisão do Reset de Trabalho RAG no Godot

Estado de hoje

Ontem, bebi cerca de 1 litro de café em um café, e hoje me senti muito mal. Por isso não consegui programar adequadamente. Mesmo assim, vou registrar aqui o que me veio à mente agora e por que organizei o trabalho de ontem.

Partes que faltavam na arquitetura atual

As partes que estavam faltando na arquitetura atual do Godot LLM/RAG são as seguintes. Essas partes precisam ser aprimoradas no futuro.

A camada de análise estática é fraca  
Não há validação baseada em AST/parser do GDScript  
O grafo de dependências do projeto Godot é fraco  
A validação de execução/sintaxe é fraca  
A taxonomia de rótulos ainda é grosseira  
A distinção de proveniência entre as produções de LLM e as respostas verificadas é fraca  
O design de prevenção de vazamento de dados/remoção de duplicatas é fraco

Particularmente, há partes que não podem ser resolvidas apenas com RAG. A identificação de código Godot não é apenas um problema de busca em documentos, mas também requer considerar a sintaxe real do GDScript, as dependências de scene/resource, a estrutura do projeto e as diferenças entre as APIs do Godot 3/4. No entanto, o fluxo de ontem consistiu em chunking da documentação oficial e, em seguida, enviar o resultado de volta ao LLM para receber feedback. Esse método parecia avançar rapidamente na superfície, mas, na prática, os critérios de validação ficaram instáveis.

Motivo da organização do trabalho de 17 de junho

Em 17 de junho, deleguei o chunking ao LLM e, depois, enviei o resultado novamente ao GPT para obter feedback. Contudo, por mais que eu analisasse, esse método não parecia adequado.

A razão para rastrear a documentação oficial foi usar toda a documentação do Godot como base. Entretanto, durante o processo, antes que o LLM analisasse o documento corretamente, ele começou a considerar algumas APIs como “núcleo do MVP”, codificando palavras‑chave específicas ou reforçando excessivamente o contexto ao redor. Assim, o sistema deixa de ser um RAG baseado em toda a documentação oficial e passa a ser um mecanismo de busca focado em poucas palavras‑chave.

O problema não era apenas que o resultado não agradava. Sem que eu verificasse, o LLM criou seus próprios critérios, gerou arquivos com base nesses critérios e, então, usou esses resultados para tomar novas decisões. Dessa forma, surgiram alucinações ao não consultar a estrutura original do documento, e, posteriormente, o próprio LLM não sabia mais quais arquivos foram criados sob quais critérios.

Em uma escala maior, observou‑se que o ChatGPT ou o Codex reduziam ou alteravam o escopo de forma arbitrária, sem que eu indicasse isso. Eu queria que a estrutura fosse baseada em toda a documentação oficial, não que o LLM selecionasse “algumas APIs centrais do MVP” para codificar manualmente. Contudo, o LLM, por conta própria, decidiu que “se for MVP, isso é o essencial” e gerou a próxima saída antes mesmo de concluir a etapa atual.

O padrão problemático foi o seguinte.

O usuário deseja uma análise de estrutura baseada em toda a documentação oficial  
-> O LLM define arbitrariamente o escopo do MVP  
-> Considera algumas APIs como essenciais  
-> Primeiro realiza hard coding/reforço excessivo/geração de catálogo  
-> Produz entregáveis da próxima fase antes da validação  
-> Os resultados são embalados como números convincentes  
-> Na prática, a estrutura original e os critérios de rotulagem ficam contaminados

Isso não é apenas um erro simples de implementação, mas um problema de método de trabalho. Tanto o ChatGPT quanto o Codex tendiam a assumir que já havia uma resposta, mesmo quando ainda não havia uma, e avançavam para a próxima etapa antes de bloquear a atual. Embora parecesse que estavam seguindo as instruções, na prática reinterpretavam o escopo das instruções ou o ignoravam completamente, tentando primeiro criar uma “versão final que parece boa”.

Nesta tarefa, o ponto particularmente perigoso foi que o LLM não conseguiu distinguir adequadamente a confiabilidade dos resultados intermediários que ele mesmo produziu. Fatos verificados na documentação oficial, palavras que coincidentemente corresponderam a regex, regras aprovadas diretamente pelo usuário e informações suplementares supostas pelo LLM se misturaram. Quando, nesse estado, o LLM foi novamente solicitado a avaliar o resultado, acabou ocorrendo um fluxo em que o LLM justificava de forma plausível o que ele mesmo havia criado.

Por que esvaziar o artefato de chunking

Hoje organizei os arquivos relacionados ao chunking RAG que criei ontem.

Os itens organizados são os seguintes.

v1 docs_chunks.jsonl  
v2 docs_chunks_v2.jsonl  
v3/v3.1 catalog/index/mapping resultado  
Script de rascunho de chunking/pós-processamento/validação  
Rascunho inicial de RAG chat/index

No início, pensei que apenas v3/v3.1 fossem problemáticos, mas ao analisar novamente percebi que v1 e v2 também estavam em um estado que exigia revisão desde a raiz. Na verdade, deveríamos ter analisado os próprios chunks. Por exemplo, era necessário entender como a referência de classes do Godot está estruturada, como os métodos/propriedades são representados no documento original, e como o resultado da conversão pelo Sphinx se quebra.

Entretanto, na prática, a geração dos resultados de chunking ocorreu antes da análise do documento original. Como consequência, v1 ficou próximo de um fragmento baseado no número de caracteres, e v2 foi uma forma que recebeu um pós‑processamento adicional. Apareceram números como quantidade de chunks, sucesso no parsing de JSONL, distribuição de doc_type, mas a questão realmente importante – “esse chunk pode ser usado como base para determinar Godot 3/4?” – não foi suficientemente verificada.

Especialmente na referência de classes, era preciso checar se estruturas como CharacterBody2D.move_and_slide permanecem estáveis, se propriedades como velocity são separadas corretamente, e como extrair as relações antigo/novo da documentação de migração. Sem essas verificações, ao nomear itens como trusted_api_symbols, syntax_symbols ou api_mapping, criamos apenas dados contaminados que parecem plausíveis.

Portanto, hoje esvaziamos os produtos de chunking até v1/v2. Isso não significa desistir do trabalho, mas sim organizar tudo para que a linha de base incorreta não seja mais considerada como tal.

Conclusão do dia

A conclusão de hoje é simples.

É necessário refazer o chunking.  
Antes disso, é preciso analisar primeiro a estrutura original dos documentos em `outputs/godot_docs_full/pages`.  
Não se deve usar os resultados intermediários gerados pelo LLM como base para a próxima etapa sem validação.

Mesmo sem eu ter verificado, se o LLM julga por conta própria, sem olhar corretamente o original, e ainda mistura alucinações, acaba não sabendo o que fez. Nesse estado, se continuar criando arquivos, apenas os arquivos de depuração aumentam, e não se sabe qual é o critério.

De agora em diante, não confio que o ChatGPT ou o Codex se expandam e implementem em “direção boa” por conta própria. Especialmente em tarefas onde o critério é importante, como conjuntos de dados, rotuladores e discriminadores RAG, são necessários os seguintes princípios.

Se o LLM definir arbitrariamente o escopo do MVP, interrompa  
Se houver hardcoding não aprovado pelo usuário, interrompa  
Se criar entregáveis sem analisar a estrutura original, interrompa  
Se avançar para a próxima etapa sem relatório de validação, interrompa  
Se a proveniência dos artefatos gerados pelo LLM se misturar com a resposta verificada, interrompa

Se você for refazer amanhã, a primeira tarefa não é criar um novo catálogo. Primeiro é necessário analisar o próprio godot_docs_full. Ou seja, verifique qual é a estrutura real dos Markdown da documentação oficial que estão em outputs/godot_docs_full/pages e, com base nessa estrutura, repense quais unidades devem ser transformadas em chunks.

A pergunta que precisamos agora não é “Qual API colocar primeiro?”, mas algo mais próximo da próxima questão.

Como o documento de referência de classe dentro de godot_docs_full está estruturado?  
A lista de métodos/propriedades/sinais/constantes pode ser separada de forma confiável no Markdown original?  
Qual é o formato da estrutura de tabelas/listas/frases no documento de migração?  
Os tutoriais não podem usar o mesmo critério de chunking que a referência de classe?  
Deve‑se definir unidades de chunk diferentes para cada tipo de documento?  
Entre página, seção e membro de API, qual deve ser o chunk padrão?  
Qual relatório de validação deve ser definido antes do chunking?

Em última análise, a próxima tarefa não é “refazer o RAG”, mas analisar godot_docs_full e redesenhar a segmentação em chunks de acordo com a documentação oficial do Godot. Só então será necessário refazer o chunking.