{"id":1273,"date":"2026-09-24T04:01:30","date_gmt":"2026-09-24T07:01:30","guid":{"rendered":"https:\/\/adrianosantostreina.com.br\/blog\/pipeline-documentacao-automatica-ia-codigo-verificado\/"},"modified":"2026-09-24T04:01:37","modified_gmt":"2026-09-24T07:01:37","slug":"pipeline-documentacao-automatica-ia-codigo-verificado","status":"publish","type":"post","link":"https:\/\/adrianosantostreina.com.br\/blog\/pipeline-documentacao-automatica-ia-codigo-verificado\/","title":{"rendered":"Coment\u00e1rio Bom \u00e9 Coment\u00e1rio Verificado: Um Pipeline de Documenta\u00e7\u00e3o Autom\u00e1tica que N\u00e3o Mente Sobre o C\u00f3digo"},"content":{"rendered":"

Voc\u00ea j\u00e1 deve ter vivido essa cena: algu\u00e9m abre um m\u00e9todo p\u00fablico sem docstring, olha o nome da fun\u00e7\u00e3o, tenta adivinhar o comportamento pelos par\u00e2metros e, na d\u00favida, faz um print<\/code> no meio do c\u00f3digo s\u00f3 para confirmar o que ele realmente retorna. Meia hora depois, descobre que a fun\u00e7\u00e3o tem um efeito colateral que ningu\u00e9m documentou \u2014 ela grava em cache, dispara um evento, ou pior, muta um objeto que deveria ser imut\u00e1vel. O problema n\u00e3o \u00e9 a aus\u00eancia de coment\u00e1rios. \u00c9 que ningu\u00e9m confia mais neles, porque a experi\u00eancia coletiva da equipe j\u00e1 provou, repetidas vezes, que documenta\u00e7\u00e3o e c\u00f3digo divergem assim que o primeiro refactor acontece.<\/p>\n

A tenta\u00e7\u00e3o \u00f3bvia em 2026 \u00e9 jogar o problema para a IA: “gera a documenta\u00e7\u00e3o para mim”. E funciona \u2014 no sentido de que produz texto plaus\u00edvel, bem formatado, com t\u00edtulos e exemplos. O problema \u00e9 que “plaus\u00edvel” e “correto” s\u00e3o coisas diferentes, e documenta\u00e7\u00e3o incorreta \u00e9 pior do que nenhuma documenta\u00e7\u00e3o, porque ela engana com confian\u00e7a. Este artigo mostra como montar um pipeline de documenta\u00e7\u00e3o autom\u00e1tica que usa IA para gerar o texto, mas usa engenharia de software convencional para garantir que esse texto continue verdadeiro \u2014 hoje e depois do pr\u00f3ximo merge.<\/p>\n

O problema real: documenta\u00e7\u00e3o como artefato descart\u00e1vel<\/h2>\n

Em times que j\u00e1 adotaram assistentes de c\u00f3digo, \u00e9 comum ver dois extremos. No primeiro, ningu\u00e9m documenta nada porque “a IA explica quando eu perguntar depois”. No segundo, documenta\u00e7\u00e3o \u00e9 gerada em massa uma vez, vira um commit gigante, e nunca mais \u00e9 tocada \u2014 o que na pr\u00e1tica \u00e9 o mesmo problema do README desatualizado, s\u00f3 que com um verniz mais bonito.<\/p>\n

O ponto central \u00e9 que gera\u00e7\u00e3o de documenta\u00e7\u00e3o por IA resolve apenas metade do problema: a reda\u00e7\u00e3o. A outra metade \u2014 manter a documenta\u00e7\u00e3o sincronizada com o comportamento real do c\u00f3digo ao longo do tempo \u2014 exige um processo, n\u00e3o um prompt isolado. \u00c9 exatamente essa lacuna que este artigo cobre.<\/p>\n

\ud83d\udca1 Dica do Mestre:<\/strong> vale diferenciar “gerar documenta\u00e7\u00e3o” de “gerar documenta\u00e7\u00e3o verific\u00e1vel”. Ferramentas como as listadas no comparativo de assistentes de codifica\u00e7\u00e3o de IA de 2026<\/a> focam majoritariamente na primeira parte. A segunda parte \u00e9 responsabilidade sua, e \u00e9 o que separa um pipeline confi\u00e1vel de um gerador de texto bonito.<\/p><\/blockquote>\n

Camada 1: gera\u00e7\u00e3o assistida com contexto real, n\u00e3o com o arquivo isolado<\/h2>\n

O erro mais comum ao pedir documenta\u00e7\u00e3o para uma IA \u00e9 colar apenas a fun\u00e7\u00e3o isolada no prompt. Sem o contexto de quem chama essa fun\u00e7\u00e3o, de quais exce\u00e7\u00f5es ela propaga e de que contrato ela cumpre dentro do m\u00f3dulo, a IA inventa detalhes plaus\u00edveis \u2014 e “plaus\u00edvel” nesse contexto \u00e9 sin\u00f4nimo de “inventado”.<\/p>\n

Um prompt de documenta\u00e7\u00e3o eficaz precisa trazer, no m\u00ednimo: a assinatura da fun\u00e7\u00e3o, o corpo completo, os call sites relevantes e os testes existentes (se houver). Um exemplo de estrutura de prompt aplicado a uma fun\u00e7\u00e3o Python real de um sistema de cobran\u00e7a:<\/p>\n

def aplicar_desconto(valor: float, cliente: Cliente, cupom: str | None = None) -> float:\n    if cliente.tipo == TipoCliente.PREMIUM:\n        valor *= 0.9\n    if cupom:\n        desconto = _validar_cupom(cupom, cliente.id)\n        if desconto is None:\n            raise CupomInvalidoError(cupom)\n        valor -= valor * desconto\n    return round(max(valor, 0), 2)\n<\/code><\/pre>\n
O prompt n\u00e3o deve pedir apenas “documente esta fun\u00e7\u00e3o”. Deve incluir o contrato completo:<\/p>\n
Gere uma docstring no padr\u00e3o Google Style para a fun\u00e7\u00e3o abaixo.\nRegras:\n- Descreva o comportamento observ\u00e1vel, n\u00e3o implementa\u00e7\u00e3o interna.\n- Liste TODAS as exce\u00e7\u00f5es que podem ser propagadas, incluindo as de _validar_cupom.\n- Indique explicitamente que o valor final nunca \u00e9 negativo.\n- N\u00e3o invente par\u00e2metros nem retornos que n\u00e3o existem no c\u00f3digo.\n\n[c\u00f3digo completo + assinatura de _validar_cupom]\n<\/code><\/pre>\n
O resultado tende a ser algo como:<\/p>\n
def aplicar_desconto(valor: float, cliente: Cliente, cupom: str | None = None) -> float:\n    \"\"\"Calcula o valor final aplicando desconto de cliente premium e cupom.\n\n    Clientes do tipo PREMIUM recebem 10% de desconto autom\u00e1tico antes\n    da aplica\u00e7\u00e3o do cupom, se houver. O valor final \u00e9 sempre\n    arredondado para duas casas decimais e nunca \u00e9 negativo.\n\n    Args:\n        valor: Valor original antes de descontos.\n        cliente: Cliente associado \u00e0 compra, usado para verificar tipo\n            e validar o cupom.\n        cupom: C\u00f3digo de cupom opcional. Se None, nenhum desconto\n            adicional \u00e9 aplicado.\n\n    Returns:\n        Valor final com descontos aplicados, arredondado e nunca negativo.\n\n    Raises:\n        CupomInvalidoError: Se o cupom informado n\u00e3o for v\u00e1lido para\n            o cliente.\n    \"\"\"\n<\/code><\/pre>\n
Note que a instru\u00e7\u00e3o “n\u00e3o invente par\u00e2metros” n\u00e3o \u00e9 decorativa. \u00c9 a defesa mais barata contra o problema mais comum de documenta\u00e7\u00e3o gerada por IA: adicionar comportamento que soa razo\u00e1vel, mas que n\u00e3o existe \u2014 como assumir que a fun\u00e7\u00e3o trata cupons expirados quando isso nunca foi implementado.<\/p>\n
Camada 2: verifica\u00e7\u00e3o autom\u00e1tica \u2014 o passo que a maioria pula<\/h2>\n
Gerar \u00e9 a parte f\u00e1cil. Verificar \u00e9 a parte que transforma documenta\u00e7\u00e3o em ativo confi\u00e1vel. Existem tr\u00eas verifica\u00e7\u00f5es que valem a pena automatizar em qualquer pipeline:<\/p>\n
1. Consist\u00eancia de assinatura<\/h3>\n
A verifica\u00e7\u00e3o mais barata \u00e9 garantir que os par\u00e2metros documentados batem exatamente com a assinatura real da fun\u00e7\u00e3o. Em Python, isso pode ser feito com a pr\u00f3pria stdlib<\/a> combinando inspect<\/code> com parsing da docstring:<\/p>\n
import inspect\nimport re\n\ndef verificar_parametros_documentados(func) -> list[str]:\n    assinatura = inspect.signature(func)\n    parametros_reais = set(assinatura.parameters.keys()) - {\"self\"}\n\n    docstring = inspect.getdoc(func) or \"\"\n    parametros_doc = set(re.findall(r\"^\\s*(\\w+):\", docstring, re.MULTILINE))\n\n    faltando = parametros_reais - parametros_doc\n    sobrando = parametros_doc - parametros_reais\n\n    erros = []\n    if faltando:\n        erros.append(f\"Par\u00e2metros sem documenta\u00e7\u00e3o: {faltando}\")\n    if sobrando:\n        erros.append(f\"Par\u00e2metros documentados mas inexistentes: {sobrando}\")\n    return erros\n<\/code><\/pre>\n
Rodar essa verifica\u00e7\u00e3o em CI para todo o m\u00f3dulo p\u00fablico \u00e9 barato e pega o erro mais comum: refatorar a fun\u00e7\u00e3o e esquecer de atualizar a docstring \u2014 ou, no caso de gera\u00e7\u00e3o por IA, a IA inventar um par\u00e2metro que n\u00e3o existe na assinatura real.<\/p>\n
2. Exce\u00e7\u00f5es documentadas versus exce\u00e7\u00f5es realmente lan\u00e7adas<\/h3>\n
Esta \u00e9 a verifica\u00e7\u00e3o que mais evita dor de cabe\u00e7a em produ\u00e7\u00e3o. Um analisador est\u00e1tico simples pode varrer o corpo da fun\u00e7\u00e3o em busca de raise<\/code> e comparar com o que est\u00e1 descrito na se\u00e7\u00e3o Raises<\/code>:<\/p>\n
import ast\n\ndef extrair_excecoes_lancadas(codigo_fonte: str, nome_funcao: str) -> set[str]:\n    arvore = ast.parse(codigo_fonte)\n    excecoes = set()\n\n    for node in ast.walk(arvore):\n        if isinstance(node, ast.FunctionDef) and node.name == nome_funcao:\n            for sub in ast.walk(node):\n                if isinstance(sub, ast.Raise) and sub.exc:\n                    if isinstance(sub.exc, ast.Call):\n                        excecoes.add(getattr(sub.exc.func, \"id\", \"Desconhecida\"))\n    return excecoes\n<\/code><\/pre>\n
Esse tipo de checagem est\u00e1tica n\u00e3o substitui um linter completo, mas serve como rede de seguran\u00e7a espec\u00edfica para o problema de documenta\u00e7\u00e3o: a IA descreveu uma exce\u00e7\u00e3o que o c\u00f3digo n\u00e3o lan\u00e7a, ou \u2014 pior \u2014 o c\u00f3digo lan\u00e7a uma exce\u00e7\u00e3o que ningu\u00e9m documentou, e o time s\u00f3 descobre isso em produ\u00e7\u00e3o.<\/p>\n
3. Exemplos de c\u00f3digo execut\u00e1veis (doctest como contrato)<\/h3>\n
Sempre que a IA gerar um exemplo de uso dentro da docstring, esse exemplo deve ser execut\u00e1vel e testado, n\u00e3o apenas ilustrativo. Usar doctest<\/a> transforma a documenta\u00e7\u00e3o em teste de regress\u00e3o:<\/p>\n
def aplicar_desconto(valor: float, cliente: Cliente, cupom: str | None = None) -> float:\n    \"\"\"Calcula o valor final aplicando desconto de cliente premium e cupom.\n\n    Exemplo:\n        >>> cliente = Cliente(tipo=TipoCliente.PREMIUM)\n        >>> aplicar_desconto(100.0, cliente)\n        90.0\n    \"\"\"\n<\/code><\/pre>\n
Rodar python -m doctest -v arquivo.py<\/code> em CI garante que, se o comportamento mudar (por exemplo, o desconto premium passar de 10% para 15%), o pipeline quebra imediatamente \u2014 n\u00e3o seis meses depois, quando algu\u00e9m confiar cegamente no exemplo desatualizado.<\/p>\n
Camada 3: pipeline em CI \u2014 do commit ao README atualizado<\/h2>\n
Com gera\u00e7\u00e3o e verifica\u00e7\u00e3o definidas, o pr\u00f3ximo passo \u00e9 orquestrar isso como parte do fluxo de integra\u00e7\u00e3o cont\u00ednua, n\u00e3o como uma tarefa manual eventual. Um desenho comum de pipeline:<\/p>\n