0

12 habilidades de IA para aprender em 2026

Há alguns anos, quando alguém dizia que “sabia inteligência artificial”, normalmente queria dizer uma de três coisas: tinha feito um curso introdutório de Machine Learning, sabia chamar alguma API de visão computacional, ou tinha decorado meia dúzia de termos que ficavam bonitos em uma apresentação de PowerPoint. Em 2026 a situação mudou, mas não necessariamente melhorou: agora temos gente confundindo prompt com carreira, agente com funcionário e automação com milagre.

Em minha não tão humilde opinião, o problema não é falta de material. É excesso de material empilhado sem ordem, como aquele diretório Downloads que todo mundo jura que um dia vai arrumar. A pergunta correta não é “qual ferramenta de IA devo aprender?”, mas sim “qual competência vem antes da outra, e que projeto prova que eu realmente entendi?”.

Sem mais delongas, vamos ao mapa.

1 — Prompt engineering: o básico que deixou de ser cargo

Prompt engineering é a capacidade de dar instruções claras para modelos como ChatGPT, Claude, Gemini, Qwen, Llama e seus parentes cada vez mais numerosos. Parece trivial, até você comparar “escreva um e-mail” com uma instrução que define público, objetivo, tom, restrições, exemplos bons, formato de saída e critérios de qualidade.

A diferença é brutal.

Mas há uma pegadinha: em 2026, “engenheiro de prompt” como cargo isolado virou mais meme do que profissão. Prompt é o alfabeto. Ninguém contrata alguém porque ele sabe o alfabeto; contrata porque ele escreve contratos, sistemas, diagnósticos ou código com ele.

O que você precisa dominar aqui:

  • Definir papel, contexto e objetivo.
  • Dar exemplos bons e ruins.
  • Pedir saída estruturada, especialmente JSON, tabelas ou checklists.
  • Saber quando colocar mais contexto e quando remover lixo.
  • Entender janela de contexto, tokens e custo.

Projeto inicial: crie um assistente que leia uma descrição de vaga e adapte seu currículo para aquela vaga, preservando fatos reais. Se ele inventar experiência que você não tem, você aprendeu duas coisas: prompts importam e modelos mentem com ótima dicção.

2 — Automação com IA: onde o retorno aparece rápido

Automação com IA é usar modelos para executar partes repetitivas de um fluxo: classificar e-mails, resumir tickets, extrair dados de notas fiscais, transformar um artigo em posts menores ou enriquecer leads em um CRM.

Aqui entram ferramentas como n8n, Make e Zapier. O n8n, em especial, tem a vantagem de poder ser auto-hospedado, o que deixa administradores menos propensos a desenvolver urticária quando aparece a palavra “dados sensíveis”.

A automação é uma das habilidades com melhor relação esforço/retorno porque resolve dores simples e mensuráveis. Uma empresa pequena talvez não queira “transformação digital com IA generativa”. Mas ela quer parar de perder duas horas por dia copiando dados de e-mail para planilha. A diferença é que a segunda frase tem orçamento.

Projeto inicial: um digest diário de e-mails ou mensagens, agrupado por assunto, prioridade e ação recomendada. Se você conseguir fazer isso sem mandar dados confidenciais para a primeira API aleatória que apareceu no YouTube, melhor ainda.

3 — APIs de IA: sair do chat e entrar na cozinha

Usar um modelo pelo navegador é como pedir comida no balcão. Usar a API é entrar na cozinha com acesso à bancada, aos ingredientes e ao sistema de pedidos. A comida é parecida; o poder de escala, não.

Quando você aprende APIs, começa a construir produtos e não apenas conversas. Você envia requisições, define parâmetros, controla temperatura, limita tokens, pede respostas estruturadas e trata erros. Parece burocrático porque é burocrático. Burocracia bem feita é o que separa um protótipo simpático de um serviço que não explode quando alguém clica duas vezes.

Você não precisa virar um engenheiro sênior de software no primeiro mês. Mas precisa saber Python o suficiente para:

  • Ler variáveis de ambiente.
  • Fazer uma chamada HTTP.
  • Tratar erro de rede e limite de taxa.
  • Validar JSON.
  • Salvar resultado em arquivo ou banco.

