Existe um cen\u00e1rio que se repete em praticamente toda empresa que adotou gera\u00e7\u00e3o de documenta\u00e7\u00e3o com IA sem pensar em arquitetura: algu\u00e9m roda um comando, um LLM l\u00ea o c\u00f3digo, produz um markdown bonito, o time comemora, faz commit, e seis meses depois aquele documento descreve uma API que j\u00e1 foi refatorada tr\u00eas vezes. Ningu\u00e9m percebeu porque a documenta\u00e7\u00e3o “existia” \u2014 s\u00f3 n\u00e3o era mais verdade. O problema n\u00e3o \u00e9 a IA ter gerado algo errado no momento zero. \u00c9 que ningu\u00e9m desenhou um mecanismo para que a documenta\u00e7\u00e3o continuasse correta quando o c\u00f3digo mudasse. Voc\u00ea trocou o problema “documenta\u00e7\u00e3o inexistente” pelo problema, mais sutil e mais perigoso, “documenta\u00e7\u00e3o obsoleta com apar\u00eancia de autoridade”.<\/p>\n
Esse \u00e9 o ponto cego de quase todo tutorial de “gere docs com IA em 5 minutos”: eles resolvem a gera\u00e7\u00e3o, n\u00e3o o ciclo de vida. Para quem j\u00e1 vive esse problema em produ\u00e7\u00e3o, a pergunta relevante n\u00e3o \u00e9 “como pe\u00e7o para o Claude documentar essa fun\u00e7\u00e3o”, mas “que arquitetura garante que a documenta\u00e7\u00e3o gerada por IA continue confi\u00e1vel daqui a um ano, sem revis\u00e3o manual constante”. \u00c9 isso que vamos desenhar aqui: um pipeline de documenta\u00e7\u00e3o viva, com verifica\u00e7\u00e3o autom\u00e1tica, versionamento sem\u00e2ntico de conte\u00fado e pontos de falha expl\u00edcitos \u2014 n\u00e3o mais um passo a passo de prompt engineering.<\/p>\n
A maior parte das ferramentas de “AI docs” trata documenta\u00e7\u00e3o como um artefato gerado uma vez: voc\u00ea aponta para um reposit\u00f3rio, ela cospe um README ou um conjunto de p\u00e1ginas, fim. Isso funciona bem para demos e mal para sistemas que evoluem em produ\u00e7\u00e3o. O modelo mental correto \u00e9 tratar documenta\u00e7\u00e3o como um build target<\/em> \u2014 algo que \u00e9 recompilado a partir do c\u00f3digo-fonte sempre que este muda, exatamente como voc\u00ea recompila um bin\u00e1rio.<\/p>\n Isso muda completamente as decis\u00f5es de arquitetura:<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> o conceito de “docs as code” \u2014 tratar documenta\u00e7\u00e3o com o mesmo rigor de versionamento, revis\u00e3o e CI que se aplica a software \u2014 \u00e9 discutido em profundidade por Anne Gentle em Docs Like Code<\/em>. A tese central: documenta\u00e7\u00e3o que n\u00e3o passa por pipeline de build e teste automaticamente decai. IA n\u00e3o elimina essa lei, apenas muda quem escreve o primeiro rascunho.<\/p><\/blockquote>\n Uma pipeline madura de documenta\u00e7\u00e3o assistida por IA separa claramente tr\u00eas responsabilidades que costumam ser misturadas em solu\u00e7\u00f5es ing\u00eanuas:<\/p>\n Respons\u00e1vel por produzir o conte\u00fado textual a partir do c\u00f3digo-fonte, assinaturas de fun\u00e7\u00e3o, coment\u00e1rios estruturados e, idealmente, exemplos de uso extra\u00eddos de testes reais. Aqui entra o LLM.<\/p>\n Respons\u00e1vel por validar que o que foi gerado corresponde ao estado atual do c\u00f3digo: assinaturas batem, exemplos de c\u00f3digo compilam e executam, links internos resolvem, par\u00e2metros documentados existem de fato na fun\u00e7\u00e3o.<\/p>\n Respons\u00e1vel por versionar, indexar e disponibilizar o conte\u00fado \u2014 site est\u00e1tico, portal interno, ou inje\u00e7\u00e3o em um \u00edndice de RAG para atendimento e onboarding.<\/p>\n A falha mais comum \u00e9 pular a camada 2 inteiramente. \u00c9 ela que transforma “documenta\u00e7\u00e3o gerada por IA” em “documenta\u00e7\u00e3o confi\u00e1vel gerada por IA”. Sem verifica\u00e7\u00e3o, voc\u00ea est\u00e1 apenas automatizando a produ\u00e7\u00e3o de alucina\u00e7\u00e3o plaus\u00edvel em escala.<\/p>\n O erro cl\u00e1ssico \u00e9 jogar arquivos de c\u00f3digo inteiros para o modelo e pedir “documente isso”. Funciona mal em bases grandes porque o modelo perde o contexto de contratos externos (quem chama essa fun\u00e7\u00e3o, o que espera como retorno, quais invariantes existem). A abordagem que escala \u00e9 gerar contexto estruturado primeiro, depois delegar apenas a reda\u00e7\u00e3o para a IA.<\/p>\n Exemplo em TypeScript, extraindo metadados via AST antes de acionar o modelo:<\/p>\n Esse JSON estruturado \u2014 n\u00e3o o arquivo bruto \u2014 \u00e9 o que voc\u00ea envia ao modelo. O prompt fica objetivo e ancorado em fatos verific\u00e1veis, reduzindo drasticamente a superf\u00edcie de alucina\u00e7\u00e3o:<\/p>\n Repare na instru\u00e7\u00e3o expl\u00edcita para admitir incerteza. Isso \u00e9 decis\u00e3o de arquitetura, n\u00e3o estilo de prompt: voc\u00ea est\u00e1 desenhando um sistema que prefere lacunas vis\u00edveis a preenchimento confiante e falso. Um “TODO” \u00e9 um sinal barato de resolver depois; uma descri\u00e7\u00e3o de comportamento inventada \u00e9 uma mina que vai explodir na produ\u00e7\u00e3o de outra pessoa.<\/p>\n \u00c9 aqui que a arquitetura s\u00e9ria se separa da demo de confer\u00eancia. Tr\u00eas verifica\u00e7\u00f5es m\u00ednimas que qualquer pipeline de docs-por-IA deveria ter:<\/p>\n Compare os par\u00e2metros documentados contra a assinatura real extra\u00edda via AST ou reflection. Um script simples de diff resolve grande parte dos casos:<\/p>\n Todo exemplo de c\u00f3digo dentro da documenta\u00e7\u00e3o deve ser extra\u00eddo e executado como teste. Ferramentas como doctests do Rust<\/a> j\u00e1 resolvem isso nativamente h\u00e1 anos \u2014 a li\u00e7\u00e3o vale para qualquer stack: se o exemplo n\u00e3o roda, o build quebra.<\/p>\n Para linguagens sem suporte nativo, voc\u00ea constr\u00f3i isso com um extrator simples de blocos de c\u00f3digo com marca\u00e7\u00e3o especial:<\/p>\n Mais avan\u00e7ada e mais cara: usar um segundo modelo para comparar a descri\u00e7\u00e3o de comportamento documentada contra o comportamento observado em testes existentes, sinalizando diverg\u00eancias para revis\u00e3o humana em vez de aprova\u00e7\u00e3o autom\u00e1tica. Esse \u00e9 o mesmo princ\u00edpio discutido no problema do “aprovador autom\u00e1tico” em code review \u2014 nunca deixe a IA ser juiz e r\u00e9u do pr\u00f3prio trabalho sem um humano no la\u00e7o para casos amb\u00edguos.<\/p>\n A decis\u00e3o de arquitetura mais importante \u00e9 tratar falha de documenta\u00e7\u00e3o com a mesma severidade de falha de teste. Um exemplo de pipeline com GitHub Actions:<\/p>\n Note a \u00faltima etapa: ela \u00e9 uma escolha deliberada de pol\u00edtica de qualidade, n\u00e3o uma verifica\u00e7\u00e3o t\u00e9cnica. Times s\u00e9rios decidem, como regra de neg\u00f3cio, que documenta\u00e7\u00e3o incompleta bloqueia merge. Isso \u00e9 caro no curto prazo e evita a acumula\u00e7\u00e3o silenciosa de d\u00edvida documental \u2014 o mesmo trade-off que se aplica a cobertura de testes m\u00ednima obrigat\u00f3ria.<\/p>\n LLMs s\u00e3o excelentes em descrever o que uma fun\u00e7\u00e3o retorna, e sistematicamente ruins em capturar efeitos colaterais n\u00e3o expl\u00edcitos na assinatura \u2014 uma fun\u00e7\u00e3o que parece pura, mas dispara um evento ass\u00edncrono, grava em cache ou modifica estado global. Nenhuma verifica\u00e7\u00e3o de assinatura pega isso. A mitiga\u00e7\u00e3o pr\u00e1tica \u00e9 conven\u00e7\u00e3o de c\u00f3digo: efeitos colaterais devem ser sinalizados explicitamente via nomenclatura ou anota\u00e7\u00e3o ( Quando uma fun\u00e7\u00e3o se comporta diferente dependendo de feature flags ou de vers\u00e3o de configura\u00e7\u00e3o, a documenta\u00e7\u00e3o gerada automaticamente tende a descrever apenas o caminho “feliz” mais comum no c\u00f3digo analisado. Isso exige uma camada adicional: gerar documenta\u00e7\u00e3o por variante de configura\u00e7\u00e3o, n\u00e3o uma \u00fanica passada gen\u00e9rica. Trata-se de mais engenharia de pipeline, n\u00e3o de melhor prompt.<\/p>\n Times que documentam APIs p\u00fablicas a partir de contratos como OpenAPI<\/a> t\u00eam vantagem estrutural aqui: o contrato j\u00e1 \u00e9 a fonte de verdade, e a IA s\u00f3 precisa gerar prosa a partir dele \u2014 n\u00e3o inferir comportamento a partir de implementa\u00e7\u00e3o, que \u00e9 uma tarefa fundamentalmente mais sujeita a erro.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> sempre que poss\u00edvel, inverta a ordem: escreva o contrato formal (OpenAPI, protobuf, JSON Schema) primeiro, gere a implementa\u00e7\u00e3o e a documenta\u00e7\u00e3o como duas sa\u00eddas independentes do mesmo contrato. Isso elimina a classe inteira de erros em que docs e c\u00f3digo divergem, porque ambos derivam da mesma fonte \u2014 o mesmo princ\u00edpio central por tr\u00e1s de spec driven development.<\/p><\/blockquote>\n Pipelines de documenta\u00e7\u00e3o autom\u00e1tica n\u00e3o s\u00e3o gratuitas depois de montadas. Existem tr\u00eas custos recorrentes que precisam entrar na decis\u00e3o de arquitetura desde o in\u00edcio:<\/p>\n Quando esse custo total supera o custo de manter documenta\u00e7\u00e3o manual disciplinada em times pequenos, a automa\u00e7\u00e3o n\u00e3o vale a pena. A decis\u00e3o correta depende de escala: equipes com dezenas de servi\u00e7os e rotatividade de pessoas se beneficiam enormemente; um time de tr\u00eas pessoas em um mon\u00f3lito est\u00e1vel pode preferir disciplina manual com revis\u00e3o em PR.<\/p>\n Vale ser honesto sobre os limites. Documenta\u00e7\u00e3o gerada automaticamente tende a ser fraca em tr\u00eas cen\u00e1rios espec\u00edficos:<\/p>\n A arquitetura correta reconhece essa fronteira: documenta\u00e7\u00e3o de refer\u00eancia t\u00e9cnica (par\u00e2metros, retornos, exemplos) \u00e9 candidata forte \u00e0 automa\u00e7\u00e3o total. Documenta\u00e7\u00e3o de inten\u00e7\u00e3o e arquitetura continua sendo trabalho humano, no m\u00e1ximo assistido por IA como redator, nunca como fonte de verdade.<\/p>\n Arquitetar pipelines de documenta\u00e7\u00e3o que sobrevivem a refatora\u00e7\u00f5es, mudan\u00e7as de equipe e anos de manuten\u00e7\u00e3o \u00e9 um problema de engenharia, n\u00e3o de prompt. Se voc\u00ea quer trocar experi\u00eancias reais sobre isso \u2014 o que funcionou, o que quebrou em produ\u00e7\u00e3o, como outras equipes calibraram o trade-off entre automa\u00e7\u00e3o e revis\u00e3o humana \u2014 entre na Comunidade Dev’s AI<\/a>. \u00c9 um espa\u00e7o de desenvolvedores seniores discutindo arquitetura de sistemas com IA aplicada, sem o superficialismo dos tutoriais de “gere isso em 5 minutos”.<\/p>\n Documenta\u00e7\u00e3o gerada por IA sem arquitetura de verifica\u00e7\u00e3o \u00e9 apenas d\u00edvida t\u00e9cnica com boa apar\u00eancia tipogr\u00e1fica. O valor real n\u00e3o est\u00e1 na capacidade do modelo de escrever prosa fluente sobre uma fun\u00e7\u00e3o \u2014 isso qualquer LLM moderno faz bem. O valor est\u00e1 no pipeline que garante que essa prosa continue verdadeira depois que tr\u00eas engenheiros diferentes tiverem mexido naquele c\u00f3digo seis meses depois. Trate documenta\u00e7\u00e3o como build target, separe gera\u00e7\u00e3o de verifica\u00e7\u00e3o, torne diverg\u00eancia um erro de CI e reserve para humanos o que s\u00f3 humanos sabem: por que as decis\u00f5es foram tomadas. Feito assim, a IA deixa de ser um gerador de texto plaus\u00edvel e passa a ser o que ela deveria ter sido desde o in\u00edcio \u2014 uma parte confi\u00e1vel da sua esteira de entrega de software.<\/p>\n","protected":false},"excerpt":{"rendered":" Existe um cen\u00e1rio que se repete em praticamente toda empresa que adotou gera\u00e7\u00e3o de documenta\u00e7\u00e3o com IA sem pensar em arquitetura: algu\u00e9m roda um comando, um LLM l\u00ea o c\u00f3digo, produz um markdown bonito, o time comemora, faz commit, e seis meses depois aquele documento descreve uma API que j\u00e1 foi refatorada tr\u00eas vezes. Ningu\u00e9m […]<\/p>\n","protected":false},"author":127,"featured_media":1089,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1088","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog"],"_links":{"self":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1088","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/users\/127"}],"replies":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/comments?post=1088"}],"version-history":[{"count":1,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1088\/revisions"}],"predecessor-version":[{"id":1090,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1088\/revisions\/1090"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media\/1089"}],"wp:attachment":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media?parent=1088"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/categories?post=1088"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/tags?post=1088"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\n
Arquitetura em tr\u00eas camadas: gera\u00e7\u00e3o, verifica\u00e7\u00e3o e publica\u00e7\u00e3o<\/h2>\n
1. Camada de gera\u00e7\u00e3o<\/h3>\n
2. Camada de verifica\u00e7\u00e3o<\/h3>\n
3. Camada de publica\u00e7\u00e3o<\/h3>\n
Passo a passo: construindo a camada de gera\u00e7\u00e3o com contexto estrutural<\/h2>\n
\/\/ extract-context.ts\nimport { Project } from \"ts-morph\";\n\nconst project = new Project({ tsConfigFilePath: \"tsconfig.json\" });\nconst sourceFile = project.getSourceFileOrThrow(\"src\/billing\/invoice.ts\");\n\nconst functions = sourceFile.getFunctions().map((fn) => ({\n name: fn.getName(),\n params: fn.getParameters().map((p) => ({\n name: p.getName(),\n type: p.getType().getText(),\n })),\n returnType: fn.getReturnType().getText(),\n jsDoc: fn.getJsDocs().map((d) => d.getText()),\n callers: fn.findReferencesAsNodes().length,\n}));\n\nconsole.log(JSON.stringify(functions, null, 2));\n<\/code><\/pre>\nimport anthropic\n\nclient = anthropic.Anthropic()\n\ndef generate_doc(function_metadata: dict) -> str:\n prompt = f\"\"\"\nVoc\u00ea \u00e9 um redator t\u00e9cnico. Gere documenta\u00e7\u00e3o em formato JSDoc\nestritamente baseada nos metadados abaixo. N\u00e3o invente par\u00e2metros,\ncomportamentos ou exemplos que n\u00e3o possam ser inferidos dos tipos.\nSe n\u00e3o houver informa\u00e7\u00e3o suficiente para descrever o comportamento,\nescreva \"TODO: descri\u00e7\u00e3o pendente de revis\u00e3o humana\".\n\nMetadados:\n{function_metadata}\n\"\"\"\n response = client.messages.create(\n model=\"claude-sonnet-4-5\",\n max_tokens=500,\n messages=[{\"role\": \"user\", \"content\": prompt}],\n )\n return response.content[0].text\n<\/code><\/pre>\nCamada de verifica\u00e7\u00e3o: o que a maioria das solu\u00e7\u00f5es de mercado ignora<\/h2>\n
Verifica\u00e7\u00e3o de assinatura<\/h3>\n
def verify_signature(documented_params: list[str], actual_params: list[str]) -> list[str]:\n missing = set(actual_params) - set(documented_params)\n extra = set(documented_params) - set(actual_params)\n errors = []\n if missing:\n errors.append(f\"Par\u00e2metros n\u00e3o documentados: {missing}\")\n if extra:\n errors.append(f\"Par\u00e2metros documentados mas inexistentes: {extra}\")\n return errors\n<\/code><\/pre>\nVerifica\u00e7\u00e3o de exemplos execut\u00e1veis<\/h3>\n
# extract_examples.py\nimport re\nimport subprocess\n\ndef extract_code_blocks(markdown_path: str) -> list[str]:\n content = open(markdown_path).read()\n return re.findall(r\"```python\\n(.*?)```\", content, re.DOTALL)\n\ndef run_example(code: str) -> bool:\n result = subprocess.run(\n [\"python\", \"-c\", code],\n capture_output=True,\n timeout=10,\n )\n return result.returncode == 0\n\nfor block in extract_code_blocks(\"docs\/billing.md\"):\n if not run_example(block):\n raise SystemExit(\"Exemplo de documenta\u00e7\u00e3o falhou na execu\u00e7\u00e3o\")\n<\/code><\/pre>\nVerifica\u00e7\u00e3o de deriva sem\u00e2ntica<\/h3>\n
Integrando ao CI: documenta\u00e7\u00e3o quebra o build, n\u00e3o \u00e9 sugest\u00e3o<\/h2>\n
name: docs-verify\n\non:\n pull_request:\n paths:\n - \"src\/**\"\n - \"docs\/**\"\n\njobs:\n verify-docs:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - uses: actions\/setup-python@v5\n with:\n python-version: \"3.12\"\n - run: pip install -r requirements-docs.txt\n - name: Extrair contexto do c\u00f3digo\n run: python scripts\/extract_context.py\n - name: Gerar documenta\u00e7\u00e3o\n run: python scripts\/generate_docs.py\n - name: Verificar assinaturas\n run: python scripts\/verify_signature.py\n - name: Executar exemplos documentados\n run: python scripts\/extract_examples.py\n - name: Bloquear merge se houver TODO n\u00e3o resolvido\n run: |\n if grep -r \"TODO: descri\u00e7\u00e3o pendente\" docs\/; then\n echo \"Documenta\u00e7\u00e3o incompleta detectada\"\n exit 1\n fi\n<\/code><\/pre>\nCasos dif\u00edceis que a documenta\u00e7\u00e3o oficial das ferramentas n\u00e3o menciona<\/h2>\n
C\u00f3digo com efeitos colaterais impl\u00edcitos<\/h3>\n
@sideEffect<\/code>, sufixo _mut<\/code>, etc.), porque a IA s\u00f3 documenta bem o que o c\u00f3digo j\u00e1 exp\u00f5e estruturalmente.<\/p>\nAPIs versionadas com comportamento condicional<\/h3>\n
Deriva entre documenta\u00e7\u00e3o p\u00fablica e c\u00f3digo privado interno<\/h3>\n
Custo de manuten\u00e7\u00e3o: o que ningu\u00e9m calcula antes de adotar<\/h2>\n
\n
Quando n\u00e3o vale a pena automatizar<\/h2>\n
\n
Aprofunde essa discuss\u00e3o com quem j\u00e1 enfrentou esses problemas em produ\u00e7\u00e3o<\/h2>\n
Conclus\u00e3o<\/h2>\n