Governance

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Governança é o conjunto de decisões sobre como o projeto é entendido e percorrido, o que vai além de como o código é escrito. A meta é uma só: qualquer pessoa que chega, do não técnico ao especialista, consegue achar o que precisa, entender o que encontrou e contribuir com contexto.

Código serve o time. A melhor solução é aquela que o próximo dev consegue ler, manter e evoluir com confiança. Uma solução elegante que ninguém entende tem valor limitado, porque toda mudança nela passa a depender de quem a escreveu.

Governança cobre o ciclo completo. Cada decisão técnica produz efeitos depois do commit: na manutenção, no onboarding, na capacidade de o time crescer. Pensar em governança é antecipar esses efeitos enquanto a mudança ainda é simples de fazer.

Complexidade organizada em camadas. Todo sistema tem uma complexidade própria, que não some. O trabalho é apresentá-la em camadas: o não técnico precisa entender o que o sistema faz, e o especialista precisa entender por que cada decisão foi tomada.

Consistência ajuda a aprender. Padrões previsíveis exigem menos esforço de leitura. Um dev que aprende como um módulo funciona já sabe se achar nos outros, porque a forma se repete.

Foco no processo. Quando algo falha, a investigação vai para o processo que deixou a falha passar. Culpar quem executou deixa o processo intacto, e a falha volta com outra pessoa no lugar.

O SDLC (Software Development Life Cycle · Ciclo de Vida de Desenvolvimento de Software) começa antes do primeiro commit e termina depois do último deploy. Design, implementação, testes, entrega, operação e manutenção: cada uma dessas fases sofre o efeito das decisões tomadas hoje.

O staff engineer raciocina sobre o sistema inteiro. A pergunta que guia o trabalho deixa de ser "como implementar isso?" e passa a ser "como isso afeta o time que vai manter, o dev que chega mês que vem e o produto que vai crescer?".

Na prática, são perguntas que antecedem cada decisão:

Responder a essas quatro perguntas dentro de uma tarefa comum já é fazer governança.

O landing é o primeiro contato com o projeto, e ele define a impressão inicial. Quem abre o repositório encontra um caminho claro para o que precisa, ou desiste e vai perguntar para alguém.

Um bom landing é hierárquico, do geral para o específico, do conceito para a implementação.

README                → o que é, como rodar, onde encontrar o quê
docs/shared/          → princípios agnósticos de linguagem e plataforma
docs/<linguagem>/     → convenções específicas da stack
quick-reference.md    → consulta rápida para devs já integrados

O README é a porta de entrada. Alguém que nunca viu o projeto precisa conseguir três coisas em menos de 5 minutos: entender o que o projeto faz, rodar localmente e saber onde procurar o resto. Se qualquer uma delas exigir perguntar para um colega, o README está incompleto.

O onboarding eficiente transfere conhecimento estrutural. Um dev que entende como um módulo está organizado entende também os outros, porque todos seguem o mesmo padrão. É a consistência do projeto que permite ensinar uma vez e valer para o repositório inteiro.

A complexidade do sistema existe e não vai sumir. A governança decide como apresentá-la, na medida que cada leitor precisa.

A documentação em camadas serve esse propósito:

A governança está funcionando quando cada uma dessas audiências abre o projeto e encontra o seu nível.

Um nome expressivo comunica a intenção sem exigir documentação em volta. Ele leva alguns segundos de reflexão na hora de escrever e poupa leitura toda vez que alguém passa por ali.

Um nome ruim dá trabalho de novo a cada leitura. Cada dev que encontra data, helper ou utils precisa abrir o arquivo e rastrear de onde a variável veio para saber o que ela guarda. Esse rastreio se repete com cada pessoa.

Um vocabulário consistente ajuda ainda mais. Quando a base inteira usa fetch para leitura, save para escrita e calculate para derivação, o leitor já sabe o que esperar de uma função que nunca viu.

Padrões previsíveis deixam o leitor concentrado no domínio, em vez de decifrar o estilo de cada arquivo.

