FlorianBruniaux/guia-ultimate-claude-code

Resumo do Guia

Gere conteúdo para redes sociais a partir de entradas do CHANGELOG.md. Produz 8 saídas por padrão (4 formatos x 2 idiomas).

Quando Usar

• Após executar /release para criar anúncios sociais
• Semanalmente para resumir múltiplos lançamentos
• Antes de postar no LinkedIn, Twitter/X, newsletter ou Slack

Uso

/guide-recap latest              # Última versão lançada
/guide-recap v3.20.5             # Versão específica
/guide-recap week                # Semana atual (segunda até hoje)
/guide-recap week 2026-01-27     # Semana específica (segunda a domingo)

Flags

Flag	Efeito	Padrão
--interactive	Modo guiado: escolha ângulo, público, destaque	Desligado (rascunho automático)
--format=X	Formato único: linkedin, twitter, newsletter, slack	Todos os 4 formatos
--lang=X	Idioma único: fr, en	Ambos FR + EN
--save	Salvar saída em claudedocs/social-posts/	Apenas exibir
--force	Gerar mesmo que apenas entradas de manutenção	Pular pontuação baixa

Fluxo de Trabalho (7 Etapas)

Etapa 1: Analisar Entrada

Analisar $ARGUMENTS para determinar o modo:

Entrada	Modo	Alvo
latest	Versão única	Primeiro ## [X.Y.Z] após [Unreleased]
vX.Y.Z ou X.Y.Z	Versão única	Correspondência exata de versão
week	Intervalo de semana	Segunda da semana atual -> hoje
week YYYY-MM-DD	Intervalo de semana	Aquela segunda -> próximo domingo

Se nenhum argumento ou argumento inválido, exibir uso e sair.

Etapa 2: Extrair Entradas do CHANGELOG

Ler CHANGELOG.md da raiz do projeto.

Versão única:

1. Encontrar linha correspondente a ## [{version}]
2. Extrair todo o conteúdo até a próxima linha ## [
3. Analisar seções ### Added, ### Changed, ### Fixed

Intervalo de semana:

1. Coletar todas as entradas ## [X.Y.Z] - YYYY-MM-DD cuja data esteja no intervalo
2. Analisar todas as seções de todas as versões correspondentes

Erro: versão não encontrada -> Listar últimas 5 versões, sugerir latest. Erro: semana sem entradas -> Mostrar data do último lançamento, sugerir essa versão.

Etapa 3: Categorizar Entradas

