Julgar um README
Visão Geral
Um README é a porta de entrada de um repositório. A maioria dos READMEs falha porque documentam a superfície (como é a API) em vez do modelo mental (o que o sistema é, como se comporta, onde quebra). Esta skill avalia um README em 8 eixos e traz à tona a melhor heurística única para o veredito geral.
Use esta rubrica para produzir uma revisão por escrito. Para cada seção: mencione o que funciona, o que está faltando e o que corrigir. Seja específico — cite linhas, aponte cabeçalhos, nomeie o bug.
Como usar
- Leia o README do início ao fim uma vez sem julgar — a primeira impressão é importante.
- Percorra as 8 seções abaixo em ordem. Cada seção tem perguntas; responda a cada uma com evidências do README.
- Aplique a melhor heurística única no final como uma verificação de integridade do seu veredito.
- Verifique os anti-padrões listados — são deduções automáticas.
- Produza uma lista de correções: o que corrigir, em ordem de prioridade.
A Rubrica
1. Teste dos primeiros 30 segundos
Se um estranho consegue se orientar antes de rolar a página.
- O que é isso? Uma frase, acima da dobra, que um estranho possa entender.
- Para quem é? O leitor consegue decidir se o projeto é relevante para ele no primeiro parágrafo.
- Funciona? Evidência de vida — status de CI, contagem de downloads semanais, data do último lançamento, badges de versão, "testado em X". Um número de downloads ativo é um sinal mais forte que uma data de lançamento; um badge de CI verde é mais forte que qualquer um deles. Ninguém confia em um repositório abandonado.
2. Consigo instalar em menos de 5 minutos?
Se um leitor que colar cada bloco de código em ordem termina com algo funcional.
- Pré-requisitos são explícitos — versões de runtime, dependências pares, serviços externos.
- Instalação é um bloco copiável. Sem "veja nosso site de documentação para instalação."
- Quick Start é executado do início ao fim. Sem lacunas, sem "configure X" sem mostrar como.
- Exemplos usam nomes consistentes.
mainKnowledgePoolna configuração e'main'na busca é o erro nº1 de README — ele silenciosamente quebra todos os usuários que copiam e colam.
3. Corresponde à realidade?
Se o README foi mantido junto com o código.
- Todo exemplo de código compila. Assinaturas de tipo desatualizadas e exports renomeados são piores que nenhum exemplo.
- Desvio de versão é reconhecido. Se um vídeo/post de blog/seção está desatualizado, diga isso no lugar, em vez de deixar os leitores descobrirem isso da pior forma.
- Respostas de erro e casos de contorno estão documentados, não apenas o caminho feliz — leitores confiam em documentação que admite o que quebra.
4. É navegável?
Se alguém voltando pela terceira vez consegue encontrar o que precisa rapidamente.
- Índice para qualquer coisa com mais de ~300 linhas.
- Profundidade da seção é significativa. h4 dentro de h3 dentro de h2 deve refletir contenção real, não apenas "acabaram os
##". Subseções órfãs são um sinal de que o documento cresceu sem ser reestruturado. - Referências cruzadas são links, não prosa. "Veja acima" envelhece mal;
[Filtragem de Metadados](#filtragem-de-metadados-onde)sobrevive a edições. - Informação duplicada é perigosa. Se o mesmo endpoint está documentado duas vezes, uma cópia vai apodrecer. Escolha um lar canônico.
5. Ensina o modelo mental, não apenas a API?
Se o leitor sai com intuição, não apenas sintaxe.
- Por que, não apenas como. "Execuções em massa nunca são enfileiradas automaticamente — devem ser acionadas manualmente" me diz mais que um monte de assinaturas.
- Ciclos de vida e invariantes são declarados. "Apenas uma execução em massa por pool por vez", "a exclusão não pode ser desabilitada", "o id correlaciona X com Y" — essas são as coisas que os usuários descobrem dolorosamente se não forem escritas.
- Modos de falha são nomeados. Uma seção de Solução de Problemas é um proxy para "o mantenedor realmente suportou isso em produção".
Exceção de site de documentação. Se o projeto tem um site de referência canônico linkado acima da dobra (ex:
zod.dev/api,nextjs.org/docs), avalie esta seção com base em "o README ensina o suficiente para o leitor saber se deve mergulhar no site de documentação e o que procurar quando chegar lá?" — não "ele ensina o modelo mental completo?". Duplicar a referência completa no README violaria a regra da Seção 4 de "informação duplicada é perigosa". O trabalho do README nesse caso é a ponte, não a enciclopédia.
6. Divulgação progressiva
Se cada público pode parar de ler na seção que precisa.
- Quick Start te deixa funcional. Referência te tira do sufoco. Exemplos mostram uso idiomático.
- Funcionalidades avançadas não bloqueiam iniciantes. API em massa, callbacks de provedores, adaptadores personalizados — tudo adiado após o caminho mínimo para uma busca funcional.
- Tabelas de configuração com colunas obrigatório/opcional permitem que as pessoas escaneiem em vez de ler.
7. Sinais de manutenção
Se o projeto parece ativo e utilizável dentro de uma empresa.
- Changelog linkado. Sem changelog = sem sinal de que o projeto é mantido.
- Licença declarada. Licença ausente = inutilizável na maioria das empresas.
- Caminho de contribuição visível. Mesmo uma linha ("abra uma issue primeiro") é melhor que nada.
- Tom corresponde à maturidade. Um projeto alfa não deveria parecer que está na versão 3; um projeto estável não deveria parecer um pitch de hackathon.
8. Honesto sobre limitações
Se o mantenedor respeita o tempo do leitor.
- Paridade de adaptadores, suporte de plataforma, lacunas conhecidas são expostas, não escondidas em uma issue do GitHub.
- Um leitor que encontra uma limitação no README se sente informado; o mesmo leitor encontrando-a após 2 horas de depuração se sente enganado.
A melhor heurística única
Aplique duas heurísticas, adaptadas ao público do README:
Contrato do usuário: Um novo usuário pode abrir o README frio e entregar uma integração pequena e correta sem ler o código fonte? Obrigatório para todo README.
Contrato do contribuidor: Um novo contribuidor pode abrir o README frio e, sem falar com o mantenedor, entregar um PR pequeno e correto? Obrigatório se o README é o ponto de entrada do contribuidor. Opcional se um
CONTRIBUTING.mdestá linkado a partir do README — nesse caso, avalie a experiência do contribuidor em relação a esse arquivo, não ao README.
O contrato do contribuidor exige que o README (ou CONTRIBUTING.md) explique a arquitetura, não apenas a superfície. A maioria dos projetos falha neste teste, e geralmente é a diferença entre um projeto que recebe contribuições espontâneas e um que não recebe.
Se o contrato do usuário falhar, isso substitui o polimento superficial das seções 1 a 7. Se apenas o contrato do contribuidor falhar e não houver CONTRIBUTING.md linkado, isso ainda é um defeito real — sinalize-o, mas não deixe que substitua os pontos fortes voltados ao usuário.
Anti-padrões (deduções automáticas)
Marque-os explicitamente quando encontrados — eles sinalizam problemas maiores.
| Anti-padrão | Por que é ruim |
|---|---|
| Texto de marketing onde deveria haver documentação de referência | Leitores precisam de fatos, não de discurso de vendas |
| Capturas de tela de código em vez de blocos de código | Não copiável, não pesquisável, não acessível |
| "Veja o código fonte" como documentação | Transfere o trabalho do mantenedor para cada leitor |
| Listas de funcionalidades com emojis que não correspondem a cabeçalhos de seção | Decoração sem valor de navegação |
| Badges sem propósito — mais de ~6, ou qualquer badge que não corresponda a um sinal distinto (CI, licença, downloads, versão, cobertura, canal de suporte) | Sinal de qualidade por imitação cultural; 5 badges com propósito estão bem, 10 decorativos não |
| Um "Roadmap" que é na verdade uma lista de desejos sem sinal de prioridade ou cronograma | Cria expectativas que o projeto não pode cumprir |
| Vídeos/postagens de blog linkados sem um aviso "gravado contra a versão X" | Leitores perdem tempo com conteúdo desatualizado |
Texto placeholder enviado aos leitores (seu-repositorio, TODO, lorem ipsum, links de âncora quebrados) | O maior destruidor de confiança acima da dobra — sinaliza que ninguém revisou antes de publicar |
Camada invertida — helpers obrigatórios (ex: embedQuery) definidos após o Quick Start que os usa | Copiar e colar o "caminho mínimo" produz ReferenceError; o bloco de exemplo não é realmente autocontido |
| Quick Start que termina na configuração sem um trecho "verifique se funciona" | O leitor não tem como confirmar que a instalação fez algo; a documentação cobre a ingestão, mas não a recuperação |
Formato de saída
Ao avaliar um README, produza:
- Veredito — uma linha. (ex: "Forte na instalação, fraco no modelo mental. Um novo usuário entrega em 10 min; um novo contribuidor não consegue.")
- Descobertas seção por seção — para cada um dos 8 eixos, o que funciona e o que está faltando, com referências de linha/cabeçalho.
- Anti-padrões encontrados — liste qualquer um da tabela acima.
- Resposta da melhor heurística — sim/não para ambos o contrato do usuário e o contrato do contribuidor, com raciocínio. Se
CONTRIBUTING.mdestá linkado, observe que o teste do contribuidor está escopo para esse arquivo. - Lista de correções — correções em ordem de prioridade (maior impacto primeiro).