Gerador de README
Crie arquivos README.md polidos e completos para repositórios de código internos/da empresa, analisando o código-fonte real e fazendo perguntas direcionadas para esclarecimentos.
Por que essa habilidade existe
Um bom README é a porta de entrada para um repositório de código. Em projetos internos, especialmente, a falta de um README ou um README incompleto significa que cada novo membro da equipe perde horas tentando entender o que o projeto faz, como executá-lo e por onde começar. Essa habilidade automatiza o trabalho pesado — ela lê o código, infere o que pode, pergunta sobre o que não consegue inferir e produz um README que deixa os desenvolvedores produtivos rapidamente.
Fluxo de Trabalho
Etapa 1: Analisar o código-fonte
Antes de perguntar qualquer coisa ao usuário, execute uma análise estruturada em quatro fases para reunir o máximo de contexto possível. Isso reduz a carga sobre o usuário — ele só precisa preencher lacunas, não descrever coisas que você já pode ver.
Etiquete cada fato com um nível de confiança: [confirmado] (lido da fonte), [inferido-alto] (evidência forte), [inferido-baixo] (evidência parcial) ou [desconhecido]. Descobertas de baixa confiança e desconhecidas se tornam perguntas de esclarecimento na Etapa 2.
Consulte referências/fases-de-analise.md para obter ações de ferramentas detalhadas, padrões de grep, checklists de extração e modelos de registro.
Fase 1 — Varredura de Metadados do Projeto: Faça glob para arquivos de gerenciador de pacotes (pyproject.toml, package.json, etc.), templates de ambiente, Dockerfiles, configurações de CI/CD e arquivos de toolchain. Leia cada um e extraia: nome/versão do projeto, linguagem, dependências (categorizadas com propósitos), scripts/comandos, variáveis de ambiente (obrigatórias vs. opcionais), estágios de CI, licença.
Fase 2 — Varredura de Arquitetura: Faça glob para todos os arquivos fonte para mapear a estrutura de diretórios. Use grep para identificar marcadores de ponto de entrada (if __name__, main(), etc.) e leia cada ponto de entrada. Construa o gráfico de importações usando grep para instruções de importação em todos os arquivos fonte — classifique os módulos como core (alto grau de entrada), folha ou orquestrador. Identifique o padrão de arquitetura (pipeline, MVC, camadas, microsserviços, orientado a eventos, CLI, monolito) usando a checklist de indicadores. Use grep para encontrar padrões de carregamento de configuração, a fim de localizar arquivos de configuração em tempo de execução.
Fase 3 — Análise Profunda de Módulos: Leia cada arquivo fonte significativo (priorizados: core → ponto de entrada → maiores → restante). Para cada um, extraia: propósito (uma frase), exports chave com assinaturas, notas de design (decisões não óbvias, casos de borda, convenções) e dependências internas. Rastreie o fluxo de trabalho principal de ponta a ponta através do gráfico de importações, rotulando quais tipos de dados fluem entre os módulos. Para bases de código com 8 ou mais arquivos fonte, despache subagentes paralelos agrupados por cluster de dependências.
Fase 4 — Varredura de Infraestrutura de Suporte: Faça glob para arquivos de teste e fixtures. Leia as primeiras 30-50 linhas de cada arquivo de teste para construir um mapeamento teste-para-módulo. Use grep para classes de exceção personalizadas e instruções raise para mapear a hierarquia de erros. Varra templates, assets e documentação existente. Extraia cenários de erro comuns para a tabela de Solução de Problemas.
Etapa 2: Fazer perguntas esclarecedoras
Após a análise, pergunte ao usuário sobre coisas que você não conseguiu inferir com confiança. Mantenha o foco — não pergunte sobre coisas que você já sabe. Lacunas comuns incluem:
- Propósito do projeto: Qual problema ele resolve? Quem o usa? (se não estiver óbvio pelo código)
- Pegadinhas de configuração: Existem pré-requisitos não óbvios, requisitos de VPN, registros de pacotes internos ou etapas de configuração de banco de dados?
- Fluxos de trabalho principais: Quais são as 2-3 coisas que um desenvolvedor faz com mais frequência neste projeto?
- Implantação: Como/onde isso é implantado? (se não estiver claro nas configurações de CI/CD)
- Convenções da equipe: Existem convenções de nomenclatura, estratégias de branch ou padrões a serem mencionados?
- Informações de contato: Quem é o proprietário/mantenedor deste projeto? (nome + email para a seção de Contato)
Apresente suas perguntas de forma concisa. Se o código for direto e você estiver confiante em sua análise, pode precisar de apenas 1-2 perguntas — ou mesmo nenhuma. Use seu julgamento.
Etapa 3: Gerar o README.md
Escreva o README usando a estrutura e as diretrizes abaixo.
Estrutura do README
Use este como seu modelo. Inclua todas as seções, mas ajuste a profundidade de acordo com a complexidade do projeto. Use réguas horizontais --- entre cada seção principal para dar respiro visual.
# Nome do Projeto
  
