# Agentes e skills para documentação técnica

READMEs, docs de API, ADRs, diagramas e changelogs que não envelhecem

A documentação técnica costuma ser a primeira coisa a ficar para trás. O código muda todas as semanas, o README continua a descrever a instalação de há um ano e a especificação da API vive num documento que ninguém abre desde a última migração. O custo aparece tarde: cada pessoa nova perde dias a perceber o que já estava decidido, e ninguém se lembra do porquê.

Os componentes desta página tratam a documentação como resultado de um processo e não como tarefa manual adiada. Geram referências de API a partir do código, escrevem Registos de Decisão de Arquitetura (ADR) com contexto e alternativas, desenham diagramas em Mermaid ou no modelo C4, montam o changelog a partir do histórico de commits e verificam se os ficheiros existentes ainda correspondem ao que está implementado.

Comece pelo que dói mais no seu projeto. Se ninguém consegue arrancar o ambiente local, o README e o guia de entrada valem mais do que qualquer diagrama. Se a equipa de frontend pergunta sempre o formato das respostas, comece pela documentação da API. Os agentes servem para trabalho aberto e continuado, os comandos para uma tarefa concreta e repetida, as skills para fixar formatos e regras de escrita.


## Documentação do projeto: README, guias e manutenção

O ponto de partida de qualquer repositório: explicar o que o projeto faz, como se arranca e como se contribui. Inclui também o trabalho menos visível de manter esses ficheiros vivos à medida que o código muda.

