Template de PR em 9 OSS: 3 renderizam zero

Antes de escrever mais um post do tipo “seu PR template está grande demais”, eu resolvi fazer o passo que quase ninguém faz: abrir o arquivo bruto de nove templates de PR de OSS grandes e contar item por item. Nada de screenshot, nada de “no meu time a gente usa isso”. Só .github/pull_request_template.md na default branch de cada repo, no dia 22 de setembro de 2026.

O que saiu foi mais estranho do que eu esperava. Três dos nove templates rendem zero itens visíveis quando você abre o formulário de PR: Next.js, VS Code e Node.js. O motivo é o mesmo nos três — tudo está dentro de um único , então o GitHub renderiza um textarea em branco. Kubernetes também tem zero checkbox, mas mantém sete títulos visíveis. Rails ficou com quatro checkboxes. Angular, no topo, tem quatorze.

Este texto é a leitura desse levantamento, cruzado com o princípio do capítulo 8 do meu livro Revisão de Código com Harness Engineering: “com mais de dez itens, ninguém marca tudo. O alvo é cinco a sete.” Vamos ver o quanto o mundo real segue o próprio conselho.

Templates de PR em 9 OSS grandes: checkboxes visíveis por repositório, medido em 22-09-2026

A regra de contagem (para você poder refazer)

Antes dos números, a regra. Uma dúvida que aparece toda vez que alguém tenta “auditar templates de PR” é o que conta como item. Eu fixei um critério simples e apliquei igual nos nove:

