Jazztinn/dontreadme

Construtor de README para Hackathon

Um README de hackathon tem um trabalho que um README de projeto normal não tem: ele precisa vencer. Juízes examinam dezenas de repositórios em minutos, muitas vezes em um telefone, decidindo o que vale a pena abrir. O README é a primeira impressão do projeto e frequentemente o único artefato que um juiz lê antes de pontuar. Portanto, o objetivo não é "documentar o código" — é fazer um juiz ocupado e cético entender e acreditar no projeto rapidamente, e tornar cada afirmação trivialmente verificável.

Esta habilidade produz um README rico no estilo de submissão, não um esparso. O estilo de referência está em references/readme-template.md — leia-o antes de escrever, pois ele codifica o estilo da casa (linhas de badges centralizados, badges-botão de demonstração, tabelas, etapas fundamentadas, uma árvore de projeto, um bloco explícito de Destaques para Julgamento). references/badges.md tem trechos prontos de shields.io.

Siga as etapas abaixo em ordem, mas mantenha-se conversacional — você está ajudando um construtor cansado a cruzar a linha de chegada, não preenchendo um formulário.

Etapa 1 — Ancorar nos critérios de julgamento (faça isso primeiro)

Esta é a ação de maior alavancagem que você pode fazer, e é por isso que esta habilidade existe. A maioria dos READMEs é escrita para um template genérico; um vencedor é escrito para a rúbrica. Antes de qualquer outra coisa, pergunte:

"Você tem os critérios de julgamento ou a rúbrica do evento à mão? (ex.: 'inovação, dificuldade técnica, impacto, polimento', ou uma folha de pontuação / prompt da página de submissão.) Cole se sim — garantirei que cada um seja visivelmente abordado. Se não, usarei um padrão forte."

Por que perguntar primeiro: se a rúbrica pondera "impacto no mundo real", comece com um problema vívido e quem ele ajuda; se pondera "dificuldade técnica", coloque a arquitetura e as partes difíceis no início. Você adicionará depois uma seção de Destaques para Julgamento perto do final que nomeia cada critério e aponta como o projeto o atende — isso é a ancoragem na rúbrica tornada visível, e os juízes adoram porque faz o trabalho deles por eles. Mantenha uma lista de verificação: todo critério precisa de um lar no README.

Se eles não tiverem uma rúbrica, use como padrão os quatro critérios que quase todo evento usa alguma versão: inovação/originalidade, execução técnica, impacto/utilidade e polimento/completeza.

Avalie também o sabor do evento, pois isso muda quais seções opcionais pertencem (veja Etapa 4):

• Acadêmico / pesquisa / techsprint (ex.: eventos ACM): geralmente recompensa uma divulgação de uso de IA, uma nota de ética/proteção de dados, referências/citações, e às vezes alinhamento com ODS da ONU. Inclua estes.
• Produto / startup / hackathon geral de fim de semana: mantenha enxuto — pule ODS, ética e citações a menos que o projeto envolva genuinamente coleta de dados ou alegações que precisem de suporte.

Quando não tiver certeza, pergunte, ou inclua o conjunto mais leve e mencione que os outros estão disponíveis.

Etapa 2 — Escaneie o repositório para fundamentar-se em fatos

Juízes perdem confiança instantaneamente quando um README descreve um projeto que não corresponde ao código, ou quando as etapas de configuração não funcionam. Portanto, antes de escrever, veja o que está realmente lá. O estilo da casa referencia caminhos de arquivo reais e mostra comandos reais com saída esperada — você só pode fazer isso lendo o repositório.

• Stack e linguagem: deduza a partir de manifestos — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile. Anote frameworks (React, Next, Vite, FastAPI, Flask, Three.js…). Eles mapeiam diretamente para a linha de badges e a tabela de stack técnico.
• Como executar: leia scripts em package.json, um Makefile, docker-compose.yml, Procfile, .env.example. A seção de execução deve corresponder à forma como o projeto realmente inicia, incluindo variáveis de ambiente e a porta de desenvolvimento real. Onde puder inferir a saída esperada, mostre-a — isso sinaliza que a coisa funciona.
• Estrutura e pontos de entrada: examine diretórios de alto nível e o arquivo de entrada principal para que a árvore do projeto e as etapas de "Como funciona" citem arquivos reais (src/lib/check.js, app/main.py), como os exemplos fazem.
• O que já existe: um README parcial, LICENÇA, capturas de tela em assets//docs//public/, uma URL implantada na configuração, workflows de CI. Reutilize.

Se você não tiver acesso ao repositório (o usuário apenas descreve o projeto), pule o escan, confie na entrevista e diga isso — sinalize que os comandos de configuração e caminhos de arquivo são placeholders a verificar, em vez de inventar exatos.

Etapa 3 — Entreviste para o que o código não pode dizer

O repositório dá fatos; o construtor dá a história e a prova. Peça por estes em um lote amigável e deixe claro que eles podem pular qualquer coisa:

• Pitch de uma linha → torna-se o blockquote do slogan.
• Problema / inspiração → concreto, humano, idealmente um momento específico.
• Demonstração ao vivo + vídeo → o ativo mais clicado. Coloque ambos perto do topo como badges-botão. Se não houver vídeo, note gentilmente que um de 2 minutos ajuda muito.
• Capturas de tela / GIF / mascote ou logotipo → mesmo uma imagem eleva o polimento percebido; os exemplos centralizam uma imagem de mascote/pré-visualização no topo.
• A parte difícil → o que foi tecnicamente complicado ou do que eles se orgulham; ouro para pontuação de execução técnica e para "Como funciona".
• Resultados / métricas de destaque → se o projeto mediu algo, uma pequena tabela de resultados é muito persuasiva.
• Equipe → nomes + funções (e links) para a tabela da equipe.
• O que vem a seguir → roteiro/escala mostra visão.
• Extras do evento (apenas se relevante por Etapa 1) → ferramentas de IA usadas, dados/detalhes de consentimento, citações.

