README que vende

O que README que vende faz?

Um README não é documentação. É uma landing page que por acaso vive em um repositório git. Um visitante decide em cerca de 15 segundos se vai dar estrela, testar ou sair. Tudo acima da dobra deve conquistar a estrela. A documentação vai abaixo da dobra ou em docs/.

O teste dos 15 segundos

Antes de escrever qualquer coisa, responda a estas perguntas em uma linha cada. Se você não conseguir, o README também não conseguirá.

1. O que é? Uma frase, sem adjetivos. "Um navegador headless para agentes de IA, escrito em Zig."
2. Por que existe? A dor que remove, nas palavras do usuário. "O Chrome consome 500 MB por aba; agentes precisam de 50 abas."
3. Prova de que funciona. Um GIF de demonstração, um número de benchmark, ou um antes/depois. Não uma lista de funcionalidades.
4. Como eu testo em um comando? npx ..., pip install ..., curl ... | sh, docker run ....

Estrutura (nesta ordem, sem exceções)

# nome-do-projeto
Frase de impacto em uma linha. (o que + para quem + o diferencial)

[GIF de demo ou captura de tela — menos de 10 segundos, mostra o resultado, não a configuração]

## Instalação           ← um comando, copiável e colável, sem pré-requisitos ocultos
## Porquê               ← 3–5 linhas: a dor, as alternativas existentes, porque isso é diferente
## Uso                  ← o caso mais comum único, como um exemplo executável
## Funcionalidades      ← opcional, curto, lista com marcadores, sem adjetivos de marketing
## Como funciona        ← opcional, um parágrafo ou um diagrama
## Comparação           ← opcional, tabela vs 2–3 alternativas, honesto sobre as desvantagens
## Contribuição / Licença

Regras

• Frase de impacto: ≤ 15 palavras. Nomeie a categoria e o diferencial. Evite "incrivelmente rápido", "poderoso", "simples mas". Se tiver um número, use o número: "Reduz o uso de tokens do Claude Code em 40%."
• Demo primeiro, palavras depois. O GIF ou captura de tela vai imediatamente abaixo da frase de impacto. Se não houver demo ainda, crie uma antes de lançar (veja a skill demo-gif). Um README sem demo converte uma fração do que um com demo converte.
• Instalação é um bloco, um comando. Se precisar de chave de API ou arquivo de configuração, mostre também, no mesmo bloco. Pré-requisitos ocultos são o motivo #1 pelo qual as pessoas desistem após clonar.
• "Porquê" é escrito para alguém que já tem uma solução. Nomeie as alternativas. Diga o que elas fazem bem. Depois diga a única coisa que este projeto faz que elas não fazem. Leitores confiam em READMEs que são justos com os concorrentes.
• Sem emoji em títulos a menos que o projeto seja deliberadamente lúdico. Sem badges acima da frase de impacto (uma parede de badges é a primeira coisa que os visitantes ignoram). Dois ou três badges abaixo da frase de impacto são aceitáveis: status da build, versão, licença.
• Um exemplo real vale mais que dez marcadores de funcionalidades. Mostre entrada → saída. Faça algo que o leitor realmente executaria.
• Diga o que não é. Uma linha de escopo honesto ("Não substitui o Playwright; ainda sem renderização JS") antecipa o primeiro comentário hostil no Hacker News.
• Link para a prova social que você tem. "Usado por X", um benchmark, um tópico Show HN. Não invente nenhum.
• Mantenha as 60 linhas superiores livres de qualquer coisa que um visitante de primeira viagem não precise. Arquitetura, roadmap, FAQ, changelog: tudo abaixo ou em outro lugar.

Anti-padrões que matam conversão

• Começar com um parágrafo de contexto ou histórico.
• Uma tabela de conteúdos como a primeira coisa na página.
• "Funcionalidades" antes de "Instalação".
• Instruções de instalação que começam com "Primeiro, clone o repositório" para uma ferramenta feita para ser usada, não desenvolvida.
• Capturas de tela de arquivos de configuração em vez de resultados.
• Tom de marketing ("revolucionário", "de última geração", "sem esforço").
• Placeholders mortos ("TODO: adicionar demo").

Procedimento

1. Leia o README atual (se houver) e os pontos de entrada do código. Extraia as quatro respostas do teste dos 15 segundos.
2. Esboce a frase de impacto. Escreva três variantes; escolha a que tiver o substantivo mais concreto e menos adjetivos.
3. Escreva Instalação, depois Uso, depois Porquê. Execute cada comando da Instalação para confirmar que funciona a partir de um diretório limpo.
4. Insira a demo abaixo da frase de impacto. Se não existir nenhuma, adicione um marcador TODO(demo) e avise ao usuário que isso bloqueia o lançamento.
5. Corte tudo acima da dobra que não responda à pergunta "um estranho precisa disso para decidir?".
6. Leia as 60 linhas superiores como um engenheiro cético. Corrija a primeira coisa que faria com que fechassem a aba.

Saída

Retorne o README.md completo. Em seguida, liste, em ≤ 5 marcadores, o que você alterou e o que o usuário ainda precisa fornecer (GIF de demo, números de benchmark, citações reais de usuários).