Templates & Exemplos Práticos

Coleção de templates copiáveis para operacionalizar os pilares e as fases do roadmap. Cada seção traz: quando usar, o template pronto pra copiar e um exemplo preenchido.

Adapte, não idolatre. Estes modelos são pontos de partida deliberadamente enxutos — comece com o mínimo e só adicione campos quando a falta deles doer.

Índice

1. ADR — Architecture Decision Record
2. Registro de Dívida Técnica
3. Registro de Incidente + Postmortem blameless
4. Matriz de Priorização (Impacto × Risco × Esforço)
5. Checklists operacionais
6. Plano de Estabilização
7. Regra de Negócio (catálogo)
8. Runbook de Suporte / FAQ

1. ADR — Architecture Decision Record

Quando usar: toda vez que tomar uma decisão técnica relevante e difícil de reverter (banco de dados, framework, padrão de arquitetura, adotar/remover um serviço). Sustenta o Pilar 5 — Conhecimento Distribuído e o Pilar 6 — Arquitetura Manutenível. Registra o porquê, que o código sozinho não conta.

Onde guardar: uma pasta docs/adr/ no próprio repositório, arquivos numerados (0001-titulo.md). Nunca se edita um ADR antigo — se a decisão muda, cria-se um novo que supersede o anterior.

Template:

# ADR-000X: <título curto da decisão>

- **Data:** AAAA-MM-DD
- **Status:** Proposto | Aceito | Substituído por ADR-00YY | Descontinuado
- **Decisores:** <quem participou>

## Contexto
<Qual problema ou força motriz levou a essa decisão? Restrições relevantes
(prazo, time, orçamento, tecnologia atual). Fatos, não opiniões.>

## Opções consideradas
1. <Opção A> — prós / contras
2. <Opção B> — prós / contras
3. <Opção C> — prós / contras

## Decisão
<O que foi decidido e, principalmente, POR QUÊ. Qual opção venceu e o motivo.>

## Consequências
- **Positivas:** <o que ganhamos>
- **Negativas / trade-offs:** <o que aceitamos perder / a dívida que assumimos>
- **Riscos e mitigação:** <o que pode dar errado e o plano B>

Exemplo preenchido:

# ADR-0007: Manter monólito modular em vez de migrar para microsserviços

- **Data:** 2026-08-06
- **Status:** Aceito
- **Decisores:** CTO, tech lead, dev sênior de backend

## Contexto
Time de 4 devs. Produto único, ~30k usuários. Surgiu a proposta de quebrar o
sistema em microsserviços "para escalar". Não temos hoje equipe de infra
dedicada nem observabilidade distribuída madura.

## Opções consideradas
1. Migrar para microsserviços agora — prós: escalabilidade independente;
   contras: complexidade operacional alta, precisa de DevOps que não temos,
   desacelera entregas por meses.
2. Manter monólito, mas modularizá-lo internamente (fronteiras claras entre
   domínios) — prós: baixo custo operacional, fácil de manter com time pequeno;
   contras: escala como bloco único (aceitável no nosso volume).
3. Híbrido: extrair só 1 serviço muito específico — contras: custo de rede e
   observabilidade sem ganho real no nosso estágio.

## Decisão
Opção 2. No nosso porte, um monólito bem modularizado é mais fácil de manter e
não paga o custo operacional dos microsserviços. Reavaliar quando tivermos
gargalos de escala reais e/ou equipe de infra.

## Consequências
- **Positivas:** entregas seguem rápidas, custo de operação baixo, onboarding simples.
- **Trade-offs:** não escalamos componentes de forma independente (ok no volume atual).
- **Riscos e mitigação:** se um domínio virar gargalo, as fronteiras internas
  já facilitam extraí-lo depois. Gatilho de revisão: latência sustentada acima
  do SLO por 2 sprints.

2. Registro de Dívida Técnica

Quando usar: sempre que assumir um atalho consciente ou identificar um ponto frágil. Torna a dívida visível — a base do Pilar 3. Cada item recebe um score de priorização (ver seção 4).

Template de item:

### DT-00X: <título do item de dívida>
- **Onde:** <arquivo/módulo/área afetada>
- **O quê:** <descrição do problema ou atalho>
- **Dor atual:** <o que isso custa hoje — lentidão, bugs, medo de mexer>
- **Frequência de contato:** Alta | Média | Baixa (com que frequência o time toca aqui)
- **Impacto (1-5):** _  · **Risco (1-5):** _  · **Esforço (1-5):** _
- **Score:** (Impacto × Risco) ÷ Esforço = _
- **Criado em:** AAAA-MM-DD

