Fine-tune de LLMs para documentar código legado

Como treinar um modelo de linguagem menor para documentar código legado em PHP, JavaScript e SQL com fidelidade ao código, sem inventar regras de negócio e deixando claro quando não houver informação suficiente.

O problema que todo time já viu

Sistemas legados carregam anos de regras de negócio no código, e quase nada disso está escrito de forma confiável.

Documentação antiga fica desatualizada. Quem saiu da empresa levou o contexto. Quem chega hoje abre um método PHP, uma procedure SQL ou um trecho de JavaScript e precisa adivinhar o que aquilo faz de verdade.

Modelos generativos gerais ajudam, mas têm um vício perigoso: completam a história. Inventam parâmetros, inventam regras, soam convincentes, e isso em legado é pior do que silêncio.

A pergunta útil não é “qual o maior modelo?”, e sim:

Como especializar um LLM para documentar só o que o código sustenta, e declarar o que não dá para saber?

Fine-tune com propósito claro

Em vez de prompt genérico em cima de um modelo “faz-tudo”, o caminho foi fine-tuning supervisionado (SFT) com adapter LoRA/QLoRA:

Formato mínimo da resposta:

1. Método ou função / Consulta SQL
2. Objetivo
3. Parâmetros
4. Retorno
5. Funcionamento
6. Regras de negócio identificadas
7. Pontos não determinados

Esse último item não é detalhe: é o contrato de qualidade. Se o trecho não mostra de onde vem um valor ou o que acontece em produção, o modelo deve dizer isso, não “completar” com senso comum.

Por que um modelo pequeno + LoRA/QLoRA

Em vez de depender só de um modelo gigante na nuvem, a escolha prática foi:

• Base aberta e leve (na faixa de ~1 a 2B parâmetros), viável para experimentação e inferência local
• Adaptação com LoRA/QLoRA: treina pouco peso, exporta um adapter compacto, encaixa na base sem republicar o modelo inteiro

O ganho não é “modelo maior”. É comportamento alinhado ao formato e à disciplina de não inventar regra de negócio.

De onde vieram os dados

Para ensinar o mapeamento código documentação, usamos bases públicas e um pipeline próprio:

No treino cheio, a ordem de grandeza foi:

• PHP ≈ 241 mil
• JavaScript ≈ 58 mil
• SQL (Spider) ≈ 5 a 7 mil
• Total ≈ 300 mil exemplos

Isso não resolve sozinho o gap de “documentação de negócio em português perfeita”, pois docstrings e corpora públicos não são rubrica de negócio. Por isso o desenho prevê curadoria e um critério explícito: não afirmar o que o código não mostra.

Como fica o pipeline de fine-tune

Fluxo resumido:

1. Preparar SQL e mesclar com CodeXGLUE
2. Montar dataset SFT no formato de chat do modelo-base
3. Treinar QLoRA em GPU
4. Avaliar se a saída respeita as seções do contrato
5. Exportar o adapter e rodar inferência local (Mac/CPU/GPU conforme o hardware)

Na prática: um notebook ou scripts encadeados cobrem dados SFT treino eval pacote do adapter.

Código aberto: GitHub + Google Colab

Assim qualquer pessoa consegue reproduzir o fine-tune ou só a inferência com o adapter, sem depender de setup fechado.

O que esperamos na prática

Não é “substituir a pessoa que conhece o domínio”. É acelerar a leitura fiel do trecho:

• Descrever o que o código faz
• Listar parâmetros e retornos visíveis
• Extrair regras só quando evidentes
• Marcar lacunas em “Pontos não determinados”

Em legado, isso já muda o jogo: menos documentação inventada, mais base para revisão humana.

Limitações (de propósito)

Fora do escopo inicial desse tipo de fine-tune:

• Especificação normativa para o que “deveria” ser construído
• Análise de uma aplicação inteira numa única chamada
• Substituir revisão técnica ou especialista de negócio

O modelo documenta o trecho. Contexto de sistema, histórico oral e intenção de produto continuam humanos.

Como isso impacta o Spec-Driven Development

No Spec-Driven Development, o time começa pela especificação e só depois implementa. O fine-tune deste artigo faz o contrário: lê o código que já existe e gera uma documentação do comportamento atual.

São etapas diferentes, e uma ajuda a outra.

Antes de escrever a especificação do que o sistema deveria fazer, alguém precisa entender o que ele faz hoje. Em legado, isso costuma ser lento e sujeito a achismo. Um modelo treinado para documentar só o que o código sustenta (e marcar o que não dá para saber) acelera essa leitura e reduz especificação inventada.

Na prática:

1. O modelo documenta o trecho legado (comportamento atual).
2. O time usa essa base para escrever a especificação do que muda ou permanece.
3. Fica mais fácil ver o gap: o que já existe, o que é incerto e o que exige conversa com o negócio.

Resumo: este fine-tune não substitui o Spec-Driven. Ele melhora o ponto de partida, com um retrato mais fiel do sistema atual, para a especificação futura nascer com menos alucinação.

Próximos passos típicos

• Ampliar curadoria em pt-BR (qualidade > volume cego)
• Refinar o modo bilingue (mesma função, duas documentações)
• Medir qualidade com rubrica humana, não só métricas automáticas
• Encaixar no fluxo do dia a dia (CLI, API local, editor)

Conclusão

Legado não precisa de mais texto genérico. Precisa de documentação ancorada no código: o que o trecho faz, o que fica explícito e o que permanece incerto.

Fine-tune com LoRA/QLoRA em um modelo pequeno é um caminho prático para isso. Em vez de só promptar um modelo genérico, você especializa o comportamento: formato fixo, dados alinhados à tarefa e a disciplina de não inventar regra de negócio.

O resultado não substitui quem conhece o domínio, nem o Spec-Driven Development. Melhora o ponto de partida: menos documentação inventada, mais base para revisão humana e para especificar o que vem depois.

Se você mantém PHP, JavaScript ou SQL antigos e já se cansou de documentação que “parece certa”, vale o experimento. O projeto é aberto e roda no Google Colab:

https://github.com/wolfxweb/Celx