Para cada entrada de nível superior (primeiro marcador abaixo de ###), atribuir uma categoria:

Categoria	Peso	Detecção
NEW_CONTENT	3	Novos arquivos, novas seções, novos diagramas, novas perguntas de quiz
GROWTH_METRIC	2	Crescimento de linhas, mudanças na contagem de itens
RESEARCH	1	Avaliações de recursos, integrações de fontes externas
FIX	1	Sob ### Fixed, correções
MAINTENANCE	0	Atualizações de README, sincronização de badges, sincronização de landing, atualizações de contagem

Consulte references/changelog-parsing-rules.md para regras detalhadas de classificação.

Etapa 4: Transformar em Valor para o Usuário

Aplicar mapeamentos de references/content-transformation.md:

• Linguagem técnica -> benefício para o usuário
• Extrair números concretos
• Creditar fontes nomeadas
• Agrupar entradas relacionadas

Validar contra a lista de FAÇA/NÃO FAÇA em references/tone-guidelines.md.

Etapa 4b: Modo Interativo (apenas --interactive)

Se a flag --interactive estiver definida, inserir entre as etapas 4 e 5:

1. Exibir destaques candidatos com pontuação:

   Destaques (por pontuação):
   [14] 4 novos diagramas ASCII (16 -> 20)     [NEW_CONTENT]
   [ 9] 30 novas perguntas de quiz (227 -> 257) [NEW_CONTENT]
   [ 6] Guia de isolamento Docker sandbox        [NEW_CONTENT]
   [ 1] README atualizado                        [MAINTENANCE]
   

2. Perguntar ângulo:

   • Automático (maior pontuação = gancho)
   • Usuário escolhe entrada específica como gancho
   • Ângulo personalizado (usuário fornece tema)

3. Perguntar público-alvo:

   • devs (profundidade técnica)
   • tech-leads (foco em impacto)
   • general (linguagem acessível)
   • all (padrão, equilibrado)

4. Perguntar destaque principal:

   • Automático (maior pontuação)
   • Usuário seleciona da lista

5. Confirmar seleção e prosseguir para a etapa 5.

Etapa 5: Pontuar e Selecionar

Calcular pontuação para cada entrada:

score = (peso_da_categoria * 3)
      + (tem_numero * 2)
      + (fonte_nomeada * 1)
      + (novo_arquivo * 1)
      + (min(impacto_arquivos, 3))
      + (alteracao_significativa * 2)

Selecionar as 3-4 entradas com maior pontuação. A maior pontuação = linha de gancho.

Se todas as pontuações < 3: Exibir "Nenhum conteúdo social recomendado para esta versão. Use --force para gerar mesmo assim." e sair (a menos que --force).

Etapa 6: Gerar Conteúdo

Para cada formato solicitado (padrão: todos os 4) e idioma (padrão: ambos):

1. Ler o template correspondente de assets/
2. Preencher os campos do template usando as entradas pontuadas e transformadas
3. Aplicar a lista de verificação de qualidade de tone-guidelines.md

Links:

Formato	Link Alvo
LinkedIn	URL do site de landing
Twitter	URL do repositório GitHub
Newsletter	Ambos (landing + GitHub)
Slack	URL do repositório GitHub

URLs:

• Landing: https://florianbruniaux.github.io/Codex-ultimate-guide-landing/
• GitHub: https://github.com/FlorianBruniaux/Codex-ultimate-guide

Etapa 7: Saída

Exibir cada post gerado em um bloco de código com cerca, rotulado por formato e idioma:

## LinkedIn (FR)

```text
[conteúdo]

LinkedIn (EN)

[conteúdo]

Twitter/X (FR)

[conteúdo]

…

Se a flag `--save`: escrever todas as saídas em `claudedocs/social-posts/YYYY-MM-DD-vX.Y.Z.md` (para versão) ou `claudedocs/social-posts/YYYY-MM-DD-week.md` (para semana). Criar diretório `claudedocs/social-posts/` se não existir.

## Tratamento de Erros

| Erro | Resposta |
|------|----------|
| Nenhum argumento | Exibir bloco de uso |
| Argumento inválido | Exibir bloco de uso com exemplos |
| Versão não encontrada | Listar 5 versões mais recentes, sugerir `latest` |
| Semana sem entradas | Mostrar data do último lançamento, sugerir versão |
| Todas as entradas MAINTENANCE (pontuação 0) | "Nenhum conteúdo social recomendado. Use `--force` para sobrescrever." |
| CHANGELOG.md não encontrado | "CHANGELOG.md não encontrado na raiz do projeto." |

## Arquivos de Referência

- `references/tone-guidelines.md` — Regras de FAÇA/NÃO FAÇA, orçamento de emojis, registro de linguagem
- `references/changelog-parsing-rules.md` — Formato do CHANGELOG, extração, algoritmo de pontuação
- `references/content-transformation.md` — Mapeamentos técnico -> valor para o usuário (30+)
- `assets/linkedin-template.md` — ~1300 caracteres, gancho + marcadores + CTA + hashtags
- `assets/twitter-template.md` — 280 caracteres único ou thread de 2-3 tweets
- `assets/newsletter-template.md` — ~500 palavras, seções estruturadas
- `assets/slack-template.md` — Compacto, rico em emojis, formatação Slack
- `examples/version-output.md` — Exemplo completo de saída para v3.20.5
- `examples/week-output.md` — Exemplo completo de saída para semana 2026-01-27

## Dicas

- Execute `/guide-recap latest` logo após `/release` para preparar posts sociais
- Use `--interactive` nas primeiras vezes para entender a pontuação
- Use `--format=linkedin --lang=fr` quando precisar apenas de uma saída específica
- As saídas de `--save` são ignoradas pelo git via convenção de `claudedocs/`
- Revise e personalize antes de postar (estes são rascunhos, não cópia final)