Documentação com IA: do README ao changelog

Para escrever documentação com IA, deixe um agente de código ler o código e rodar os comandos que ele documenta, dê a cada documento um público claro e confira no repositório cada função, flag e exemplo mencionado. Agentes como o Claude Code e o Codex são bons nas partes tediosas da documentação: transformar uma base de código em um README, preencher docstrings, resumir uma versão a partir do histórico do git. O ponto fraco deles é a confiança: vão descrever uma opção que parece certa, mas nunca foi implementada.

Este guia cobre o que documentar com um agente, prompts que funcionam para cada tipo de documento, como gerar changelogs a partir do git log, como manter a documentação sincronizada, onde entra o AGENTS.md e como revisar documentação escrita por IA em busca de APIs inventadas.

Agente, não janela de chat

O maior salto de qualidade vem de onde o modelo escreve. Colar um arquivo em uma janela de chat e pedir documentação dá ao modelo um único arquivo e nenhuma forma de verificar nada. Um agente de código rodando no seu repositório pode:

• abrir os arquivos que o código chama, não só aquele que você colou;
• rodar --help, a suíte de testes ou o exemplo que acabou de escrever;
• buscar todos os lugares onde uma função é usada;
• ler a documentação existente e seguir o mesmo estilo.

Todos os prompts abaixo assumem que o agente está rodando no repositório. Se você ainda não configurou um, como usar o Claude Code e como usar o Codex CLI levam você até lá.

Defina o público primeiro

“Escreva a documentação deste projeto” produz uma página genérica. Cada tipo de documento tem um leitor diferente e uma fonte de verdade diferente:

Coloque o leitor e a fonte no prompt. Isso muda o resultado mais do que qualquer instrução de estilo.

README

Um bom README responde rápido a quatro perguntas: o que é isto, como instalo, como uso e como contribuo. Peça ao agente para verificar enquanto escreve:

Write README.md for this repository. Audience: a developer seeing it
for the first time. Sections: what it does (2-3 sentences), requirements,
install, quick start, configuration, running tests, project layout.

Rules:
- Take commands from package.json scripts and the CI workflow; run each
  install and quick-start command and fix the README if one fails.
- List only environment variables that are actually read in the code;
  cite the file for each.
- No badges, no marketing language, no features that aren't in the code.

“Rode cada comando” é o que transforma um README plausível em um correto. Se o agente não conseguir rodar algo (porque precisa de credenciais, por exemplo), peça para marcar esse passo como não verificado, para você conferir à mão.

Referência de API

Para bibliotecas e serviços, gere o máximo possível da referência a partir do código-fonte, e use o agente nas partes que os geradores não escrevem: visões gerais, exemplos e explicações de comportamentos complicados.

Para uma API HTTP, peça ao agente que monte a referência a partir das próprias definições de rotas:

Document every HTTP endpoint in src/routes. For each: method, path,
auth requirement, request body and query parameters with types,
response shape, error status codes. Read the handler and the
validation schema; don't infer from names. Add one curl example per
endpoint and run it against the local dev server.

Se o projeto já usa OpenAPI, peça ao agente para atualizar o arquivo de especificação em vez de escrever uma referência separada em Markdown, e deixe suas ferramentas atuais renderizá-lo. Uma única fonte de verdade é mais fácil de manter honesta do que duas.

Docstrings e JSDoc

Agentes preenchem docstrings de um módulo inteiro rapidamente, e é justamente aí que mais descrevem o que uma função deveria fazer em vez do que ela faz. Peça o comportamento visível no corpo:

Add JSDoc to every exported function in src/billing/. For each:
one-line summary, @param with type and meaning, @returns, and @throws
for every error the function can actually throw (read the body and
the functions it calls). Add an @example only if you run it.
Don't change any code.

Duas verificações baratas tornam as docstrings confiáveis:

• TypeScript em projetos JS: com // @ts-check no topo de um arquivo ou checkJs no tsconfig.json, o TypeScript verifica os tipos do JSDoc, então um tipo de @param errado aparece como erro.
• Python: exemplos escritos no formato doctest (linhas >>>) podem ser executados com python -m doctest module.py -v, então um exemplo que se afasta do código falha.

Uma regra prática útil: uma docstring deve dizer por quê e para quê, não repetir a assinatura. “Retorna o usuário” em getUser(id): User é ruído; “Retorna null para usuários com exclusão lógica; quem chama precisa tratar isso” vale a pena. Diga isso ao agente.

Notas de arquitetura

Documentação de arquitetura é onde os agentes mais economizam tempo, porque a parte difícil é ler muito código e resumi-lo. É também onde as alucinações se escondem melhor, já que ninguém confere um diagrama linha por linha. Restrinja:

Write docs/architecture.md for engineers new to the codebase.
Cover: the main modules and what each owns, how a request flows from
the HTTP layer to the database, background jobs, and external services.
For every claim, cite the file (and function) it comes from.
Include a Mermaid diagram of the request flow.
Mark anything you're unsure about with "TODO: verify".

As citações são o ponto principal: deixam um revisor checar afirmações por amostragem em segundos e mostram quais partes vão ficar desatualizadas quando esses arquivos mudarem. Registre por que as decisões foram tomadas, não só o que existe; um registro curto de decisões (no estilo ADR: contexto, decisão, consequências) envelhece melhor do que uma descrição do código atual. Um mapa da base de código para agentes de IA trata do problema relacionado de dar aos agentes uma visão geral navegável.

Changelogs a partir do git log

Notas de versão são a tarefa perfeita para um agente: a matéria-prima está no git, e o trabalho é filtrar e reescrever para os usuários. Comece pelo intervalo desde a última tag:

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Depois, o prompt:

Write the CHANGELOG.md entry for the next release from
git log v1.4.0..HEAD --no-merges. Audience: users upgrading.
Use the Keep a Changelog headings (Added, Changed, Deprecated,
Removed, Fixed, Security). Skip refactors, tests, CI and chores.
Rewrite each entry in user terms, put breaking changes first with
upgrade steps, and keep the short hash next to each entry.

Se a sua equipe escreve Conventional Commits (feat:, fix:, feat!: para mudanças incompatíveis), mencione isso; o agente consegue ordenar por tipo com segurança. Se as mensagens de commit forem curtas demais, deixe o agente ler o diff (git show <hash>) ou o pull request vinculado nos itens que importam. Manter o hash ao lado de cada linha torna a revisão rápida: você confere um item abrindo o commit dele.

Mantendo a documentação sincronizada

A documentação apodrece porque é atualizada em uma etapa separada que ninguém agenda. A solução é tornar a documentação parte da mudança:

1. Mesma mudança, mesmo agente. Adicione uma linha às regras do seu agente: “Quando você mudar comportamento, flags, variáveis de ambiente ou APIs públicas, atualize a documentação relacionada no mesmo commit.”

2. Peça uma verificação da documentação ao fim de cada tarefa:

   List every doc, README section, docstring and example that mentions
   the code you changed. Update the ones that are now wrong.

3. Confira uma branch antes do merge: dê ao agente o diff (git diff main...HEAD) e a pasta de documentação e pergunte quais afirmações da documentação o diff torna falsas.

4. Rode os exemplos como testes. Doctests, um script que executa os trechos do README ou JSDoc com verificação de tipos transformam documentação desatualizada em build quebrado.

5. Gere o que puder. Texto de ajuda da CLI, especificações OpenAPI e referências de tipos geradas a partir do código-fonte não ficam defasados.

O AGENTS.md não é a sua documentação