Baixar o arquivo cru: curl https://raw.githubusercontent.com/<owner>/<repo>/<default-branch>/.github/pull_request_template.md.
Descartar tudo entre  (inclusive multi-linha). É o que o GitHub esconde ao renderizar.
No que sobra, contar linhas que começam com - [ ] ou * [ ] (com ou sem x) como checkbox interativo.
Contar linhas #, ##, ###, #### como título visível.
Contar ``` como fence de bloco de código.

Se você quiser refazer, o script inteiro em Python cabe em vinte linhas. Deixei ele em gist no repo do livro. O ponto de fixar a regra por escrito é que o Next.js do post anterior “tinha oito checkboxes” e não tinha nenhum — a versão anterior deste texto contou os - dentro do comentário como se fossem visíveis, e todo o restante da análise ficou tortada. Sem regra escrita, o próprio autor conta errado.

Os nove templates, medidos

Repositório	Branch	Checkboxes visíveis	Títulos visíveis	Blocos de código
vercel/next.js	canary	0	0	0
microsoft/vscode	main	0	0	0
nodejs/node	main	0	0	0
kubernetes/kubernetes	master	0	7	2
rails/rails	main	4	4	0
electron/electron	main	7	3	0
Homebrew/brew	main	8	0	0
django/django	main	11	4	0
angular/angular	main	14	6	0

Mediana de checkboxes entre todos os nove: 4, no rails/rails. Média entre os visíveis (excluindo os quatro zeros): 8,8, puxada pelo Angular. Desvio nítido entre os dois grupos, “zero” e “acima de sete”, com muito pouco no meio.

Por que três templates rendem zero

O caso do Next.js é o mais didático. O arquivo tem quarenta e cinco linhas de conteúdo útil — checklist para bug, para feature, para docs, uma seção “For Maintainers” com What/Why/How. Tudo bem organizado. Só que a primeira linha do arquivo é . Um  no fim, tudo no meio vira comentário HTML. O GitHub renderiza um formulário de PR em branco.

Não é acidente. A intenção provável é oferecer guia sem obrigação: o autor do PR lê o comentário no editor de texto quando está apagando, e escreve o corpo do PR à mão. É um tipo de checklist “só olhado”, nunca marcado. VS Code segue a mesma ideia com um bloco de instruções mais curto. Node.js é semelhante, com um bloco maior que inclui o “Developer’s Certificate of Origin”.

Kubernetes é um caso híbrido interessante: nada de checkboxes, mas mantém sete títulos visíveis (What type of PR / What this PR does / Which issue / Special notes / Does this PR introduce a user-facing change / Additional documentation / AI usage disclosure) e dois blocos de código com ```release-note e ```docs. A ideia ali é forçar prosa estruturada mais bots com labels do tipo /kind bug, não um checklist.

Já Angular, Django e Homebrew jogam do outro lado do espectro: quatorze, onze e oito checkboxes visíveis. Angular chega a expor um seletor manual do tipo do PR (“Bugfix / Feature / Code style / Refactoring / Build / CI / …”) com nove opções em checkboxes soltos. Alguém já contou quantos desses ficam marcados na prática. O número não é bonito, mas ninguém publica.

O princípio do capítulo 8, contra a régua

O capítulo 8 do meu livro monta um template de PR “prático” com três princípios:

Encurte. Com mais de dez itens, ninguém marca tudo. O alvo é cinco a sete.
Seja concreto. “Conferi a qualidade” é abstrato demais; “os portões automáticos (lint / type check / test) estão todos passando” é o mesmo item, mas verificável.
Tire do checklist o que dá para automatizar. Se o CI já bloqueia PR sem teste passando, não gasta linha de checklist com “Todos os testes passam”.

Cruzando com o que eu medi:

Rails, com 4 checkboxes visíveis, é o mais próximo do alvo. Cada checkbox é concreto (“Tests are added or updated if you fix a bug”, “CHANGELOG files are updated for the changed libraries”) e nenhum duplica um portão que o CI já resolve.
Electron (7) e Homebrew (8) ficam dentro da faixa “alta mas defensável”. Homebrew inclui um item de IA disclosure recente, o que é uma escolha de política, não excesso.
Django (11) e Angular (14) violam o princípio 1. O caso Angular é o mais claro — nove checkboxes só para “qual tipo de mudança” caberiam em um select no corpo, ou em um label.
Kubernetes e os três “zero” violam o princípio 2 pelo lado oposto. Prosa livre é ótima para maintainer sênior, mas o iniciante que abre PR pela primeira vez não tem a régua que separa “o que este projeto quer que eu diga” de “o que eu acho que devo dizer”. Título vazio delega essa régua para o revisor humano na hora da leitura, que é justamente o custo que o template existe para reduzir.

Nenhum dos nove templates aplica com rigor todos os três princípios. O mais próximo é o Rails; o mais distante do capítulo 8 é o Angular.

O que não dá para inferir daqui

Vale antecipar duas objeções antes que elas surjam no comentário do post.

“Mas Next.js, VS Code e Node.js merecem template zero — eles são maduros o suficiente.” Talvez. Mas a distinção importante é que o template zero não é uma escolha explícita. Ele é o efeito colateral de embrulhar tudo em . Um template deliberadamente vazio seria um arquivo com uma linha (“descreva a mudança e o motivo”). O que existe hoje nesses três repos é um arquivo grande com instruções que ninguém vê a menos que abra o editor. Isso é diferente.

“Contar checkbox visível não mede se o template funciona.” Concordo. Um checkbox visível pode virar hábito de check-and-forget; um template zero pode funcionar num time onde todo mundo já sabe o que escrever. O que a contagem entrega é o ponto de partida do PR: o que o autor vê ao abrir o formulário. Comparar essa superfície entre repos que operam em escalas parecidas (dezenas de PRs por dia) tem valor porque o custo cognitivo do autor é o gargalo que o template existe para reduzir, e a superfície visível é a parte que o autor paga primeiro.

Se você quiser medir “funciona ou não”, precisaria coletar dados de conformidade — quantos PRs de fato preenchem cada campo. Eu fiz isso com uma regra do meu AGENTS.md em Escrevi ‘testes antes do PR’ no AGENTS.md por 3 meses. Só 12% seguiram: a resposta foi que regra sem portão não vira comportamento, seja em AGENTS.md, seja em checkbox de template. O template é a superfície de entrada. Quem obriga a preencher é a camada de portão, não a lista.

Como calibrar o template do seu time

A leitura prática que eu tiro da medição é curta.

Se o seu template hoje tem mais de dez itens, você provavelmente está no grupo Django/Angular. Vale reduzir. O corte mais fácil é remover o que o CI já verifica: “Testes passam”, “Lint passa”, “Build passa” saem porque o pull_request workflow no .github/workflows/ já bloqueia PR que quebra qualquer um dos três. Ganho: cada item que sai libera atenção para os itens que sobram (efeito de saliência clássico — reduzir a lista faz o revisor de fato ler o que restou).

Se o seu template hoje tem entre cinco e sete itens, você já está na faixa que o livro sugere. O trabalho vira qualidade de cada item: verifique que cada checkbox é acionável, que nenhum é duplicata de portão automático, e que nenhum é “abstrato demais” no sentido do princípio 2.

Se o seu template hoje envolve tudo em  ou está vazio, considere se essa é escolha explícita ou herança. Se for herança, deixar assim delega o padrão do PR para o autor, e o autor varia — o que empurra o custo para a revisão. Um arquivo com uma única linha visível (“Descreva o que mudou e por quê. Linke a issue com Fixes #.”) já reduz variância sem virar checklist.

O que eu não recomendo é copiar o template do Angular porque “é do Google”. A auditoria mostra que o Angular está no extremo distante do princípio 1. Copiar por prestígio antes de medir é o viés que empurra o template do seu time para a categoria “grande demais para ser marcado”. O template certo é o menor que cobre o que o CI não cobre.

O template do capítulo 8, como referência

Para fechar, deixo o template que o livro propõe. Ele fica com cinco checkboxes fixos na “Auto-checagem” mais o bloco “Tipo de mudança” (que é uma lista curta, não um checklist a marcar). Está exatamente na faixa cinco-a-sete quando você conta os checkboxes que de fato têm um estado a marcar.

<!-- .github/pull_request_template.md -->

## Resumo
<!-- O que mudou. Em 1 a 3 frases. -->

## Razão da mudança
<!-- Por que mudou. Linke a issue, se houver. -->
Closes #

## Tipo de mudança
- [ ] Nova funcionalidade
- [ ] Correção de bug
- [ ] Refatoração (sem mudança funcional)
- [ ] Adição de testes
- [ ] Documentação
- [ ] Atualização de dependências

## Como revisar
<!-- Se o PR é grande, por qual arquivo começar a leitura para entender melhor -->

## Screenshots (se houver mudança de UI)
<!-- Antes / Depois -->

## Auto-checagem
- [ ] Os portões automáticos (lint / type check / test) estão todos passando
- [ ] Adicionei ou atualizei os testes
- [ ] Está alinhado com a "Code Direction" do AGENTS.md
- [ ] Separei refatoração de nova funcionalidade (se estiverem misturados, explique aqui)
- [ ] Até 300 linhas (se passar, explique a razão da divisão)

Note o que não está aqui: nenhum “Todos os testes passam”. Esse item saiu porque o CI cobre. Nenhum “Fiz revisão do meu código”. Item abstrato, sai. Nenhum “Segui o guia de contribuição”. Se você não seguiu, marcar mesmo assim é o comportamento esperado.

Referências

Templates medidos em 22-09-2026:
Capítulo 8 do livro Revisão de Código com Harness Engineering: “Automatizando o template de PR e o checklist de revisão” — Kindle Brasil (BRL 24,99).
Versão japonesa da série no Zenn: zenn.dev/kenimo49/books/harness-code-review.

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews