2026-06-26 Retrospectiva | idea_world

Hoje, ao documentar o fluxo de entrada source-to-AST, organizei como “realmente passar o código-fonte para a avaliação do LLM”.

Não foi apenas um dia de escrever documentação. Também estou coletando dados relacionados ao Godot em tempo real, então a documentação não poderia ficar apenas como um design abstrato. Era necessário um critério para verificar por quais caminhos os dados coletados estão passando, em quais unidades são fragmentados e como devem ser encaminhados em solicitações.

Por que quis organizar este design primeiro

O motivo de querer documentar este design primeiro foi a preocupação de que, em trabalhos anteriores, a IA poderia gerar código de forma estranha ou mudar o escopo da solicitação arbitrariamente.

Em especial, o fato de que seria necessário enviar todo o Markdown, mas poderia ser implementado enviando apenas uma parte inicial; inserir hard‑coding que eu não desejava; ou, ao precisar analisar o arquivo inteiro, enviar apenas o “código central”. Esses cenários me deixavam inquieto.

Por isso, antes de escrever código, quis fixar em documento: “Qual solicitação fazer à IA”, “Em que unidades expandir o arquivo”, “O que colocar no AST Parser e o que colocar diretamente no Retriever”, “Que combinações devem entrar na chamada ao LLM”.

Hoje em dia, mais do que a própria implementação, fico pensando em como instruir a IA para que a intenção seja menos distorcida. O mesmo requisito pode gerar resultados muito diferentes dependendo de como o escopo é definido, quais expressões são proibidas e quais evidências devem ser verificadas.

Este documento é mais um padrão de referência para que, ao delegar a implementação à IA, a solicitação não se perca, do que um simples plano de desenvolvimento. Ele serve para evitar que a IA reduza a entrada, envie apenas trechos centrais ou modifique arquivos não solicitados.

Critério de hoje

Concluí que o código-fonte deve ser expandido usando cabeçalhos no formato # <caminho‑relativo>/<caminho‑relativo>. O objetivo desses cabeçalhos não é decorativo no prompt, mas rastrear de onde o arquivo veio e como ele foi fragmentado antes de chegar ao Retriever.

Desde o início, imaginei percorrer o repositório do GitHub na ordem dos caminhos, excluir arquivos quando necessário, mas ainda assim exibir o que foi excluído na UI web ou nos logs. Em seguida, dividir os arquivos restantes em unidades legíveis e rastrear de qual arquivo original cada fragmento provém.

Durante a documentação, a IA frequentemente interpretava erroneamente a dicotomia “enviar o arquivo inteiro de uma vez ou apenas o código central”. O que eu pretendia era expandir o arquivo por caminho e, então, enviá‑lo fragmentado em ordem.

No meu critério, arquivos .gd são a entrada para o AST Parser. O AST Parser deve cortar sequencialmente unidades analisáveis, como as funções a, b, c e d dentro de um .gd. Quando a unidade de função não for clara, basta cortar em trechos de código em ordem. O ponto crucial não é “escolher arbitrariamente funções centrais”, mas fragmentar mantendo a ordem e o caminho originais e rastrear como esses fragmentos chegam ao Retriever.

Por outro lado, arquivos como .md, que decidimos excluir desta análise de código-fonte, devem constar na lista de exclusão. É fundamental que a exclusão não desapareça; a UI web ou os logs devem mostrar por qual critério cada arquivo foi excluído. Caso existam arquivos de configuração textual que não devam ser excluídos, faz sentido enviá‑los diretamente ao Retriever, divididos em linhas, parágrafos, pares chave‑valor, nós/recursos/conexões, sem passar pelo AST Parser.

Resumindo, o fluxo atual se assemelha ao seguinte.

repository path order
  -> "# <relative/path>" file expansion for tracking
  -> excluded file list visible in UI/log
  -> .gd files to AST Parser
  -> AST Parser emits ordered function/code chunks
  -> excluded files are recorded with reason
  -> non-.gd allowed text/config files emit ordered chunks
  -> each chunk goes to Retriever with source path metadata
  -> prompt + current chunk + retrieved evidence
  -> LLM judgment
  -> validation
  -> accumulated project-level result

Parte revisada da interpretação da IA

No meio, a IA criou uma estrutura separada como repository_file_manifest, mas isso não correspondia à direção que eu imaginava. O que é necessário não é um repositório de manifestos separado, mas rastrear, com base no fluxo de arquivos expandido pelos cabeçalhos # <caminho_relativo>, quais arquivos foram excluídos, em quais fragmentos cada arquivo foi dividido e em que ordem esses fragmentos foram inseridos no Retriever.

