Dissequei os perfis do GitHub de 10 engenheiros famosos. Tudo coube em 7 estilos

O GitHub tem um terreno nobre que muita gente deixa vazio. Crie um repositório público com o mesmo nome do seu usuário, coloque um README.md na raiz, e ele aparece no topo do seu perfil — acima dos repositórios fixados, antes de qualquer outra coisa. É a primeira tela que um recrutador gringo, um mantenedor de projeto ou um colega de comunidade vê quando abre a sua página. Se você mira vaga internacional, essa é a sua vitrine, e ela abre antes do seu currículo.

O meu ficou vazio por anos. Caiu a ficha quando um engenheiro me seguiu e eu abri o perfil dele: a página inteira funcionava como portfólio. Bio, produtos, atividade recente — tudo num README, sem visitar site nenhum. Bonito demais pra ignorar. Antes de montar o meu, fui olhar como os grandes fazem: abri o perfil de 10 engenheiros conhecidos (criadores do npm, React, Datasette, textlint) e anotei a estrutura de cada um.

Resultado: tudo coube em 7 estilos. E a escolha entre eles depende menos de gosto e mais de qual é o seu ativo mais forte.

Os 7 estilos que existem

Os 7 estilos de perfil README, com um representante famoso em cada

1. Dashboard auto-atualizável — simonw. Quase zero decoração. Uma tabela de 3 colunas com últimos releases, posts do blog e TILs, preenchida todo dia pelo GitHub Actions. O README vira um feed vivo: quem abre percebe na hora que a pessoa produz sem parar. O criador do Datasette inventou o formato e documentou o esquema em 2020.

2. Minimalista refinado com auto-update — tw93. O criador do Pake resume a bio em 2 linhas, injeta os números reais (12 mil seguidores, quando olhei) e deixa releases e artigos se atualizarem sozinhos. É o estilo 1 depois de passar num designer.

3. Texto de conquistas — azu. Markdown puro, sem um único badge. Mas os números fazem o trabalho: 500+ pacotes npm, 10 milhões de downloads por ano. Funciona quando a bagagem é densa. O caso extremo: gaearon e outros nomes gigantes simplesmente não têm README de perfil. Quando todo mundo já sabe quem você é, o terreno vazio também comunica. Nós, meros mortais, seguimos plantando.

4. Vitrine de widgets — anuraghazra / DenverCoder1. Cards de estatísticas, SVG animado digitando, pins de repositório. O anuraghazra é o próprio autor do github-readme-stats; o DenverCoder1 é um catálogo vivo de tudo que existe em widget.

5. Muro de badges — thmsgbrt. Dezenas de badges do shields.io mapeando a stack inteira, com estrelas e status de CI ao vivo. Rende densidade visual rápido, mas todo perfil desse estilo acaba parecido com o vizinho.

6. Interativo — timburgan. Tem uma partida de xadrez rolando no README. Você clica num lance, abre uma issue, o Actions redesenha o tabuleiro. Quebra a premissa de que README é estático. O card de “tocando agora no Spotify” do andyruwruw é da mesma família.

7. Piada assumida — sindresorhus. Um dos maiores nomes do npm encheu o perfil de GIF anos 90, unicórnio e placa de “em construção”. Só funciona porque a reputação dele chegou antes. Como no estilo 3, errar a ordem dessa jogada sai caro.

Como escolher: parta do seu ativo mais forte

Olhando os 10 perfis, o padrão que se repete: os bons perfis colocam na frente o ativo mais forte da pessoa. Os que não funcionam empilham enfeite sem lastro — badge de 50 tecnologias com 3 repositórios vazios embaixo convence ninguém.

Seu ativo mais forte	Estilo que encaixa
Frequência (artigos e releases toda semana)	1. Dashboard / 2. Minimalista com auto-update
Números acumulados (downloads, anos de projeto)	3. Texto de conquistas
Resultado visual, projetos demonstráveis	4. Widgets / 5. Badges
Criatividade e personalidade	6. Interativo / 7. Piada

No meu caso o ativo é frequência: publico artigo todo dia e livro todo mês. README decorado à mão começa a apodrecer no dia seguinte ao commit; um feed que se alimenta sozinho continua fresco sem eu encostar. Fui de dashboard.

A implementação: 3 peças

Meu perfil montado: header com identidade visual, números reais e feed em 3 colunas