Não bloqueie por respostas. Se eles estiverem sem tempo, rascunhe com placeholders claramente marcados como <!-- TODO: adicionar link de demonstração --> para que nada importante seja silenciosamente omitido — nunca invente uma URL de demonstração, uma métrica ou um colega de equipe.

Etapa 4 — Escreva o README

Produza um único README.md na raiz do projeto (ou onde o usuário quiser), seguindo references/readme-template.md. O esqueleto ordenado completo está nesse arquivo; aqui está a forma e quais partes são essenciais vs. opcionais.

Essencial (quase sempre incluir):

1. Título + logotipo/mascote centralizado opcional
2. Linha de badges técnicos centralizada (de references/badges.md)
3. Linha do evento/submissão + blockquote do slogan
4. Demonstração + vídeo como badges-botão (e links de dataset/Colab se existirem)
5. Tabela da equipe
6. Problema (ou "Por que isso importa")
7. Solução / O que faz
8. Como funciona — etapas numeradas citando arquivos reais
9. Tabela de stack técnico
10. Executar localmente — comandos verificados, com saída esperada quando possível
11. Árvore de estrutura do projeto
12. Roteiro / O que vem a seguir
13. Destaques para Julgamento — um tópico por critério, mapeando o projeto a ele
14. Licença

Opcional (incluir com base no sabor do evento e no que é real):

• Uma barra de navegação com links de âncora abaixo do herói (3–6 seções principais) — transforma uma rolagem longa em um toque para um juiz examinando em um telefone.
• Tabela de resultados / métricas de destaque + tabelas de erro/análise (projetos de dados); link para os dados brutos ou um comando de reprodução para que os números sejam reexecutáveis.
• Uma tabela antes/depois 50/50 quando o projeto melhora um status quo (mais rápido, mais barato, menos etapas) — torna a vitória visual em vez de apenas afirmada.
• Uma caixa de estatísticas ASCII abaixo do herói para um projeto com um número matador.
• > [!IMPORTANT] / > [!NOTE] chamadas de alerta do GitHub para destacar a única ressalva ou fato chave que um juiz examinando não pode perder (usar com moderação).
• Diagrama de pipeline Mermaid (sistemas de múltiplos estágios)
• Fluxo de demonstração / passo a passo "o que funciona offline"
• Divulgação de uso de IA (eventos acadêmicos)
• Proteção de dados / privacidade / ética (projetos envolvendo pessoas ou dados)
• Alinhamento com ODS da ONU (eventos acadêmicos orientados a impacto)
• Referências e citações, agradecimentos
• Lista de verificação de status atual + afazeres de polimento pré-julgamento

Adapte a ênfase e a ordenação à rúbrica da Etapa 1: os critérios que mais importam devem aparecer mais altos. Não encha — cada seção deve merecer seu lugar. Um hack de produto enxuto pode usar apenas o conjunto essencial; um techsprint de pesquisa pode usar a maioria do conjunto opcional. Corresponda ao projeto, não a uma lista de verificação.

Notas de estilo que importam para o julgamento:

• Lidere com a coisa mais forte — inovação, engenharia ou impacto, qualquer que seja o gancho.
• Mostre, não conte — um badge-botão de demonstração, um GIF, uma configuração de um comando e um bloco de saída esperada superam adjetivos. Toda afirmação impressionante deve ser verificável. Uma tabela antes/depois, uma caixa de estatísticas ou um benchmark reproduzível transforma uma afirmação em prova que o juiz pode ver ou reexecutar.
• Faça o herói trabalhar — título centralizado, logotipo/mascote opcional, linha de badges e um slogan afiado devem permitir que um juiz entenda o que é e por que é bom antes de rolar. Coloque os botões de demonstração/vídeo aqui, onde o primeiro clique cai.
• Fundamente tudo no repositório — caminhos de arquivo reais, comandos reais, a porta de desenvolvimento real. É isso que torna o README confiável e é a linha condutora do estilo de exemplo.
• Seja honesto — não afirme funcionalidades que não existem; juízes testam coisas, e uma afirmação quebrada custa mais do que uma funcionalidade ausente. Marque trabalho inacabado sob "o que vem a seguir" ou uma lista de verificação de status, não como concluído.
• Mantenha escaneável — parágrafos curtos, cabeçalhos significativos, tabelas em vez de muros de prosa, legível de cima para baixo em um telefone em dois minutos.

Etapa 5 — Feche o loop contra a rúbrica

Antes de entregar, pegue cada critério da Etapa 1 e confirme que a seção de Destaques para Julgamento (e o corpo) o aborda; se algum critério não tiver um lar, adicione-o. Em seguida, diga ao usuário o que você fez — ex.: "Sua rúbrica ponderou impacto e dificuldade técnica; liderei com o problema para impacto e adicionei uma nota 'por que isso foi difícil' em Como funciona, e o bloco de Destaques para Julgamento nomeia todos os quatro." Finalmente, liste quaisquer placeholders restantes (link de demonstração, capturas de tela, métricas) para que eles saibam exatamente o que preencher antes de enviar.