Exemplo de backlog de dívida (ordenado por score):

Leitura: DT-03 ganha mesmo com esforço médio, porque impacto e risco são máximos. DT-04 quase nunca justifica esforço dedicado — resolve-se de passagem (regra do escoteiro).

3. Registro de Incidente + Postmortem blameless

Dois níveis: um registro rápido para capturar o incidente na hora (útil já na Fase 1), e um postmortem completo para incidentes relevantes.

Blameless = sem culpa. O foco é o sistema que permitiu o erro, nunca a pessoa. Isso é o que faz as pessoas relatarem em vez de esconder. Pergunte "por que foi fácil errar?", não "quem errou?".

3a. Registro rápido de incidente (na hora):

### INC-00X — <título>
- **Início:** AAAA-MM-DD HH:MM   · **Fim:** HH:MM   · **Duração:** __min
- **Severidade:** SEV1 (crítico) | SEV2 (grave) | SEV3 (menor)
- **Impacto:** <o que o usuário sentiu / quantos afetados>
- **Detectado por:** alerta | cliente | dev
- **Ação imediata:** <o que fez para estancar>
- **Status:** Resolvido | Mitigado | Em investigação

3b. Postmortem blameless (depois, para SEV1/SEV2):

# Postmortem — INC-00X: <título>

- **Data do incidente:** AAAA-MM-DD · **Autor:** <nome> · **Severidade:** SEVx
- **Duração:** __ · **MTTR:** __ (tempo até recuperação)

## Resumo
<2-3 frases: o que aconteceu e o impacto no negócio/usuário.>

## Linha do tempo
- HH:MM — <evento / detecção / ação> (horários em fuso único)
- HH:MM — ...
- HH:MM — recuperação confirmada

## Causa raiz
<A causa técnica de fundo. Use "5 porquês" se ajudar. Foco no sistema:
por que foi possível/fácil isso acontecer e não ser pego antes?>

## O que funcionou / o que não funcionou
- ✅ <o que ajudou a detectar/resolver rápido>
- ❌ <o que atrasou ou piorou>

## Ações de acompanhamento (com dono e prazo)
| Ação | Tipo | Dono | Prazo |
|------|------|------|-------|
| <corrigir causa raiz> | Corretiva | @fulano | AAAA-MM-DD |
| <adicionar alerta que teria pego> | Preventiva | @beltrano | AAAA-MM-DD |

Exemplo (resumo + causa raiz preenchidos):

## Resumo
Em 05/08, o checkout ficou indisponível por 38min após um deploy. ~400 usuários
receberam erro 500 ao finalizar compra. Receita estimada perdida: ~R$ 3k.

## Causa raiz
Uma migração de banco rodou fora de ordem em produção porque o passo era manual
e dependia de o dev lembrar de executá-lo. Não houve má conduta individual:
o processo permitia um deploy "meio pronto" sem checagem automática.

## Ações de acompanhamento
| Ação | Tipo | Dono | Prazo |
|------|------|------|-------|
| Migrações automáticas no pipeline de deploy | Preventiva | @ana | 2026-08-13 |
| Alerta de taxa de 5xx acima de 2% | Preventiva | @rui | 2026-08-11 |
| Health check de checkout pós-deploy | Preventiva | @ana | 2026-08-15 |

4. Matriz de Priorização (Impacto × Risco × Esforço)

Quando usar: para decidir, de forma consciente, entre itens concorrentes — inclusive manutenção vs. feature nova (o dilema central do Pilar 7). Substitui o "quem grita mais alto" por um critério transparente.

Escala (1 a 5 em cada eixo):

Fórmula do score:

Score = (Impacto × Risco) ÷ Esforço

Quanto maior, mais prioritário. Multiplicar impacto por risco faz itens que são valiosos E perigosos de adiar subirem; dividir por esforço favorece ganhos rápidos.

Exemplo trabalhado — manutenção vs. feature, disputando o mesmo tempo do time:

A lição do exemplo: a feature de relatórios tem o maior impacto isolado (5), mas perde para duas tarefas de manutenção — porque o risco de adiá-las é alto. É exatamente esse raciocínio que protege o espaço da preventiva contra o "quem grita mais alto". O botão "urgente", apesar da pressão, é objetivamente o menos prioritário.