Visto assim, parece perfil de gente grande. Olhe o canto esquerdo de novo: 9 seguidores. Construí a vitrine antes da loja — a loja agradece a paciência.

A estrutura é o esquema do simonw, sem firula. São 3 peças:

Peça 1: marcadores em comentário HTML. Comentários não renderizam, então dá pra demarcar a zona que o robô reescreve, convivendo com o texto fixo no mesmo arquivo:

### Últimos artigos

<!-- feed starts -->
(esta parte é reescrita todo dia)
<!-- feed ends -->

Peça 2: um script Python de ~90 linhas, só stdlib. Busca os feeds e troca o miolo entre os marcadores:

import json
import re
import urllib.request

def fetch(url):
    req = urllib.request.Request(url, headers={"User-Agent": "profile-readme"})
    with urllib.request.urlopen(req, timeout=30) as res:
        return res.read().decode("utf-8")

def replace_section(text, name, lines):
    block = "\n\n".join(lines)
    pattern = re.compile(
        rf"(<!-- {name} starts -->).*?(<!-- {name} ends -->)", re.S
    )
    if not pattern.search(text):
        raise RuntimeError(f"marcadores de '{name}' não encontrados")
    return pattern.sub(lambda m: f"{m.group(1)}\n{block}\n{m.group(2)}", text)

Guarde o detalhe do lambda na última linha. Ele volta já já, na armadilha 3.

Peça 3: um workflow do Actions rodando 1x por dia. Se não houver diferença no README, ele nem commita:

on:
  schedule:
    - cron: "0 9 * * *"
  workflow_dispatch:
permissions:
  contents: write

Um cuidado: se você também disparar no push, restrinja o paths ao script e ao workflow. Incluir o README.md no gatilho cria a receita clássica de loop infinito — o commit do bot dispara o próximo run, que commita de novo.

As 3 armadilhas que ninguém documenta

Armadilha 1: o GitHub apaga praticamente todo CSS. Tag <style>, atributo style, tudo sanitizado. Sobrevivem align, width/height de <img>, <table> e… imagens. Ou seja: se quiser cor, fonte e identidade visual, o único caminho é assar tudo num PNG e colar como header. É também por isso que os perfis do estilo 4 vivem de SVG externo — widget é o jeito de decorar num mundo sem CSS.

Armadilha 2: o botão “Share to profile”. Criei o repositório privado, montei tudo com calma e virei público no final. O README não apareceu no perfil. Fucei as configurações por meia hora achando que era cache — era um botão no canto do repositório, “Share to profile”, que só aparece nesse fluxo. Quem cria o repositório já público nunca vê essa armadilha; quem prepara em privado, cai.

Armadilha 3: o título alheio que quebra seu regex. A versão ingênua da substituição é assim:

# ❌ bomba-relógio
return pattern.sub(rf"\1\n{block}\n\2", text)

No re.sub, a string de substituição interpreta \1 como backreference. E o block carrega títulos vindos de feed externo. No dia em que alguém publicar um artigo com \1 no título — e quem escreve sobre regex publica — seu workflow quebra às 6 da manhã. A correção é dupla: lambda na substituição (o retorno não é interpretado como pattern) e escape nos títulos:

def md_escape(title):
    title = " ".join(title.split())
    for ch in "\\[]<>":
        title = title.replace(ch, "\\" + ch)
    return title

Parece paranoia até você perceber o que esse pipeline é: texto de terceiros entrando direto na sua página de perfil. ] quebra link em Markdown, < vira HTML. Trate como entrada não confiável, porque é.

Decoração apodrece. Feed, não.

Entrei nessa querendo decorar um README e saí com um pipeline. O resumo dos 10 perfis dissecados: o que separa um perfil bom de um perfil enfeitado é o encaixe entre o seu ativo real e o estilo escolhido. Enfeite sem lastro envelhece mal; número honesto e atividade recente envelhecem bem.

Meu perfil (github.com/kenimo49) agora se reescreve toda manhã. No dia seguinte à configuração, os artigos novos já estavam lá sem eu tocar em nada — sensação de regador automático funcionando no quintal. Se o seu terreno nobre está vazio: abra os 10 perfis lá de cima, veja qual ativo você já tem, e escolha o estilo que o valoriza. A decoração vem depois. Se vier.

ken imoto · AI Agent engineer · kenimoto.dev · TabNews