Projeto inicial: um resumidor de artigos via linha de comando. Ele recebe uma URL, extrai o texto, chama o modelo e devolve pontos principais, riscos, entidades citadas e uma conclusão curta.

4 — Workflows de IA: parar de pedir tudo em uma oração só

O erro mais comum de quem começa é escrever um megaprompt que tenta fazer pesquisa, checagem, análise, redação, revisão e SEO em uma única chamada. Funciona uma vez, falha na segunda, e na terceira você já está negociando com a máquina como se ela fosse um oráculo temperamental.

Workflow é decompor o trabalho em etapas:

  1. Extrair as informações relevantes.
  2. Verificar afirmações importantes.
  3. Estruturar o argumento.
  4. Escrever o rascunho.
  5. Revisar estilo e consistência.
  6. Pedir aprovação humana antes de publicar.

Cada etapa tem uma função clara. Cada saída pode ser inspecionada. Cada erro tem um lugar provável. Isso se chama engenharia, uma prática antiga que aparentemente precisamos redescobrir a cada nova moda tecnológica.

Duas ideias são fundamentais: roteamento e checkpoints humanos. Roteamento manda tarefas simples para modelos baratos e tarefas difíceis para modelos melhores. Checkpoints impedem que uma IA publique bobagem em seu nome, envie e-mail errado para cliente ou apague algo importante porque “parecia razoável”.

Projeto inicial: um pipeline que transforma um post técnico em três formatos: resumo executivo, thread curta e checklist operacional. Cada transformação deve ser uma etapa separada.

5 — Modelos open source/open weight: privacidade, custo e soberania

Modelos como Llama, Qwen, DeepSeek, Gemma, Mistral e outros mudaram o jogo. Tecnicamente muitos são “open weight”, não open source no sentido clássico, mas o ponto prático é que você pode baixar, rodar, quantizar, testar e adaptar.

Isso ensina coisas que o chat escondia: inferência, quantização, tamanho de contexto, VRAM, throughput, latência e custo real. Descobrir que um modelo 8B quantizado cabe em um notebook decente é educativo. Descobrir que um modelo maior consome GPU como um adolescente consome internet também é.

Por que empresas se importam? Privacidade e custo. Bancos, escritórios jurídicos, hospitais e empresas com dados sensíveis nem sempre podem mandar tudo para uma API externa. E, em alto volume, auto-hospedar pode ser mais barato do que pagar por token eternamente.

Projeto inicial: instale Ollama ou LM Studio, rode um modelo local e construa um assistente privado para consultar suas próprias notas. Não precisa ser perfeito. Precisa funcionar sem mandar tudo para fora.

6 — RAG: dar memória documental ao modelo sem fingir que ele sabe tudo

RAG, Retrieval Augmented Generation, é a técnica de buscar documentos relevantes e entregá-los ao modelo no momento da pergunta. Em vez de torcer para que ele “saiba” algo, você dá o material certo e exige que ele responda baseado nele.

A estrutura básica é simples:

  1. Quebrar documentos em pedaços.
  2. Gerar embeddings.
  3. Armazenar em um banco vetorial.
  4. Buscar os trechos mais relevantes.
  5. Passar esses trechos para o modelo responder.

Embeddings transformam texto em vetores numéricos. Banco vetorial encontra proximidade semântica. Isso permite que “como peço meu dinheiro de volta?” encontre “política de reembolso”, mesmo que as palavras não coincidam.

RAG é uma das habilidades mais empregáveis hoje porque grande parte dos projetos corporativos de IA é, no fundo, um chatbot em cima de documentação interna. O problema é que RAG ingênuo atinge teto rápido. O diferencial está em chunking, busca híbrida, reranking, controle de fontes e avaliação.

Projeto inicial: um assistente para PDFs que responde perguntas citando o trecho de origem. Se ele não consegue apontar de onde tirou a resposta, ainda não é sistema; é papagaio-de-pirata com GPU.

7 — Fine-tuning e LoRA: mudar comportamento, não só contexto

Fine-tuning é treinar um modelo já existente com exemplos adicionais para ajustar comportamento, formato ou domínio. RAG dá uma biblioteca ao modelo. Fine-tuning muda seus hábitos.