É estranho dizer que “não lê” binários ou assets. O ponto central é que os bytes originais não são inseridos no LLM; isso não significa que o arquivo desapareça completamente da avaliação do projeto. Se um caminho de asset aparecer dentro de fragmentos de texto como .tscn, .import, README, a decisão pode ser feita com base nesses fragmentos.

Outro aspecto que percebi ser necessário é a depuração da transmissão. Não pode acontecer de a IA simplesmente selecionar funções principais de arquivos .gd e enviá‑las. O arquivo expandido com # <caminho_relativo> deve ser dividido pelo AST Parser em funções ou trechos de código, e deve ser possível verificar, por meio de diff ou SHA‑256, qual trecho foi passado para o Retriever e em que ordem.

Pontos organizados ao revisar o PR

Ao revisar o PR, percebi que o llm_judgment_request estava definido de duas maneiras diferentes no documento. Uma versão focava em chunk_text, chunk_kind e retrieved_evidence, enquanto a outra incluía também chunk_code, surrounding_context e judgment_contract.

Quando o mesmo objeto de solicitação é definido de forma diferente dentro da documentação, isso inevitavelmente gera confusão na implementação posterior. O esquema de solicitação deve ser unificado. Em particular, para distinguir entre chunks de AST e chunks de recuperação direta, chunk_kind é necessário, e para validar o julgamento do LLM, tanto retrieved_evidence quanto judgment_contract precisam estar incluídos.

Na revisão do Qwen, confirmei que também foram feitas observações sobre links do README e erros de digitação e links relacionados ao documento de 25 dias. No entanto, a inclusão do documento de 25 dias ou do workflow no diff do PR não foi uma tarefa que eu pretendia. Alterações feitas arbitrariamente pela IA se misturaram, e, ao descobri‑las, solicitei a restauração.

Problema com escopo misturado

Hoje, ao analisar o diff do PR, descobri que o documento de 25 de junho e o arquivo .github/workflows/qwen-code-pr-review.yml foram incluídos. Isso não era a mudança que eu solicitei. Parecia que a IA havia alterado ou excluído arquivos arbitrariamente, e na tela do PR os seguintes arquivos apareciam como modificados ou removidos:

.github/workflows/qwen-code-pr-review.yml
docs/observations/2026-06-25-qwen-markdown-classification-observation.md
docs/retrospectives/2026-06-25-source-analysis-scoring.md
docs/roadmaps/2026-06-25-qwen-pr-review-workflow.md

Então solicitei que essas alterações fossem revertidas. Em seguida, os arquivos foram restaurados com base em origin/main, e o diff do PR ficou concentrado em README.md e docs/roadmaps/2026-06-26-source-to-ast-input-flow.md.

Ao observar esse processo, percebi que, ao delegar a produção de documentos à IA, também é necessário fixar rigidamente o escopo das mudanças antecipadamente. Escrever retrospectivas ou documentos de roadmap deve ser gerenciado como o escopo de um PR, assim como alterações de código.

Conclusão de hoje

O ponto central que verifiquei novamente hoje foi “como os arquivos expandidos por caminho são excluídos, em quais fragmentos são divididos e em que ordem esses fragmentos são passados para o Retriever e para o julgamento do LLM”. Não se trata de inserir todos os arquivos de uma vez, nem de escolher arbitrariamente apenas o código essencial.

A base atual é a seguinte:

Os arquivos são expandidos com um cabeçalho # <caminho relativo>, e esse cabeçalho serve para rastrear o caminho original e os fragmentos.
Os arquivos excluídos devem ser visíveis na interface web ou nos logs.
Arquivos .gd são enviados para o AST Parser, que gera funções ou fragmentos de código na ordem original.
Arquivos que decidimos excluir, como .md, permanecem na lista de exclusão e devem ser visíveis na interface web ou nos logs.
Arquivos de configuração de texto que não são excluídos são fragmentados em unidades como linhas, parágrafos ou blocos de configuração, sem passar pelo AST.
Cada fragmento contém informações de rastreamento como caminho de origem e ordem do fragmento ao ser enviado ao Retriever.
As chamadas ao LLM são realizadas várias vezes no formato prompt + fragmento atual + resultados da busca do Retriever.
A avaliação do projeto só seria possível depois que os resultados de julgamento de vários fragmentos fossem acumulados desde o início.

A coleta de dados continua em andamento. Portanto, os documentos futuros devem servir como critério para verificar como os dados realmente coletados são inseridos e validados, e não apenas como uma “arquitetura plausível”.