O AGENTS.md (lido pelo Codex e por muitos outros agentes) e o CLAUDE.md (lido pelo Claude Code) são arquivos de instruções para agentes de código. Eles são carregados em toda sessão, então devem ser curtos: comandos de build e teste, convenções, pastas que não devem ser tocadas. Rodar /init no Claude Code ou no Codex gera uma primeira versão.

A sua documentação para pessoas tem outra função e pode ser tão longa quanto precisar. Misturar as duas causa dois problemas: um AGENTS.md longo desperdiça o contexto do agente em toda tarefa, e um README cheio de regras para agentes confunde as pessoas. Mantenha-os separados e crie links entre eles:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md vs AGENTS.md explica o que deve entrar nesses arquivos e como compartilhar um único conjunto de regras entre agentes.

Revise a documentação escrita por IA em busca de APIs alucinadas

O bug de documentação mais danoso é uma API que não existe: uma opção de configuração, uma flag de CLI ou um método que o modelo inventou porque projetos parecidos têm. Os leitores confiam na documentação, então perdem tempo antes de suspeitar dela. Revise com esse objetivo:

• Faça grep de cada nome. Peça ao agente (ou a um segundo agente) para extrair cada função, opção, flag, variável de ambiente e endpoint mencionados na nova documentação e buscar cada um no código. O que não for encontrado sai.

  Extract every identifier, CLI flag, config key and env var from
  docs/api.md. For each, show where it is defined in the code with
  file:line, or say NOT FOUND. Don't edit anything.

• Rode cada exemplo. Blocos de código que nunca foram executados são palpites.

• Confira padrões e limites. Números (timeouts, tamanhos, tentativas) muitas vezes são inventados; cada um deve ser rastreável até uma constante no código.

• Desconfie de “também suporta”. Frases como “também suporta configuração em YAML” ou “pode ser usado com Redis” são enchimento clássico. Peça o código que faz isso.

• Use um segundo revisor. Um agente separado revisando a documentação contra o código é menos apegado a ela do que quem a escreveu. Revisão de código com IA mostra como configurar isso.

Documentação com o AgentVera

O AgentVera é um app desktop para macOS, Windows e Linux que roda Claude Code, Codex, Gemini CLI e outros agentes de CLI lado a lado. Algumas das ferramentas dele ajudam com documentação:

• Escritor e revisor lado a lado: rode um agente escrevendo a documentação e outro conferindo-a contra o código no mesmo workspace, ou dê ao trabalho de documentação seu próprio worktree.
• Aba Specs: lista os arquivos Markdown do repositório, dos mais novos para os mais antigos, separados em specs, planos e documentos, incluindo arquivos sem commit que agentes escreveram em outros worktrees. O Markdown abre em pré-visualização.
• Brain: lê seu README, ARCHITECTURE, CHANGELOG, ADRs, commits e PRs, lista as decisões com seus motivos e sinaliza aquelas cujos termos de código não aparecem mais no código, um bom sinal de documentação desatualizada.
• Tour do projeto: uma execução somente leitura do Claude Code que resume a stack, os módulos e os arquivos principais de um repositório, um bom rascunho inicial para notas de arquitetura.
• Revisão de código: revise as mudanças de documentação de um agente com o modelo Claude que você escolher, com apontamentos vinculados a arquivo e linha.
• Painel Git: navegue pelo histórico a partir do qual você monta os changelogs e deixe o Claude Haiku escrever mensagens de commit no estilo do seu repositório, o que facilita o próximo changelog.

Conclusão

A IA torna a documentação barata de escrever, o que faz da precisão o trabalho de verdade. Rode o agente dentro do repositório, diga a ele quem é o leitor e onde está a verdade, faça-o rodar comandos e exemplos e monte changelogs a partir do git log mantendo os hashes. Atualize a documentação na mesma mudança do código, deixe o AGENTS.md para os agentes e a documentação para as pessoas, e faça grep de cada nome documentado antes de publicar. Quando uma documentação revelar um bug, depurar código com IA continua a partir daí.