Golden paths

Golden path é o caminho recomendado e suportado para fazer algo comum: subir um serviço novo, expor uma API, criar um job agendado. Ele não proíbe alternativas — é apenas tão mais fácil que quase ninguém quer sair dele.

A diferença entre caminho pavimentado e muro decide o resultado. Muro é política sem suporte: “é proibido usar outra coisa”, sem que o caminho oficial funcione bem. As pessoas contornam, e você perde padronização e visibilidade ao mesmo tempo.

O que entra num golden path

Um caminho pavimentado de serviço web, para valer, entrega de uma vez:

• Repositório criado, com estrutura, dono e CODEOWNERS.
• Pipeline completo: build, teste, verificação de segurança, imagem assinada.
• Deploy em todos os ambientes, com rollback pronto.
• Observabilidade ligada: métricas, logs estruturados, tracing, painel padrão e alerta de SLO básico.
• Segurança: identidade do workload, segredos pelo cofre, políticas de admissão.
• Ambiente efêmero por pull request.
• Documentação do serviço no catálogo, e um runbook inicial.

O critério de aceite é objetivo: do zero a “hello world” em produção, com observabilidade e alerta, em menos de um dia — sem nenhum ticket para outro time.

Templates de serviço

O ponto de entrada é um template que gera o esqueleto:

# a interface pode ser CLI, portal ou um repositório template — o que o time já usa
plataforma criar servico \
  --nome pedidos \
  --linguagem go \
  --tipo api-http \
  --time loja \
  --centro-de-custo CC-4821

Duas decisões de projeto separam o template que envelhece bem do que vira dívida:

• Gerar pouco e referenciar muito. O que é comum (pipeline, manifests, políticas) fica em módulos e workflows reutilizáveis, versionados. O template só instancia. Assim, uma melhoria chega a todos os serviços com um bump de versão, em vez de exigir cinquenta pull requests.
• Nada de scaffolding descartável. Se o código gerado é copiado e nunca mais recebe atualização, você criou cinquenta variantes divergentes em um ano — exatamente o problema que queria resolver.

# no serviço gerado: o pipeline é uma chamada, não uma cópia
jobs:
  entrega:
    uses: empresa/plataforma-workflows/.github/workflows/servico-http.yml@v3
    with: { nome: pedidos, linguagem: go }

Permita sair do caminho

Casos legítimos existem: uma linguagem que a plataforma não cobre, um requisito de latência, uma integração exótica. Torne a saída possível e visível:

• Registre o desvio no catálogo, com motivo e dono.
• Deixe claro o que o time assume ao sair (observabilidade, plantão, conformidade).
• Revise periodicamente: desvio recorrente é sinal de que o caminho precisa crescer, não de que o time é rebelde.

Guardrails continuam valendo fora do caminho — política de admissão, exigência de imagem assinada, criptografia. O que muda é a conveniência, não a segurança.

Medindo adoção

Se ninguém adota, o problema é do caminho. Meça:

• Percentual de serviços no caminho pavimentado (e a tendência).
• Tempo até o primeiro deploy de um serviço novo.
• Versão do template em uso: muitos serviços em versões antigas indicam migração difícil.
• Tickets manuais que o caminho deveria ter eliminado.
• Satisfação de quem usou, coletada logo depois do uso.

Adoção baixa tem sempre uma causa investigável: o caminho não cobre um caso comum, é lento, é difícil de depurar quando falha, ou ninguém sabe que ele existe. Descubra qual antes de propor obrigatoriedade.

Manutenção é parte do trabalho

Golden path é código com consumidores — vale a mesma disciplina de módulo compartilhado: versionamento semântico, changelog, teste automatizado do caminho inteiro (um serviço de exemplo que sobe a cada mudança da plataforma) e migração assistida quando houver quebra.

Um caminho pavimentado que quebra o deploy de outro time destrói mais confiança do que dez melhorias constroem.

Próximo passo: para catalogar esses serviços e expor os templates, veja Backstage e catálogos de serviço.