Mas é preciso algum bom senso. Fine-tuning não é a primeira resposta para tudo. Muitas vezes prompt melhor, RAG decente e exemplos bem escolhidos resolvem com menos custo e menos risco. Fine-tuning começa a fazer sentido quando:

  • Você precisa de estilo ou formato consistente em escala.
  • Quer que um modelo menor execute uma tarefa específica como um maior.
  • Seus prompts viraram monstros de 500 linhas.
  • Você tem exemplos bons o suficiente para ensinar o comportamento desejado.

LoRA e QLoRA tornaram isso acessível porque treinam adaptadores pequenos sobre um modelo congelado, sem retreinar o monstro inteiro. Ainda assim, lixo entra, lixo sai — agora com checkpoints.

Projeto inicial: ajuste um modelo pequeno com algumas centenas de exemplos do seu próprio estilo de escrita ou de respostas técnicas padronizadas. Meça antes e depois. Sem avaliação, fine-tuning vira ritual xamânico com CUDA.

8 — Agentes de IA: quando o modelo ganha ferramentas

Um agente é um LLM em loop usando ferramentas. Ele recebe um objetivo, escolhe ações, observa resultados e continua até terminar ou até encontrar uma parede, o que também acontece com frequência.

Ferramentas podem ser busca web, shell, banco de dados, e-mail, calendário, APIs internas, arquivos, navegador. O modelo deixa de apenas responder e passa a agir. Isso é poderoso e perigoso na mesma medida, que é basicamente a definição de qualquer tecnologia interessante.

MCP, o Model Context Protocol, merece atenção aqui. Ele tenta padronizar como agentes se conectam a ferramentas e fontes de dados. Aprender MCP em 2026 lembra aprender REST alguns anos atrás: não é glamour, é infraestrutura. E infraestrutura é o que continua pagando boletos quando o hype muda de roupa.

Mas um aviso: nem tudo precisa ser agente. Muitos sistemas de produção chamados de “agentes” são workflows bem definidos com um ou dois passos agentivos. Isso é saudável. Agente solto demais costuma descobrir maneiras criativas de falhar.

Projeto inicial: implemente um agente simples em Python com loop explícito, duas ferramentas e limite de iterações. Só depois use frameworks como LangGraph, CrewAI ou SDKs específicos.

9 — Sistemas multi-agente: especialistas coordenados, não festa infantil

Multi-agente é dividir o trabalho entre agentes especializados: planejador, pesquisador, executor, revisor, auditor. Em tese, cada um recebe contexto menor e função mais clara. Na prática, cada agente novo adiciona custo, latência e modo de falha.

Os padrões mais comuns são:

  • Supervisor: um agente coordena e delega.
  • Pipeline: cada agente transforma a saída do anterior.
  • Debate/revisão: agentes criticam resultados para encontrar erros.

Isso pode funcionar muito bem quando a tarefa realmente tem partes independentes. Também pode virar teatro caro, com cinco agentes fazendo o trabalho que uma função Python e um checklist resolveriam.

A regra operacional é simples: use o menor número de agentes que resolve o problema. Se um workflow linear basta, use workflow. Se uma função determinística basta, use código. Se uma planilha basta, talvez o problema nem fosse de IA. Chocante, eu sei.

Projeto inicial: um estúdio de conteúdo com três papéis: pesquisador, redator e revisor. O revisor deve ter poder real de rejeitar a saída, não apenas elogiar em tom corporativo.

10 — Avaliação de LLMs: a habilidade que separa demo de produto

Avaliação mede se um sistema de IA é bom e se uma mudança o tornou melhor ou pior. É teste automatizado em um mundo probabilístico, o que parece contradição apenas até você precisar operar isso em produção.

O fluxo básico:

  1. Monte um conjunto de casos reais.
  2. Defina o que é uma boa resposta.
  3. Rode versões diferentes do sistema.
  4. Compare precisão, fidelidade, formato, custo e latência.
  5. Faça revisão humana em amostras.

Você pode usar regras de código, validação de JSON, comparação com resposta esperada, revisão humana e LLM-as-judge. Juízes automáticos ajudam, mas também erram. Logo, precisam ser avaliados. Sim, avaliamos o avaliador. Bem-vindo à recursão profissional.

Essa é uma das habilidades mais valiosas porque qualquer um constrói uma demo que impressiona por cinco minutos. Poucos conseguem provar que o sistema melhorou depois de uma alteração ou detectar regressão antes do cliente.

