Repository navigation
Agente technical writer
Esta página descreve o agente technical-writer de forma didática. Se algum termo for novo, consulte o Glossário.
Este agente é o redator técnico (ou desenhista de documentação): a pessoa que escreve e mantém a documentação do produto. Documentação é o conjunto de textos que explica como o produto funciona e como usá-lo. O objetivo dele é simples: cada documento precisa ajudar o leitor a resolver a tarefa dele, com linguagem clara e sem informação desatualizada.
O Claude Code aciona este agente quando o pedido envolve escrever, organizar ou melhorar documentos. Exemplos de frases que costumam acionar o redator:
- "escreva um README para este projeto" (o README é o texto de apresentação que abre o repositório).
- "preciso de um tutorial de primeiros passos".
- "crie um guia de como fazer tal coisa".
- "documente esta interface de programação (API)".
- "escreva as notas de versão do lançamento".
- "esta documentação está confusa, pode reorganizar?".
- Separa a documentação em quatro tipos (um método chamado Diátaxis): tutorial (para aprender do zero), guia prático (para resolver um objetivo específico), referência (para consultar um detalhe exato) e explicação (para entender o porquê). Misturar tipos deixa o texto ruim, então ele mantém cada documento com um propósito só.
- Escreve para um público definido. Antes de escrever, ele decide se o leitor é iniciante, intermediário ou avançado, e adapta o tom.
- Usa linguagem simples: frases curtas, voz ativa e nenhum jargão sem explicar. Jargão é o vocabulário técnico que só quem é da área entende.
- Trata documentação como código (a prática chamada docs como código): os textos ficam em arquivos no repositório, passam por revisão e são publicados de forma controlada.
- Gera a referência técnica a partir do próprio código sempre que possível, para que a documentação não fique diferente do que o programa realmente faz.
- Cria diagramas como código. Um diagrama é um desenho que explica um fluxo; feito como código, ele pode ser versionado e refeito facilmente.
- Escreve notas de versão para gente. Notas de versão são o resumo do que mudou em cada lançamento, agrupado por tema e escrito para quem usa, não uma lista crua de alterações técnicas.
- Cuida do ciclo de vida do texto: registra quem é o responsável, a data da última revisão e mantém os links internos funcionando, para que nada fique esquecido ou quebrado.
Cor azul (operacional). Família: Suporte, Docs, Legal e Idiomas. Ele executa o trabalho de escrever e manter a documentação, em parceria com o gerente de produto (para as notas de versão) e o arquiteto de software (para registros de decisão técnica).
-
ORG: governança e quem decide o que. -
CONTRACT: a autoridade do projeto sobre o código; a documentação nunca pode contradizer este manual.
Você diz: "este projeto não tem documentação, preciso de um ponto de partida". O agente entrega uma estrutura de documentação organizada nos quatro tipos, escreve um README com um início rápido (instalar e rodar em poucos minutos), um tutorial de primeiros passos e a base para a referência, tudo em linguagem clara e com o responsável e a data de revisão registrados.
Veja também Caetano (CTO), que coordena a área técnica, e os colegas de família support-engineer, compliance-legal, internal-auditor e i18n-l10n-specialist. Voltar para a Home.