Regra de bolso: reserve ~20% da capacidade do ciclo para itens de manutenção antes de aplicar a matriz ao resto. A matriz decide o quê dentro de cada balde; os 20% garantem que o balde de manutenção nunca fique vazio.

5. Checklists operacionais

5a. Code Review (Pilar 2)

Cole no template de Pull Request do repositório.

## Checklist de Review
- [ ] O código faz o que o PR diz (e nada além do escopo)
- [ ] Nomes claros; funções pequenas (<~50 linhas); sem aninhamento profundo
- [ ] Erros tratados explicitamente (nada de erro engolido em silêncio)
- [ ] Entradas validadas nas fronteiras (não confia em dado externo)
- [ ] Sem segredos hardcoded (chaves, senhas, tokens)
- [ ] Sem logs de debug / código comentado esquecido
- [ ] Testes cobrindo o caminho feliz + principais casos de erro
- [ ] CI verde (build + testes + lint)
- [ ] Entendi o suficiente para dar manutenção nisso depois

5b. Atualização de Dependências (Pilar 4)

## Rotina de atualização (mensal ou por sprint)
- [ ] Rodar o scanner de vulnerabilidades (o que está crítico/alto?)
- [ ] Priorizar patches de segurança sobre atualizações de feature
- [ ] Atualizar de forma incremental (1 major por vez, não tudo junto)
- [ ] CI + testes verdes após cada atualização
- [ ] Testar manualmente os fluxos críticos afetados
- [ ] Ler o changelog em busca de breaking changes antes de mergear
- [ ] Registrar como dívida (seção 2) o que não deu pra atualizar agora

5c. Deploy Readiness (Pilares 1 e 2)

## Antes de dar deploy
- [ ] CI verde (build + testes + lint)
- [ ] Migrações de banco automatizadas no pipeline (não manuais)
- [ ] Plano de rollback conhecido e testável (reversível com 1 ação)
- [ ] Alertas e monitoramento ativos para pegar regressões
- [ ] Feature flag / rollout gradual quando a mudança for arriscada

## Depois do deploy
- [ ] Health check dos fluxos críticos passou
- [ ] Taxa de erro e latência dentro do normal (olhar o dashboard)
- [ ] Ninguém precisou executar passo manual "de cabeça"

6. Plano de Estabilização

Quando usar: quando a demanda urgente supera a normal e você precisa sair do Modo Crise. Formaliza o esforço de estabilização — o que congela, quanta capacidade é protegida, o que será atacado e como saber que acabou. Dá ao time foco e ao board previsibilidade.

Template:

# Plano de Estabilização — <período>

- **Motivo:** <por que estamos estabilizando: sintomas, % tempo em corretiva>
- **Timebox:** <ex: 2 semanas, de AAAA-MM-DD a AAAA-MM-DD>
- **Dono:** <quem lidera> · **Board avisado em:** AAAA-MM-DD

## O que CONGELA (durante o timebox)
- <features / pedidos não-críticos suspensos>

## O que CONTINUA
- Urgências SEV1/SEV2 (via "bombeiro do dia" rotativo)
- <trabalho de estabilização abaixo>

## Capacidade
- **Bombeiro do dia:** <quem/rotação> — absorve as urgências
- **Time blindado:** <N pessoas / __% da capacidade> focadas na estabilização

## Alvos (causas-raiz recorrentes, por prioridade)
| # | Problema recorrente | Impacto | Risco | Esforço | Score |
|---|---------------------|:-------:|:-----:|:-------:|:-----:|
| 1 | <...> | _ | _ | _ | _ |
| 2 | <...> | _ | _ | _ | _ |

## Critérios de saída
- [ ] <ex: incidentes recorrentes X e Y eliminados na causa-raiz>
- [ ] <ex: tempo em corretiva abaixo de __%>
- [ ] <ex: time voltou a cumprir o planejado por 1 sprint>

## Comunicação
- **Antes:** <mensagem do trade-off ao board>
- **Durante:** <cadência de update, ex: resumo diário/semanal>
- **Depois:** <retrospectiva + retorno ao roadmap normal>

Exemplo (resumo preenchido):

# Plano de Estabilização — Sprint 2026-08

- **Motivo:** ~65% do tempo do time em corretiva nas últimas 3 semanas; checkout
  e login geraram 8 incidentes SEV2. Trabalho planejado parado.