- **documentation-expert** (Agentes): Serve para quando existe código a mais e texto a menos: cria e melhora a documentação do projeto a partir do próprio código, aplicando normas de escrita técnica consistentes. [ficha](https://doutorai.pt/componentes/agents__documentation-expert)
- **documentation-generation-docs-architect** (Agentes): Pensado para bases de código herdadas. Analisa a arquitetura e os padrões de implementação já existentes e produz manuais técnicos longos, em vez de páginas soltas. [ficha](https://doutorai.pt/componentes/agents__wshobson-agents__agents-docs-architect)
- **update-docs** (Comandos): Um comando único para a passagem de sincronização, que atualiza o estado de implementação, as alterações de API e o conteúdo desalinhado depois de uma ronda de desenvolvimento. [ficha](https://doutorai.pt/componentes/commands__update-docs)
- **docs-maintenance** (Comandos): Útil quando a documentação já é grande demais para reler à mão, porque monta validação e atualizações automáticas para apanhar páginas que deixaram de bater certo. [ficha](https://doutorai.pt/componentes/commands__docs-maintenance)
- **crafting-effective-readmes** (Skills): Nem todos os READMEs servem o mesmo público. Esta skill dá modelos consoante o tipo de projeto e quem o vai ler, de biblioteca interna a projeto aberto. [ficha](https://doutorai.pt/componentes/skills__crafting-effective-readmes)
- **documentation-templates** (Skills): Para equipas que querem deixar de discutir estrutura. Reúne modelos de README, de documentação de API e de comentários de código, incluindo formatos pensados para leitura por IA. [ficha](https://doutorai.pt/componentes/skills__documentation-templates)

## APIs, contratos e referências

Documentação que outras pessoas leem para integrar com o seu sistema. Cobre especificações OpenAPI, listagens completas de parâmetros e a passagem de contexto entre backend e frontend.

- **api-documenter** (Agentes): Cobre o ciclo completo de uma API exposta a terceiros: escrita da especificação OpenAPI, portais de documentação interativos e exemplos de código prontos para quem integra. [ficha](https://doutorai.pt/componentes/agents__api-documenter)
- **generate-api-documentation** (Comandos): Quando a API já está estável e falta apenas a referência, gera a documentação em vários formatos de saída e trata da publicação automática. [ficha](https://doutorai.pt/componentes/commands__generate-api-documentation)
- **openapi-spec-generation** (Skills): Indicada para quem trabalha em design-first ou precisa de gerar SDKs, porque cria e mantém especificações OpenAPI 3.1 e verifica a conformidade do contrato. [ficha](https://doutorai.pt/componentes/skills__wshobson-agents__openapi-spec-generation)
- **backend-to-frontend-handoff-docs** (Skills): Resolve o momento em que o backend termina e o frontend fica à espera de saber o que existe, produzindo um documento de entrega focado em quem consome os endpoints. [ficha](https://doutorai.pt/componentes/skills__backend-to-frontend-handoff-docs)
- **reference-builder** (Agentes): Para os casos em que faltam as listagens completas. Produz referências exaustivas de parâmetros e guias de configuração, em vez de meia dúzia de exemplos ilustrativos. [ficha](https://doutorai.pt/componentes/agents__wshobson-agents__agents-reference-builder)

## Arquitetura, decisões e diagramas

Documentação para quem chega e pergunta porque é que o sistema está feito assim. Junta o desenho geral, as decisões registadas por escrito e as representações visuais.

- **create-architecture-documentation** (Comandos): Um arranque completo quando não existe nada escrito sobre o desenho do sistema, já que produz de uma vez os diagramas, os ADRs e uma visualização navegável. [ficha](https://doutorai.pt/componentes/commands__create-architecture-documentation)
- **adr-generator** (Agentes): Para fixar decisões antes de se perderem no histórico de conversas. Escreve Registos de Decisão de Arquitetura estruturados, com o contexto e as alternativas ponderadas. [ficha](https://doutorai.pt/componentes/agents__adr-generator)
- **c4-architecture** (Skills): Segue o modelo C4 e gera os níveis de contexto, contentor e componente em Mermaid, o que ajuda quando é preciso explicar o mesmo sistema a públicos com detalhe diferente. [ficha](https://doutorai.pt/componentes/skills__c4-architecture)
- **diagram-architect** (Agentes): Quando o diagrama tem de caber num formato específico, produz ASCII, Mermaid, PlantUML ou Draw.io, incluindo ERDs, máquinas de estados e grafos de dependências. [ficha](https://doutorai.pt/componentes/agents__diagram-architect)
- **mermaid-diagrams** (Skills): Referência de sintaxe para quem escreve os diagramas à mão dentro do Markdown, com cobertura de diagramas de classes, de sequência e de modelação de domínio. [ficha](https://doutorai.pt/componentes/skills__mermaid-diagrams)

## Histórico de alterações e entrada de novas pessoas

O que mudou desde a última versão e o que alguém precisa de saber no primeiro dia. São dois problemas com a mesma raiz: contexto que só existe na cabeça de quem já lá está.

- **changelog-generator** (Agentes): Trabalha a partir do histórico de git para produzir changelogs e notas de lançamento, e mantém a documentação de versões alinhada de versão para versão. [ficha](https://doutorai.pt/componentes/agents__changelog-generator)
- **add-changelog** (Comandos): Para quem só quer o ficheiro CHANGELOG.md em ordem. Gera e mantém as entradas no formato Keep a Changelog, sem inventar estrutura nova a cada versão. [ficha](https://doutorai.pt/componentes/commands__add-changelog)
- **Release Note Generator** (Comandos): Separa dois públicos que costumam ficar misturados: a partir dos commits recentes produz uma nota virada para o cliente e outra nota técnica para a equipa. [ficha](https://doutorai.pt/componentes/commands__centminmod-cc-setup__commands-create-release-note)
- **create-onboarding-guide** (Comandos): Gera o guia de entrada com preparação de ambiente, fluxos de trabalho e tutoriais, o que poupa repetir as mesmas explicações a cada pessoa que chega. [ficha](https://doutorai.pt/componentes/commands__create-onboarding-guide)
- **documentation-generation-tutorial-engineer** (Agentes): Transforma código existente em tutoriais passo a passo com exemplos práticos, útil quando a referência já está escrita mas ninguém percebe por onde começar. [ficha](https://doutorai.pt/componentes/agents__wshobson-agents__agents-tutorial-engineer)

## Como instalar estes componentes no seu projeto

Cada item da biblioteca técnica do Doutor AI é um ficheiro de texto. Os agentes ficam em .claude/agents/, os comandos em .claude/commands/ e as skills em .claude/skills/, dentro do repositório onde os quer usar. Se preferir tê-los disponíveis em todos os projetos, coloque-os na pasta equivalente dentro de ~/.claude/. Depois de gravar o ficheiro, reinicie a sessão do Claude Code para que o novo componente seja lido. Os agentes são escolhidos pela descrição, por isso basta pedir a tarefa por palavras; os comandos chamam-se pelo nome, precedido de barra; as skills carregam quando o pedido corresponde ao que a descrição indica. Instale dois ou três de cada vez, não vinte.

## Combinar os componentes num fluxo de trabalho

Estes componentes rendem mais encadeados do que isolados. Uma sequência que funciona bem num projeto já em curso: primeiro um agente que lê a base de código e produz o desenho geral, depois os ADRs para registar as decisões que só existem na memória da equipa e, no fim, o README e o guia de entrada, que assentam nessa base. A documentação de API segue outro ritmo, ligado ao ciclo de desenvolvimento: gere a especificação OpenAPI a partir do código e volte a gerá-la sempre que um endpoint mude. O changelog fecha o ciclo, porque nasce dos commits e serve de registo do que foi entregue em cada versão.

## O que estes componentes não resolvem

Nenhum destes componentes sabe aquilo que não está escrito em lado nenhum. Um agente lê o código, os commits e os ficheiros existentes; não sabe porque é que a equipa rejeitou a alternativa óbvia há dois anos, nem que aquele serviço vai ser desligado no trimestre seguinte. Esse contexto tem de vir de si. Há ainda um risco conhecido: documentação gerada em grande volume dá a sensação de trabalho feito e passa a ser aceite sem leitura. Reveja o que sai antes de gravar, sobretudo nos ADRs e na documentação de API, onde um detalhe errado leva outra pessoa a construir sobre uma premissa falsa.

## Perguntas frequentes

### Vale a pena gerar documentação automaticamente ou fica sempre genérica?

Depende do que pede. A documentação de referência, ou seja, listas de endpoints, parâmetros e opções de configuração, sai bem porque a informação já está no código. O texto que explica intenção e compromissos precisa de contexto que só a equipa tem. Na prática, gere a parte mecânica e escreva à mão as três ou quatro páginas que explicam decisões.

### Qual escolher entre um agente, um comando e uma skill?

O comando serve para uma tarefa fechada que se repete muitas vezes, como acrescentar uma entrada ao changelog. O agente serve para trabalho aberto, em que é preciso ler vários ficheiros e decidir a estrutura do que vai ser escrito. A skill não executa nada sozinha: define formatos, modelos e regras de escrita que o Claude Code aplica quando o assunto aparece.

### Como evito que a documentação volte a ficar desatualizada?

Ligue a atualização ao ritmo do código, em vez de a tratar como projeto à parte. Um comando de sincronização corrido no fim de cada bloco de trabalho, mais um componente de manutenção que valida periodicamente as páginas existentes, apanha a maior parte da deriva. O resto é decidir que ficheiros passam a ser obrigatórios numa revisão de código.

### Preciso mesmo de ADRs num projeto pequeno?

Se for a única pessoa a trabalhar no projeto e não pretender sair dele, provavelmente não. O valor de um ADR aparece quando entra alguém novo, ou quando volta ao código passado um ano e já não se lembra porque é que descartou a solução mais simples. Um ficheiro curto por decisão relevante costuma chegar.

### Estes componentes funcionam com qualquer linguagem ou stack?

A maior parte é independente da linguagem, porque trabalha sobre ficheiros de texto, histórico de git e estrutura de pastas. As exceções são as que assumem um formato concreto: as especificações OpenAPI pressupõem uma API HTTP, e os diagramas Mermaid precisam de um destino que os saiba renderizar, por exemplo o GitHub ou um site de documentação.


Fonte: https://doutorai.pt/para/documentacao-tecnica - Doutor AI, selecao feita a mao da biblioteca tecnica.