Descrição breve e clara. Use **negrito** para destacar a tecnologia chave ou o tipo de produto.
---
## Índice
Gere um índice completo e aninhado que inclua TODOS os cabeçalhos ## e ###. Recue as subseções sob suas seções pai para que os leitores possam ver a estrutura completa de relance. Isso é especialmente importante em READMEs mais longos — o índice serve tanto como uma ferramenta de navegação quanto como um esboço de todo o documento.
Exemplo da profundidade esperada:
- [Visão Geral](#visão-geral)
- [Arquitetura](#arquitetura)
- [Arquitetura de Alto Nível](#arquitetura-de-alto-nível)
- [Estrutura de Pastas](#estrutura-de-pastas)
- [Grafo de Dependências de Módulos](#grafo-de-dependências-de-módulos)
- [Primeiros Passos](#primeiros-passos)
- [Pré-requisitos](#pré-requisitos)
- [Instalação](#instalação)
- [Executando Testes](#executando-testes)
- [Variáveis de Ambiente](#variáveis-de-ambiente)
- [Uso](#uso)
- [Exemplo: Caso de Uso Principal](#exemplo-caso-de-uso-principal)
- [Exemplo: Caso de Uso Secundário](#exemplo-caso-de-uso-secundário)
- [Referência da API](#referência-da-api)
- [Recurso A](#recurso-a)
- [Recurso B](#recurso-b)
- [Solução de Problemas](#solução-de-problemas)
- [Contato](#contato)
- [Licença](#licença)
Cada cabeçalho ### no documento deve aparecer como uma entrada recuada sob seu cabeçalho ## pai. Não pule subseções — o objetivo de um índice completo é que os leitores possam pular diretamente para qualquer parte do documento.
---
## Visão Geral
Expanda a descrição. Coloque termos chave em negrito. Use listas numeradas para processos de várias etapas.
---
## Arquitetura
### Arquitetura de Alto Nível
```mermaid
graph TD
...
### Estrutura de Pastas
raiz-do-projeto/ ├── src/ # Breve anotação ├── tests/ # Breve anotação └── ...
### [Fluxo de Dados / Pipeline / Dependências de Módulos — diagramas adicionais]
```mermaid
...
Primeiros Passos
Pré-requisitos
Instalação
Executando Testes
Variáveis de Ambiente
| Variável | Obrigatória | Descrição |
|---|---|---|
DB_URL | Sim | String de conexão PostgreSQL |
Uso
Exemplos de código reais para as 2-3 operações mais comuns.
Referência da API
Solução de Problemas
| Sintoma | Causa Provável | Correção |
|---|---|---|
mensagem de erro | O que está errado | Como corrigir |
Contato
Para perguntas ou suporte, entre em contato:
- Nome — [email protected]
Licença
Uso Interno Apenas – Nome da Empresa Software proprietário. © [Ano] [Empresa]. Todos os direitos reservados.
## Badges do Shields.io
Sempre inclua badges do shields.io logo após o título `# Nome do Projeto` (3-6 badges cobrindo linguagem, framework, biblioteca principal, gerenciador de pacotes, banco de dados, infraestrutura). Consulte [referências/referencia-de-badges.md](referências/referencia-de-badges.md) para obter formato, exemplos e sugestões de cores por categoria.
## Diretrizes para Diagramas Mermaid
Use diagramas Mermaid generosamente — eles tornam a arquitetura, os fluxos de dados e os processos imediatamente compreensíveis. Um README típico deve ter **3-6 diagramas**; projetos complexos (pipelines de dados, sistemas com vários serviços) podem ter **6-10+**. Consulte [referências/diretrizes-mermaid.md](referências/diretrizes-mermaid.md) para saber quando usar cada tipo de diagrama, melhores práticas e recomendações específicas por tipo de projeto.
## Diretrizes de Escrita
- **Seja específico em vez de genérico.** "Execute `npm run dev`" é melhor do que "Inicie o servidor de desenvolvimento." Inclua comandos reais, caminhos de arquivos e nomes de variáveis.
- **Escreva para o novo membro da equipe.** Presuma habilidades gerais de engenharia, mas zero contexto do projeto.
- **Coloque em negrito termos chave e nomes de produtos** na primeira menção e nas visões gerais. Isso ajuda os leitores a escanear.
- **Use listas numeradas para processos sequenciais.** "1. **Extrai** dados de X. 2. **Transforma** os dados. 3. **Carrega** em Y." — coloque o verbo em negrito.
- **Exemplos de código devem ser executáveis.** Copie do código real sempre que possível.
- **Tabelas de variáveis de ambiente são inegociáveis.** Liste cada uma delas.
- **Solução de problemas em formato de tabela** (Sintoma | Causa Provável | Correção) — escaneável e consistente.
- **Anotações da estrutura de pastas devem ser breves.** Uma frase curta por diretório.
- **Sempre inclua uma seção de Contato.** Pergunte ao usuário quem mantém o projeto. Formato: `**Nome** — [email protected]`.
- **Use réguas horizontais `---`** entre todas as seções principais para estrutura visual.
## Saída
Salve o README como `README.md` na raiz do repositório (ou no diretório de trabalho atual se nenhuma raiz do repositório for identificável). Se um `README.md` já existir, confirme com o usuário antes de sobrescrever — ele pode querer manter partes dele.