O efeito prático aparece no onboarding: quem entende a estrutura de um módulo entende todos os outros, e o aprendizado de uma área do sistema se transfere para as demais. O time cresce sem que o treinamento cresça junto.

A inconsistência produz o efeito oposto. Cada módulo com o seu jeito próprio obriga a um reaprendizado por área, e o conhecimento de quem já está no time deixa de transferir para quem chega.

Os ADRs (Architecture Decision Records · Registros de Decisão de Arquitetura) guardam o raciocínio que levou à escolha. O código mostra o que foi feito; o ADR guarda o motivo, as alternativas que estavam na mesa e o que se abriu mão ao escolher.

Decisão sem registro vira conhecimento que só existe na cabeça de quem estava presente. Quando essas pessoas saem, o motivo sai junto. Quem chega depois questiona a decisão, refaz a mesma análise e às vezes reverte uma escolha que tinha um motivo legítimo e invisível.

Três elementos tornam um ADR útil:

Existe um conjunto de normas públicas que já resolveu problemas comuns de vocabulário, segurança, versionamento e troca de dados entre sistemas. Adotar essas normas encurta discussão de preferência pessoal. Uma auditoria externa também reconhece a norma sem precisar aprender a convenção da casa.

O agrupamento por domínio ajuda a localizar a norma certa no contexto certo.

Linguagem normativa e datas

Protocolos HTTP (HyperText Transfer Protocol · Protocolo de Transferência de Hipertexto) e autenticação

Qualidade e segurança

Versionamento e entrega

A norma serve de ponto de referência. Um projeto pode divergir dela quando existe motivo concreto, e o desvio vale tanto quanto a conformidade desde que registrado em um ADR. O problema aparece quando a divergência acontece por inércia, sem decisão documentada: quem chega depois fica sem saber se aquilo foi uma escolha deliberada ou um acidente que ninguém corrigiu.

Uma revisão que procura apenas bugs deixa passar a pergunta principal: este código se encaixa no sistema que já existe?

Perguntas que orientam uma revisão com pensamento de governança:

Aprovar sem olhar essas perguntas devolve o PR ao autor em minutos, e o problema volta para o time meses depois, quando alguém precisa mexer naquele código.

Um processo auditável permite conferir a qualidade em qualquer ponto do ciclo sem depender da memória de quem estava presente.

Cada etapa tem entrada, saída e um critério de verificação. Com isso em ordem, qualquer pessoa (dev, tech lead, alguém do negócio) olha um ponto isolado ou o ciclo inteiro e enxerga o estado real do projeto.

Spec → Implementation → Review → CI → Deploy → Observability

A ordem e etapas podem variar conforme o tipo de projeto, escopo e divisão de equipes. O importante é ter clareza sobre cada etapa e garantir que todas sejam executadas.

No dia de uma falha em produção, cada etapa responde com o seu registro: qual decisão originou o problema, em qual review ele passou, qual teste não cobriu o caso, qual deploy o introduziu. O time reconstrói o que aconteceu a partir desses registros.

Com o processo alinhado, um checklist curto por etapa funciona como controle de qualidade. Cada um é leve, específico e aplicado no momento em que a etapa acontece.

O propósito é pegar o desvio antes que ele se espalhe. O item esquecido na Spec vira retrabalho na Review, e o item esquecido na Review vira bug em produção.

O checklist cobre o óbvio que se esquece sob pressão. O julgamento sobre o que o código deveria fazer continua com quem revisa.

O sinal aparece quando pessoas de contextos diferentes conseguem trabalhar no projeto com confiança.

O não técnico entende o que o sistema faz e como está organizado. O dev novo contribui em dias, sem precisar pedir contexto. O dev experiente localiza o que precisa sem perguntar. O especialista encontra o raciocínio que levou a cada decisão.

Se qualquer um deles abre o projeto e consegue seguir sozinho, a governança está fazendo o trabalho dela.

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.