# Documentação com IA: do README ao changelog

URL: https://agentvera.dev/pt/blog/write-documentation-with-ai/ · Publicado: 2026-10-27

Escreva documentação com IA que continua correta: READMEs, docs de API, docstrings, notas de arquitetura e changelogs do git log, sem APIs inventadas.

**Resumo:**

- Um agente de código escreve boa documentação quando lê o código real e roda os comandos reais; um modelo de chat escrevendo de memória inventa flags, opções e funções.
- Use-o para READMEs, referências de API, docstrings e JSDoc, notas de arquitetura e changelogs gerados do git log, e dê a cada um um público e uma fonte claros.
- Mantenha a documentação sincronizada atualizando-a na mesma mudança do código, deixe o AGENTS.md só para regras de agentes e confira cada API documentada no código.

**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](/pt/blog/how-to-use-claude-code/ "Como usar o Claude Code") e [como usar o Codex CLI](/pt/blog/how-to-use-codex-cli/ "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:

| Documento | Leitor | Fonte de verdade |
| --- | --- | --- |
| README | Novo usuário ou contribuidor | Manifesto do pacote, scripts, pontos de entrada |
| Referência de API | Desenvolvedor que chama o seu código | Assinaturas de funções, tipos, definições de rotas |
| Docstrings / JSDoc | Quem lê ou chama uma função | O corpo da função e quem a chama |
| Notas de arquitetura | Engenheiro que vai mudar o sistema | Estrutura de módulos, fluxo de dados, decisões |
| Changelog | Usuários que vão atualizar | Commits e pull requests desde a última versão |
| AGENTS.md / CLAUDE.md | Agentes de código | As regras e comandos da sua equipe |

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:

```text
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:

```text
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:

```text
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:

```text
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](/pt/blog/codebase-map-for-ai-agents/ "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:

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

Depois, o prompt:

```text
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](https://www.conventionalcommits.org/ "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:**

   ```text
   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:

```markdown
# 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](/pt/blog/claude-md-agents-md/ "CLAUDE.md e 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.

  ```text
  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](/pt/blog/ai-code-review/ "Revisão de código com IA") mostra como configurar isso.

## Documentação com o AgentVera

O [AgentVera](/pt/download/ "Baixar 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](/pt/features/workspace/ "Workspace"), ou dê ao trabalho de documentação seu próprio worktree.
- **[Aba Specs](/pt/features/editor-and-terminal/ "Editor, terminal e 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](/pt/features/brain/ "AgentVera 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](/pt/features/project-tour-and-code-map/ "Tour do projeto e mapa de código"):** 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](/pt/features/code-review/ "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](/pt/features/git-and-github/ "Git e GitHub"):** 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](/pt/blog/debug-code-with-ai/ "Depurar código com IA") continua a partir daí.

## Perguntas frequentes

**A IA consegue escrever boa documentação?** Sim, se trabalhar a partir do código. Um agente de código que pode abrir arquivos, rodar comandos e testar exemplos escreve READMEs, docs de API e docstrings precisos. Um modelo escrevendo de memória, sem o repositório, tende a inventar opções e nomes de funções que parecem certos, mas não existem.

**Como gero um changelog a partir do git log com IA?** Dê ao agente o intervalo desde a última versão, por exemplo git log v1.4.0..HEAD --no-merges, e peça que agrupe as mudanças visíveis ao usuário em seções como Added, Changed, Fixed e Removed, ignorando refatorações e tarefas de manutenção. Depois confira cada item com o seu commit.

**Qual a diferença entre AGENTS.md e a documentação do projeto?** O AGENTS.md (ou CLAUDE.md) é um conjunto curto de instruções para agentes de código: comandos, convenções e o que evitar. A documentação do projeto é para pessoas: o que o projeto faz, como usá-lo e como ele é construído. Mantenha os dois separados e crie links entre eles em vez de copiar.

**Como evito que a IA invente APIs na documentação?** Diga ao agente para documentar só o que encontrar no código, citar o arquivo de cada função ou opção e rodar cada exemplo de código. Depois busque no código cada nome que aparece na documentação; o que não for encontrado é uma alucinação a remover.

**Como mantenho a documentação sincronizada com o código?** Atualize a documentação na mesma mudança do código, peça ao agente que liste as docs afetadas ao fim de cada tarefa, gere a documentação de referência a partir do código-fonte quando puder e rode os exemplos da documentação como testes, para que os desatualizados falhem.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/