- **Timebox:** 2 semanas (11 a 22/08)
- **Dono:** CTO · **Board avisado em:** 2026-08-08

## O que CONGELA
- Nova tela de relatórios; ajustes de UI não-críticos.

## Capacidade
- **Bombeiro do dia:** rotação Ana → Rui → Ana (1 pessoa/dia)
- **Time blindado:** 3 devs (~75%) focados nos alvos abaixo

## Alvos
| # | Problema recorrente | Impacto | Risco | Esforço | Score |
|---|---------------------|:-------:|:-----:|:-------:|:-----:|
| 1 | Migração manual quebra deploy | 5 | 5 | 3 | 8.3 |
| 2 | Timeout intermitente no checkout | 5 | 4 | 3 | 6.7 |

## Critérios de saída
- [ ] Deploys com migração 100% automatizados
- [ ] Zero SEV2 de checkout por 1 semana
- [ ] Tempo em corretiva abaixo de 30%

7. Regra de Negócio (catálogo)

Quando usar: ao recuperar uma regra de negócio que estava presa no código ou na cabeça de alguém (ver Conhecimento Preso). Cada regra vira uma entrada permanente do catálogo — a "fonte da verdade" do sistema, em linguagem que o suporte e o negócio entendem.

Template:

### RN-00X: <nome curto da regra>
- **Área:** <domínio / módulo — ex: Pagamentos, Cadastro>
- **Regra (linguagem clara):** <o que o sistema faz, sem jargão de código>
- **Condições/exceções:** <quando se aplica; casos especiais>
- **Onde vive no código:** <arquivo/função — para achar de novo>
- **Exemplo concreto:** <entrada → resultado esperado>
- **Descoberta via:** código | comportamento | logs/banco | entrevista | ticket
- **Última verificação:** AAAA-MM-DD

Exemplo preenchido:

### RN-014: Frete grátis acima do valor mínimo
- **Área:** Checkout / Frete
- **Regra (linguagem clara):** Pedidos com subtotal igual ou acima de R$ 199,00
  têm frete zerado para a região Sudeste.
- **Condições/exceções:** Só Sudeste. Não vale para itens marcados como "entrega
  especial", que sempre cobram frete mesmo acima de R$ 199.
- **Onde vive no código:** services/frete.py → calcula_frete(), linha do if de subtotal
- **Exemplo concreto:** carrinho R$ 210 em SP → frete R$ 0; com 1 item "entrega
  especial" → frete cobrado normalmente.
- **Descoberta via:** código + confirmação por ticket #4821
- **Última verificação:** 2026-08-06

8. Runbook de Suporte / FAQ

Quando usar: para capturar a resolução de uma dúvida ou problema recorrente do suporte — a "regra de ouro" da documentação sob demanda. Toda escalação ao dev deve virar um destes, para não se repetir.

Template:

### FAQ-00X: <sintoma ou pergunta, como o cliente descreve>
- **Nível que resolve:** N1 | N2 | N3
- **Diagnóstico rápido:** <como confirmar que é este caso>
- **Solução (passo a passo):**
  1. <passo>
  2. <passo>
- **Quando escalar:** <condição> → **para quem:** <N2 / dev responsável>
- **O que enviar ao escalar:** <contexto/dados já coletados>
- **Regras relacionadas:** <RN-00X, se houver>

Exemplo preenchido:

### FAQ-023: "Meu pedido sumiu do histórico"
- **Nível que resolve:** N1
- **Diagnóstico rápido:** confirmar se o pedido tem mais de 90 dias.
- **Solução (passo a passo):**
  1. Pedidos acima de 90 dias saem da listagem padrão (regra RN-031).
  2. Orientar o cliente a usar o filtro "Todos os períodos".
  3. Se ainda não aparecer, aí sim seguir para escalação.
- **Quando escalar:** pedido < 90 dias que não aparece nem com o filtro →
  **para quem:** N2.
- **O que enviar ao escalar:** número do pedido, e-mail da conta, print do filtro aplicado.
- **Regras relacionadas:** RN-031 (retenção de 90 dias no histórico).

➡️ Estes templates operacionalizam os 7 pilares. Para saber quando introduzir cada um, veja o roadmap-maturidade.md; para medir o efeito, o metricas.md; para sair de uma sobrecarga, o modo-crise.md; para libertar conhecimento preso, o conhecimento-preso.md.