Skip to content

Instantly share code, notes, and snippets.

@gbzarelli
Created October 3, 2025 17:06
Show Gist options
  • Select an option

  • Save gbzarelli/261aa979f8b58b2bc2a97c7209181183 to your computer and use it in GitHub Desktop.

Select an option

Save gbzarelli/261aa979f8b58b2bc2a97c7209181183 to your computer and use it in GitHub Desktop.
Design Doc Template - Documento que registra, de forma clara e detalhada, o planejamento e a arquitetura de uma solução técnica. #helpdev-blog

Template Design Doc

Status: EM CONSTRUÇÃO


Objetivos

Descreva de forma clara os objetivos que desejamos alcançar com a solução proposta.
Exemplo: "Automatizar o fluxo de aprovação de pagamentos, reduzindo o tempo médio em 30%".


Fora do Escopo

Liste todos os itens que não fazem parte do escopo da solução proposta. Exemplo: Integração com sistemas legados antigos que não estão no roadmap.


System Design

Solução Atual

Detalhe a solução atual, utilizando diagramas e exemplos para representar o funcionamento.
Recomenda-se usar ferramentas como Draw.io para diagramas.

Solução Proposta

Detalhe claramente as mudanças esperadas na solução proposta, preferindo diagramas atualizados.


Arquitetura

Apresente um desenho de arquitetura seguindo o modelo C4.
Dica: inclua diagramas que representem desde visão mais macro (Context) até Container, Component e Code.


Novos Recursos / Componentes

Nome do Componente Descrição Tecnologia Cluster/K8s ou Recurso Cloud
componente-x Função principal do recurso linguagem/framework usado cluster-prod-apps

Fluxos e Diagramas

Detalhe cada fluxo em etapas separadas (Heading 4).
Inclua diagramas de sequência, BPMN ou fluxos de estado.


Payloads e Integrações

Liste e descreva todos os payloads e contratos envolvidos na solução.
Inclua estrutura JSON ou XML de cada integração.


Alternativas Consideradas

Documente alternativas avaliadas que foram descartadas e explique o motivo.


Critérios de Segurança

Descreva aspectos de segurança, práticas aplicadas, e conformidades com PCI ou LGPD.


Times Envolvidos

Squad / Time Função Responsáveis
Squad Pagamentos Desenvolvimento da solução Nome 1, Nome 2

Preocupações Gerais

Apresente riscos e preocupações mapeados.
Exemplo: "Dependência de API externa com SLA não garantido".


Plano de Implementação

Se o deploy precisar ocorrer em etapas, descreva as fases:

  1. Deploy em ambiente de homologação
  2. Testes automatizados
  3. Deploy em produção gradual
  4. Monitoramento pós-deploy

Referências Externas

  • Tarefas do Jira
  • Documentação do projeto
  • Diagramas no Draw.io

Documento de Upstream

  • Escrito por: [nome do autor]
  • Revisores:
    Revisor Atuação Aceite
    Nome 1 Arquiteto de soluções Aceite

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment