README do Projeto
Um README não é um manual de parâmetros nem um anúncio. É o caminho mais curto para ajudar um novo leitor a confiar em um projeto e obter um primeiro resultado.
Não preencha seções por preenchê-las. Um leitor deve ser capaz de responder a três perguntas: O que é isso? É adequado para mim? Posso obter um primeiro resultado e entender os limites de risco?
Princípios Fundamentais
- Cada afirmação precisa de evidência. Omita afirmações que não podem ser verificadas no repositório ou confirmadas pelo usuário; não suavize um palpite em prosa vaga.
- Um Guia de Início Rápido é obrigatório: forneça o caminho real mais curto da instalação a um resultado útil. Se seus comandos não puderem ser verificados, pergunte em vez de deixar espaços em branco ou inventá-los.
- Quando um README já existir, pergunte se deve substituí-lo, preservar material selecionado ou estendê-lo no lugar. Não adivinhe nem sobrescreva conteúdo escrito pelo usuário.
- Estabeleça identidade e um ponto de entrada acima da dobra. Para projetos públicos, use o nome/logotipo do projeto, descrição de uma linha, badges reais e navegação, então coloque o Guia de Início Rápido imediatamente depois. Use um GIF/captura de tela apenas quando transmitir mais do que texto.
- Mostre em vez de afirmar: saída de terminal, capturas de tela, código e números verificados são mais fortes que adjetivos.
- Organize por tarefa, não por parâmetro. Explique "o que quero fazer → qual comando faz isso"; deixe listas completas de opções para
--help. - Remova qualquer linha que não ajude o leitor a decidir, confiar ou agir.
- Se o projeto tocar em arquivos locais, bancos de dados, credenciais, redes ou chamadas de modelo, explique o que ele lê, escreve e envia para fora do dispositivo e sua postura padrão de somente leitura/confirmação/backup/fechamento em caso de falha. Não faça promessa de segurança sem evidência de código.
- Mantenha o README como porta de entrada; vincule detalhes profundos a
docs/ouCONTRIBUTING.mdem vez de transformar o README em um manual. - Corresponda ao projeto; não force um único modelo em CLI, MCP, bibliotecas, aplicativos e repositórios de pesquisa.
- Evite alegações não verificadas como "líder do setor", "pronto para produção" ou "desempenho extremo". Veja as diretrizes em
content-writing.
Escolha o Público
Classifique o leitor do README para definir o nível de detalhe:
- Solo (projeto pessoal, ferramenta interna ou script pessoal): o leitor é principalmente você, incluindo seu eu futuro. Obrigatório: descrição de uma linha, Guia de Início Rápido e limitações conhecidas. Badges, guia de contribuição, canais da comunidade, histórico de estrelas e roadmap são opcionais. O básico é que você ainda consiga executá-lo três meses depois.
- Público (código aberto, software distribuído ou compartilhado em equipe): o leitor é um estranho. Inclua descrição, valor, Guia de Início Rápido, uso, configuração, índice de documentação, contribuição e licença. Adicione badges e informações da comunidade apenas quando realmente existirem.
Padrão para público se o repositório for público, publicado em um gerenciador de pacotes ou tiver usuários externos; padrão para solo para projetos pessoais privados e trabalhos únicos. Para casos mistos, use o detalhe público.
Escolha o Modo
| Modo | Quando usar | Primeiro passo |
|---|---|---|
| criar | Nenhum README existe, ou o usuário solicita explicitamente uma reescrita | Inspecione o repositório e colete fatos. |
| melhorar | Um README existe e precisa de trabalho | Leia-o, pergunte como lidar com o conteúdo existente e então prossiga. |
| auditar | O usuário solicita apenas diagnóstico | Verifique cada afirmação do README em relação ao repositório e relate as descobertas. |
Portão: Se um README existir, pause para a escolha do usuário: (1) substituí-lo inteiramente, (2) reescrever retendo material especificado, ou (3) estendê-lo no lugar. "Ajude-me a escrever um README" não implica opção 1.
Acima da Dobra e Estilo de Ferramenta para Desenvolvedores (Projetos Públicos)
Os leitores decidem se continuam após uma tela. A primeira tela deve mostrar o que o projeto faz.
Para CLI, MCP e ferramentas de desenvolvedor locais, prefira documentação de desenvolvedor contida e verificável:
<div align="center">
Logotipo opcional
# Nome do projeto
**Descrição de uma linha**
Apenas badges reais
Seletor de idioma (apenas quando o outro README existir)
Navegação por âncora (quando o documento exceder 100 linhas)
</div>
---
Visão geral das capacidades: comandos/ferramentas reais, entradas, saídas e postura de segurança padrão
Três regras:
- Descrição de uma linha: Mantenha memorável e aproximadamente uma linha: o que é, para quem é e sua distinção factual mais importante. Guarde princípios e antecedentes para depois.
- Visão geral das capacidades: Liste comandos/ferramentas reais, entradas, saídas, objetos de leitura/escrita e a postura de segurança padrão. Evite alegações genéricas como "rápido, seguro e inteligente".
- Guia de Início Rápido em seguida: Prefira 1 a 3 etapas mais curtas. A etapa final deve verificar a instalação ou descoberta de serviço. Coloque configuração complexa depois.
Material visual é opcional. Escolha GIFs/asciinema, capturas de tela e saída real do terminal apenas quando adicionarem informações. Se não houver ativo de demonstração, não invente um; forneça comandos reais, saída esperada e etapas de verificação.
Projetos solo podem omitir logotipos, badges e navegação, mas uma descrição de uma linha e saída visível ainda são úteis.
Escada de Evidências
Antes de escrever cada afirmação, classifique sua evidência:
| Nível | Fonte | Uso |
|---|---|---|
| 1 | No repositório: código-fonte, testes, exemplos, configuração, CI, Tags, capturas de tela | Escreva diretamente. |
| 2 | Confirmado pelo usuário: posicionamento, diferenciação, métricas, capturas de tela, casos | Escreva diretamente. |
| 3 | Verificável externamente: página do pacote, Release, benchmark público | Escreva com um link. |
| 4 | Nenhuma fonte | Omita. Pergunte se importante; caso contrário, remova. |
Nunca invente comandos de instalação, parâmetros de CLI, assinaturas de API, chaves de configuração, variáveis de ambiente, caminhos, números de desempenho, alegações de compatibilidade, termos de licença ou links da comunidade.
Consulte references/evidence.md para a varredura do repositório e regras de evidência.
Fluxo de Trabalho
- Classifique público e modo: solo/público e criar/melhorar/auditar. Se um README existir, pergunte como lidar com ele antes de alterá-lo.
- Colete evidências do repositório: inspecione metadados do pacote, pontos de entrada, estrutura, configuração, documentos, Git/CI, ativos, caminhos de leitura/escrita, credenciais, redes, chamadas de modelo e códigos de erro. Esta etapa coleta fatos, não conclusões; veja
references/evidence.md. - Classifique o projeto e o leitor: CLI, MCP, biblioteca, aplicativo, projeto de pesquisa, Skill de Agente ou monorepo. Use isso para selecionar seções; veja
references/structure.md. - Verifique o Guia de Início Rápido: encontre e verifique o primeiro comando que produz um resultado útil após a instalação. Se não puder ser verificado, pergunte e não prossiga além deste portão.
- Planeje as seções: selecione seções para o tipo de projeto e identifique evidências para cada uma. Omita seções sem suporte. Decida também o layout acima da dobra, verificação do Guia de Início Rápido e se segurança/fluxo de dados, códigos de erro ou solução de problemas são necessários.
- Rascunho: identidade e capacidades → Guia de Início Rápido → características → instalação/configuração → uso baseado em tarefas → justificativa/antecedentes → limites de segurança/privacidade → erros/solução de problemas → limitações conhecidas → desenvolvimento/documentação aprofundada. Explique a justificativa depois que o leitor tiver um caminho funcional, não antes.
- Execute o portão de qualidade: verifique cada item em
references/checklist.md, especialmente precisão factual e etapas executáveis. - Entregue: forneça um rascunho na conversa por padrão; grave em disco apenas quando explicitamente solicitado. Reexecute a lista de verificação antes de escrever.
Saída
Declare de forma concisa: (1) público e modo; (2) tipo de projeto e leitor-alvo; (3) plano de seções e fonte de evidência para cada seção; (4) o rascunho do README; (5) alegações que precisam de confirmação do usuário porque faltam evidências; e (6) omissões conhecidas. Nunca rotule um palpite como verificado. Liste explicitamente alegações sem suporte em vez de disfarçá-las com linguagem vaga.
Bandeiras Vermelhas
- Guia de Início Rápido ausente ou em branco, ou comandos inventados sem ponto de entrada no repositório.
- Sobrescrita de um README existente sem perguntar como lidar com ele.
- Alegações não confirmadas de desempenho, compatibilidade, contagem de usuários ou contagem de estrelas.
- Badges que apontam para CI, pacotes ou licenças inexistentes.
- Preenchimento de seções de modelo com cabeçalhos vazios ou "TODO/em breve".
- Incorporação de um manual completo de API em vez de vincular a ele.
- Reprodução de uma longa tabela
--helpem vez de mostrar comandos baseados em tarefas. - Tela de abertura com apenas slogans ou princípios e nenhum ponto de entrada real ou resultado verificável.
- Omissão de informações de segurança/fluxo de dados para ferramentas que tocam dados locais, credenciais, redes ou chamadas de modelo.
- Promessa de operação somente leitura, sem vazamento de dados, comportamento de falha fechada ou configuração zero sem evidência de código/teste.
- Solução de problemas que diz apenas "reiniciar" sem sintoma, código de erro, causa e remédio.
- Descrição de uma linha que é um parágrafo, ou justificativa que aparece antes do primeiro caminho executável.
- Adjetivos como "poderoso", "elegante", "extremo" ou "pronto para uso" substituindo evidências.
- Forçar guias de contribuição, códigos de conduta ou links da comunidade em um projeto solo quando nenhum existe.
- Diagramas de arquitetura contendo componentes ou relações de chamada inexistentes.
- Gravação de arquivos sem autorização do usuário.
Referências
Leia apenas o necessário:
references/structure.md: fluxo de leitura, seleção de seções por tipo de projeto e orientação para escrita de seções.references/evidence.md: varredura do repositório, níveis de evidência e alegações que não devem ser inventadas.references/checklist.md: portão de qualidade pré-escrita para fatos, usabilidade, apresentação e linguagem.