README writer
Um README tem um trabalho: levar um visitante de "o que é isso?" a executar o primeiro comando em menos de um minuto, e depois mostrar como ir além e como ajudar.
Quando usar
- Escrevendo um README para um projeto novo, ou reescrevendo um muito resumido ou confuso
- Revisando um README antes de um lançamento ou de uma versão 1.0
- O usuário diz que o projeto tem visitas, mas não recebe estrelas, instalações ou contribuidores
Quando não usar
- Documentação de referência de API (gere-a a partir do código; crie links a partir do README)
- Tutoriais longos ou documentação de arquitetura: coloque-os em
docs/e crie links
Fluxo de trabalho
-
Colete fatos antes de escrever. Leia o manifesto (
pyproject.toml,package.json,composer.json,Cargo.toml...), a saída--helpda CLI ou o ponto de entrada principal, a documentação existente e a licença. Encontre o comando de instalação real e um exemplo real. Nunca invente flags, saídas, benchmarks ou funcionalidades. -
Pergunte ao usuário apenas o que o código não pode dizer: para quem é o projeto, o único problema que ele resolve e por que é melhor que a alternativa óbvia. Se não estiverem disponíveis, escreva um pitch neutro a partir do código e marque-o para revisão.
-
Faça lint do README atual (se houver).
scripts/é relativo a esta skill:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
Escreva usando a estrutura em structure.md, começando a partir do template. A ordem importa: título + badges, pitch, (imagem de demonstração), início rápido, funcionalidades, uso/exemplos, configuração, FAQ, roadmap, contribuição, licença.
-
Aplique as regras de escrita:
- Pitch: uma frase, com menos de 200 caracteres, sem palavras de hype. Padrão:
"
<nome>é um(a)<categoria>que<faz X>para<público>,<principal diferencial>." - Primeiro bloco de código acima da linha 60. Todo comando deve ser copiável e real.
- Mostre a saída após comandos quando ajudar (
# => ...ou um bloco separado). - Use tabelas para opções e comparações, listas para funcionalidades (benefício primeiro).
- Vincule, não cole: documentações longas, changelogs e referências de API vão para outro lugar.
- Toda imagem deve ter alt text; prefira um SVG ou um GIF curto do fluxo principal.
- Pitch: uma frase, com menos de 200 caracteres, sem palavras de hype. Padrão:
"
-
Badges. Use apenas badges que sejam verdadeiros e mantidos, nesta ordem: status da CI, versão mais recente (PyPI/npm/Packagist/release), downloads (opcional), licença. Exemplos em structure.md.
-
Refaça o lint até que não haja erros. Resolva avisos ou informe ao usuário por que não.
-
Verifique os links que o linter não consegue: URLs absolutas e âncoras. Teste clicando ou explique quais não foram verificados.
Saída
- O README.md novo ou atualizado (mostre um resumo diff para reescritas).
- O resultado final do lint.
- Uma lista curta de fatos que você não pôde verificar e placeholders que o usuário deve preencher (GIF de demonstração, screenshots, números de benchmark).
Regras de lint
| Regra | Nível | Significado |
|---|---|---|
| title | erro/aviso | exatamente um H1 |
| pitch | erro/aviso | um primeiro parágrafo curto abaixo do título |
| badges | aviso | nenhum badge encontrado |
| install | erro/aviso | seção de instalação (ou início rápido), com um bloco de código |
| quickstart | erro/aviso | seção de uso, início rápido ou exemplo, com código |
| code | erro | nenhum bloco de código |
| scroll | aviso | primeiro bloco de código após --max-scroll linhas (padrão 60) |
| contributing, license | aviso | seção ausente |
| faq, toc | informação | sugerido |
| alt-text | aviso | imagem sem alt text |
| broken-link | erro | link relativo para um arquivo ausente, ou link vazio |
| broken-anchor | erro | link #anchor (sumário) que não corresponde a nenhum heading ou id/name HTML, usando regras de slug do GitHub |
| placeholder | aviso | TODO, TBD ou lorem ipsum deixados |
Saída com código 1 em caso de erros (e com avisos, se --strict).