Projeto inicial: crie 30 perguntas para seu assistente de PDF, com respostas esperadas e trechos de referência. Depois rode cada mudança contra esse conjunto.

11 — Deploy de LLMs: curar-se da “works on my machine syndrome”

Deploy é transformar o experimento em serviço: API, web app, autenticação, rate limit, logs, rollback e custo controlado.

Há dois caminhos principais. O mais simples usa uma API hospedada por terceiros atrás de um backend próprio, normalmente FastAPI, Node ou algo equivalente. O caminho mais avançado hospeda modelo open weight com ferramentas como vLLM, TGI ou servidores compatíveis com OpenAI API.

É aqui que aparecem detalhes pouco românticos:

  • Streaming de resposta.
  • Fallback entre provedores.
  • Limite de custo por usuário.
  • Autenticação e autorização.
  • Observabilidade.
  • Controle de versão de prompts.
  • Proteção contra abuso.

“Na minha máquina funciona” é um estado larval. Produção começa quando alguém que não é você usa o sistema às duas da manhã e ele continua vivo.

Projeto inicial: publique seu assistente avaliado como uma aplicação web com login, limite de uso e logs básicos. Se não houver logs, o bug continua existindo; só está escondido.

12 — LLMOps: manter o bicho funcionando

LLMOps é tudo que mantém sistemas de IA úteis depois do deploy. Se deploy é inaugurar o restaurante, LLMOps é comprar insumo, medir desperdício, controlar qualidade, pagar funcionários e impedir que a cozinha pegue fogo.

Na prática, envolve:

  • Tracing de cada requisição.
  • Métricas de custo, latência e erro.
  • Avaliação contínua de amostras reais.
  • Versionamento de prompts.
  • Dashboards.
  • Alertas.
  • Guardrails.
  • Auditoria de chamadas de ferramentas.

Em agentes, guardrail não pode ser apenas filtro de texto no final. Se o agente já executou a ação perigosa, censurar a resposta é fechar a porta depois que o cachorro saiu dirigindo o carro.

Ferramentas como Langfuse, LangSmith, Helicone, OpenTelemetry e pipelines de CI/CD entram aqui. A parte menos glamourosa é exatamente a mais valiosa: empresas já sabem fazer piloto. O problema é operar com confiabilidade e custo aceitável.

Projeto final: pegue um app com IA e adicione tracing, dashboard de custo, avaliação automática, alarme de queda de qualidade e versão dos prompts. Depois tente quebrá-lo de propósito.

Como ordenar os estudos

A sequência faz sentido porque cada habilidade alimenta a próxima:

  • Prompting alimenta APIs.
  • APIs alimentam workflows.
  • Workflows ficam mais úteis com RAG.
  • RAG e fine-tuning melhoram comportamento e conhecimento.
  • Agentes usam ferramentas e workflows.
  • Multi-agente amplia coordenação.
  • Avaliação prova qualidade.
  • Deploy coloca em uso.
  • LLMOps mantém vivo.

Você não precisa dominar tudo para ser útil. As quatro primeiras habilidades já colocam muita gente à frente da média em escritórios, times de operação e áreas administrativas. Da quinta à oitava você começa a construir sistemas. Da nona à décima segunda você entra no território que empresas realmente têm dificuldade de contratar: gente que não apenas monta a demo, mas entrega algo operável.

Minha recomendação prática: escolha o ponto onde você está hoje e construa o projeto correspondente. Não pule direto para agentes multi-A2A-orquestrados-com-MCP-em-Kubernetes porque o título parece bonito no LinkedIn. Primeiro faça uma chamada de API decente. Depois um workflow. Depois RAG. Depois avaliação. Suba um degrau por vez.

A IA vai mudar de forma muitas vezes nos próximos anos. Os nomes das ferramentas vão trocar, alguns frameworks vão sumir, outros serão comprados, e meia dúzia de gurus vai vender o mesmo curso com capa nova. Mas as competências duráveis continuam as mesmas: orientar modelos com precisão, conectá-los a dados reais, dar ferramentas com segurança, medir resultado e operar em produção.

O roadmap só funciona se você caminhar. O resto é slide.

 

Guia operacional para um repositório open source no GitHub

Ilustração de fluxo de colaboração Git e GitHub com pull requests, testes, CI/CD e qualidade de código.

