Chegamos à última parte da série. Já vimos o que é um design doc, como preencher cada seção e como ele vive ao longo do tempo. Falta a parte mais prática, que mostra com o que escrever, onde se aprofundar e como um agente de IA pode te dar o primeiro rascunho.
Ferramentas para escrever Link para o cabeçalho
- Confluence. Wiki corporativo da Atlassian para criar documentos com colaboração em equipe. Integra com Jira e Bitbucket.
- Google Docs. Online e gratuito, com edição colaborativa em tempo real e compartilhamento fácil.
- GitHub. Hospeda código e também documentos em Markdown, com edição colaborativa via Pull Requests.
Ferramentas para diagramas Link para o cabeçalho
- Mermaid. Diagramas de forma textual: sequência, casos de uso, C4 e mais.
- Sequence Diagram. Dedicada a diagramas de sequência, de forma textual e rápida.
- Structurizr. Diagramas como código: vários diagramas de arquitetura C4 a partir de um único modelo.
Os diagramas C4 e de sequência que aparecem na parte 2 foram feitos com ferramentas como essas.
Referências para se aprofundar Link para o cabeçalho
- Design Docs at Google (industrialempathy.com)
- Uma introdução aos Design Docs (Inside PicPay)
- How to Write an Effective Design Document (rinaarts.com)
- Design Docs (vídeo) (YouTube)
- RFCs and Design Docs (The Pragmatic Engineer)
Demo: gerando um rascunho com IA Link para o cabeçalho
A relação entre design docs e IA vai nos dois sentidos. Como me lembrou meu amigo Ithalo Alves, “um design doc pode ser muito útil para alimentar contexto de agentes de IA. Serve como especificação inicial e ajuda a guiar a implementação”. Ou seja, além de servir de entrada para guiar quem (ou o que) vai implementar, o próprio documento pode ser gerado com a ajuda de um agente.
É esse segundo caminho que a demo a seguir percorre. Para isso, criei a skill design-doc, que escreve ou revisa o documento junto com você. Ela trabalha por descoberta interativa. Em vez de já cuspir um texto pronto, te faz perguntas sobre o problema, as compensações, as alternativas e os times impactados, e só então escreve. A ideia é simples, o documento que sai dali é seu e as perguntas é que são dela. Por baixo, ela carrega as dicas que percorremos nesta série e o que fui aprendendo revisando esses documentos na prática. Instale a skill com o comando do GitHub CLI:
gh skill install cassiobotaro/skills design-doc --agent github-copilot
A flag --agent indica a ferramenta de destino: troque por claude-code, cursor, codex, entre outros. Quem usa o Claude Code também pode instalar pelo marketplace de plugins:
claude plugin marketplace add cassiobotaro/skills
claude plugin install design-doc@cassiobotaro-skills
Depois, basta acionar o agente com um prompt que traga o contexto e as restrições. Por exemplo:
Elabore um design doc para um novo pipeline de dados.
Contexto: hoje não existe pipeline de predição de churn. Precisamos processar eventos de comportamento do usuário (cliques, tempo de tela, compras) e prever a probabilidade de cancelamento em até 5 minutos após cada ação.
Restrições e requisitos:
- Objetivo: latência ponta a ponta ≤ 5 min; AUC-ROC do modelo ≥ 0,80 em 90 dias.
- Volume: cerca de 10 mil eventos por segundo via streaming.
- Processamento: camadas de limpeza, enriquecimento e feature store. Preferência por modelos interpretáveis (por exemplo, árvores).
- Armazenamento: arquitetura Medalhão (Bronze, Silver, Gold).
- Saída: banco NoSQL para a aplicação e Data Warehouse para análise.
- Fora de escopo: recomendações em tempo real e integração com CRM.
- Envolva: times de Segurança e Infraestrutura como revisores.
A partir daí, ela te devolve algumas perguntas antes de escrever. Responda o que souber, porque quanto mais contexto você der, melhor fica o rascunho. E o resultado traz exatamente o que percorremos nesta série: cabeçalho com autores, revisores e estado; objetivos mensuráveis e fora de escopo; alternativas consideradas com compensações; perguntas em aberto e plano de implantação.
Mas vale o lembrete que abriu a parte 1: o agente entrega um rascunho, não um documento final.
💡 Dicas:
- A IA acelera a escrita, organiza ideias e tira a página em branco da frente, mas não pensa por você.
- O valor de um design doc está nas decisões que você tomou, nas alternativas que descartou e nas compensações que assumiu. Isso vem do seu conhecimento do problema e do time.
- Copiar e colar sem questionar produz um documento com a aparência de um design doc, não um de verdade.
- Na revisão, quando alguém pergunta “por que não fizeram de outro jeito?”, a resposta precisa estar no documento porque você de fato raciocinou sobre ela, não porque saiu pronta do prompt.
Como diz Gergely Orosz, “não terceirize seu pensamento para a IA”. O rascunho é da máquina, o raciocínio é seu.
Fim da série Link para o cabeçalho
Essa foi a série sobre design docs. Espero que ela te ajude a transformar decisões técnicas em documentos claros, revisáveis e úteis muito tempo depois de o código ter subido.
Então é isso, pessoal!
Até a próxima!
{}’s