Repositorios open source não crescem apenas com código bom. Eles crescem quando a colaboração é previsível, a branch principal permanece protegida e novos contribuidores conseguem entender rapidamente como participar sem pedir instruções por telepatia. Este guia reúne um modelo operacional prático para organizar branches, pull requests, revisão, automação de qualidade e documentação básica em projetos no GitHub.

Este guia operacional reúne um fluxo prático para manter um repositório open source colaborativo, previsível e atraente para contribuidores. A base recomendada combina branches curtas, pull requests pequenas, revisão obrigatória, automação de qualidade e documentação de entrada clara para reduzir atrito e aumentar a confiança no projeto.

Objetivos do repositório

Um repositório open source bem operado deve atender quatro objetivos ao mesmo tempo: facilitar colaboração, proteger a branch principal, manter qualidade contínua e tornar simples a descoberta e adoção do projeto. Repositórios com README claro, instruções de contribuição e revisões bem estruturadas dão mais contexto para novos usuários e melhoram a experiência de quem quer abrir issue, testar ou enviar PR.

Modelo operacional recomendado

O modelo abaixo funciona bem para projetos individuais que querem crescer com colaboração externa.

ÁreaPadrão recomendado
Branch principalmain protegida contra push direto
Branches de trabalhofeat/*, fix/*, docs/*, refactor/*, chore/*
IntegraçãoSomente via pull request aprovado
QualidadeTestes, lint, formatação e análise de segurança no CI
RevisãoPelo menos 1 aprovação; 2 aprovações em áreas críticas
GovernançaREADME.md, CONTRIBUTING.md, licença, templates de issue e PR

Regras de branch

A branch main deve representar sempre o estado mais confiável do projeto. Para isso, a proteção da branch deve impedir merge sem checks obrigatórios, sem revisão e sem resolução das conversas abertas quando essas regras forem adotadas no repositório.

Política sugerida

  • Bloquear push direto em main.
  • Exigir pull request para merge.
  • Exigir pelo menos 1 review aprovado; usar 2 para código sensível, segurança ou infraestrutura.
  • Exigir status checks obrigatórios, como testes, lint e build.
  • Exigir que conversas do PR sejam resolvidas antes do merge.
  • Exigir branch atualizada com a base antes de merge quando o projeto tiver bastante atividade.
  • Ativar CODEOWNERS para solicitar revisão automática por área do código.

Convenção de nomes de branches

feat/nome-curto-da-feature
fix/descricao-curta-do-bug
docs/ajuste-readme-ou-guia
refactor/modulo-ou-componente
chore/tarefa-operacional

Regras práticas para branches

  • Cada branch deve tratar um único objetivo funcional.
  • Branches devem durar pouco tempo para reduzir conflitos.
  • Evitar PRs gigantes; o ideal é manter diffs pequenos e revisáveis.

Fluxo de contribuição

O fluxo ideal para colaboradores é simples: criar branch, implementar mudança pequena, validar localmente, abrir PR com contexto claro e responder ao review até o merge. O GitHub destaca que bons PRs melhoram a colaboração quando deixam explícitos o objetivo da mudança, o tipo de feedback esperado e a sequência sugerida para revisão.

Fluxo padrão

  1. Abrir uma issue, quando a mudança exigir discussão ou alinhamento prévio.
  2. Criar branch a partir de main.
  3. Implementar a mudança em commits pequenos e objetivos.
  4. Rodar testes, lint e validações locais.
  5. Atualizar documentação e changelog, quando aplicável.
  6. Abrir PR usando o template oficial.
  7. Corrigir feedback, reexecutar checks e concluir merge após aprovação.

Padrão para commits

Commits curtos e legíveis facilitam revisão, rastreabilidade e automação futura. Mesmo quando o projeto não usa Conventional Commits de forma rígida, uma convenção consistente ajuda a entender o histórico e gerar releases com menos esforço.

Convenção sugerida

feat: adiciona cache para respostas da API
fix: corrige validação de token expirado
docs: melhora instruções de instalação
refactor: simplifica carregamento de configurações
test: cobre cenário de retry no cliente HTTP
chore: atualiza workflow de CI

Regras para commits

  • Um commit deve representar uma ideia principal.
  • Evitar commits genéricos como update, fixes ou changes.
  • Preferir verbo no presente e descrição objetiva.

Template de README

O README é o principal ponto de entrada do repositório e deve explicar por que o projeto existe, como instalar, como usar e como contribuir. Um README forte reduz dúvidas repetitivas e aumenta a chance de adoção, fork e estrelas quando o valor do projeto fica visível rapidamente.

Copie e adapte o modelo abaixo para README.md.

# Nome do Projeto

Descrição curta em 1 ou 2 frases explicando o problema que o projeto resolve e para quem ele serve.

## Status

- Estado: ativo / beta / experimental / maintenance
- Versão atual: x.y.z
- Licença: MIT / Apache-2.0 / outra

## Por que este projeto existe

Explique a dor resolvida, o diferencial e o contexto de uso.

## Principais recursos

- Recurso 1
- Recurso 2
- Recurso 3

## Demonstração

Inclua screenshot, GIF, terminal output ou link para demo.

## Instalação

```bash
# exemplo
make install
```

## Uso rápido

```bash
# exemplo
comando --help
```

## Exemplo

Mostre o menor exemplo útil possível.

## Arquitetura

Explique os componentes principais em poucas linhas.

## Requisitos

- Linguagem / runtime
- Dependências externas
- Versão mínima suportada

## Desenvolvimento local

```bash
# setup
make setup

# testes
make test

# lint
make lint
```

## Roadmap

- [ ] Item 1
- [ ] Item 2
- [ ] Item 3

## Como contribuir

Leia [CONTRIBUTING.md](./CONTRIBUTING.md) antes de abrir issue ou pull request.

## Segurança

Informe como reportar vulnerabilidades de forma responsável.

## Licença

Este projeto está licenciado sob a licença X. Consulte `LICENSE`.

Template de CONTRIBUTING

Um CONTRIBUTING.md claro reduz retrabalho e torna previsível a entrada de novos colaboradores. Também ajuda a filtrar contribuições de baixa qualidade ao definir escopo, processo e padrão técnico antes do primeiro PR.

Copie e adapte o modelo abaixo para CONTRIBUTING.md.

# Contribuindo

Obrigado pelo interesse em contribuir.

## Antes de começar

- Leia o README.
- Verifique se já existe issue ou PR relacionado.
- Para mudanças grandes, abra uma issue antes de implementar.

## Tipos de contribuição

- Correção de bugs
- Novos recursos
- Melhorias de documentação
- Testes
- Refatorações
- Exemplos e templates

## Fluxo de trabalho

1. Faça fork do repositório, se necessário.
2. Crie uma branch a partir de `main`.
3. Implemente uma mudança pequena e focada.
4. Adicione ou atualize testes.
5. Rode lint, testes e validações locais.
6. Atualize documentação relevante.
7. Abra um pull request usando o template.

## Padrão de branches

- `feat/*`
- `fix/*`
- `docs/*`
- `refactor/*`
- `chore/*`

## Padrão de commits

Use mensagens claras. Exemplo:

```text
feat: adiciona suporte a configuração por arquivo
fix: corrige falha ao processar credenciais vazias
```

## Qualidade mínima

Um PR deve:

- Passar em todos os checks de CI.
- Manter ou melhorar cobertura de testes quando aplicável.
- Incluir documentação para mudanças visíveis ao usuário.
- Não misturar refatoração ampla com feature nova sem necessidade.

## Pull requests

Ao abrir um PR:

- Explique o problema resolvido.
- Descreva a solução adotada.
- Liste impactos, trade-offs e limitações.
- Vincule a issue correspondente, quando houver.
- Adicione evidências, screenshots ou logs quando fizer sentido.

## Código de conduta

Ao participar deste projeto, espera-se comunicação respeitosa e colaboração construtiva.

## Dúvidas

Use issues, discussões ou o canal definido no README.

Template de pull request

Um template de PR reduz ambiguidades e melhora a qualidade da revisão porque padroniza contexto, validação e impacto da mudança. Também ajuda o mantenedor a identificar rapidamente se o PR está pronto para revisão ou ainda precisa de ajustes.

Copie e adapte o modelo abaixo para .github/pull_request_template.md.

## Resumo

Descreva a mudança em 2 a 5 linhas.

## Problema resolvido

Explique qual problema este PR resolve e por que a mudança é necessária.

## Tipo de mudança

- [ ] Bug fix
- [ ] Nova feature
- [ ] Refatoração
- [ ] Documentação
- [ ] Testes
- [ ] Chore / manutenção

## Como validar

Descreva o passo a passo para testar.

## Evidências

Inclua screenshots, logs, GIFs ou exemplos de saída quando aplicável.

## Checklist

- [ ] Li as diretrizes de contribuição.
- [ ] Mantive o escopo do PR pequeno e objetivo.
- [ ] Rodei testes e validações locais.
- [ ] Atualizei documentação relevante.
- [ ] Adicionei ou ajustei testes quando necessário.
- [ ] O PR está pronto para revisão.

## Issues relacionadas

Closes #

Checklist de revisão para mantenedores

Um checklist explícito ajuda a padronizar reviews e melhora a consistência da qualidade entre mantenedores. O GitHub trata o review de PR como mecanismo central para aprovar, comentar e pedir mudanças antes do merge.

Checklist sugerido

  • O objetivo do PR está claro?
  • O escopo está pequeno o suficiente para revisão segura?
  • A solução está correta tecnicamente?
  • Existem testes cobrindo o comportamento alterado?
  • Há impacto em segurança, performance, compatibilidade ou DX?
  • A documentação foi atualizada?
  • Os checks obrigatórios passaram?
  • Há necessidade de envolver CODEOWNERS ou especialista do domínio?

Regras de branch no GitHub

A configuração abaixo é uma boa base operacional para a branch main.

Configuração sugerida

  • Require a pull request before merging: habilitado
  • Require approvals: 1 mínimo; 2 para áreas críticas
  • Dismiss stale approvals when new commits are pushed: habilitado
  • Require review from Code Owners: habilitado quando houver CODEOWNERS
  • Require status checks to pass before merging: habilitado
  • Require conversation resolution before merging: habilitado
  • Block force pushes: habilitado
  • Block deletions: habilitado

Estrutura mínima recomendada do repositório

Uma estrutura previsível melhora a descoberta do projeto e reduz o tempo até a primeira contribuição.

.
├── .github/
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/
│   └── pull_request_template.md
├── docs/
├── src/
├── tests/
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── SECURITY.md

Automação mínima recomendada

A automação deve verificar qualidade em todo PR e proteger a branch principal contra regressões. O GitHub Actions oferece CI/CD integrado e o GitHub Code Quality pode reportar problemas de qualidade em PRs e scans do repositório.

Pipeline mínimo

  • Build
  • Testes unitários
  • Lint
  • Formatação
  • Análise estática
  • Security/dependency scan

Exemplo de política operacional

  • Nenhum PR entra em main sem checks verdes.
  • Nenhuma feature entra sem documentação mínima.
  • Bugs críticos exigem teste de regressão.
  • Refatorações grandes devem ser quebradas em etapas menores.

Diretrizes para ganhar adoção e estrelas

Projetos ganham mais atenção quando o valor fica evidente nos primeiros segundos de leitura do README e quando existe prova de utilidade, como demo, exemplos e instalação simples. Para um projeto open source crescer, a operação do repositório deve tratar onboarding e reputação como parte do produto, não como detalhe administrativo.

Práticas com maior impacto

  • Mostrar proposta de valor logo no topo do README.
  • Incluir GIF, screenshot ou exemplo executável.
  • Manter instruções de instalação curtas e confiáveis.
  • Aceitar contribuições com regras claras e previsíveis.
  • Responder issues e PRs com consistência para passar confiança à comunidade.

Kit inicial de arquivos

Para colocar este guia em prática rapidamente, o repositório deve começar com os seguintes arquivos:

  • README.md
  • CONTRIBUTING.md
  • .github/pull_request_template.md
  • .github/ISSUE_TEMPLATE/bug_report.yml ou .md
  • .github/ISSUE_TEMPLATE/feature_request.yml ou .md
  • .github/CODEOWNERS
  • LICENSE
  • SECURITY.md
  • CODE_OF_CONDUCT.md
  • Workflow de CI em .github/workflows/ci.yml

Política operacional resumida

A política central do repositório pode ser registrada desta forma:

Todo código entra por pull request pequeno, com contexto claro, revisão obrigatória, automação de qualidade e documentação atualizada. A branch principal permanece protegida e sempre pronta para uso.