Mapeamento de Palavras-chave e Perguntas de Expansão (Keyword F…

Mapeamento de Palavras-chave e Perguntas de Expansão (Keyword & Fan-Out Map)

Etapa 1 de 5. Produz o mapa de palavras-chave que todas as habilidades posteriores leem, para que nada precise ser repetido.

Antes de começar

Obrigatório: o conector DataForSEO. Sem ele não há volumes de pesquisa reais e esta habilidade estaria adivinhando, o que é pior que inútil porque os palpites parecem dados.

Verifique se existe uma ferramenta DataForSEO. Se não houver, pare e diga:

Esta habilidade precisa de dados de pesquisa reais. Conecte o DataForSEO primeiro: Personalizar → Conectores → Adicionar conector personalizado → https://mcp.dataforseo.com/mcp → Conectar → aprovar. Leva cerca de um minuto, depois execute novamente.

Leia também site-brief.md do Projeto. Extraia dele SEARCH_COUNTRY, SEARCH_LANGUAGE, a área de atendimento, a lista de serviços e os concorrentes. Se estiver faltando, informe e ofereça executar site-brief-builder primeiro. Você pode prosseguir sem ele, mas deve então perguntar explicitamente o país e o idioma e avisar que os volumes só estão corretos para os valores fornecidos.

Entrada

Uma palavra-chave semente, ou um tipo de negócio mais localização, ou apenas um tópico. Se o usuário não fornecer nada, proponha três sementes a partir da lista de serviços no resumo.

Processo

Etapa 1: Expandir

Use o conector DataForSEO. Os endpoints que você deseja, por caminho da API:

• dataforseo_labs/google/keyword_ideas, a expansão principal
• dataforseo_labs/google/related_keywords, vizinhos semânticos
• keywords_data/google_ads/search_volume, volume, CPC, concorrência
• ai_optimization/ai_keyword_data/keyword_data, volume de pesquisa IA, significando com que frequência as pessoas inserem isso em um LLM em vez de uma caixa de pesquisa
• serp/google/organic, quem classifica atualmente (opcional, mas melhora o relatório)

Os nomes das ferramentas no conector mapeiam esses caminhos. Escolha a ferramenta correspondente pela sua descrição, em vez de assumir um nome exato.

Sempre passe a localização e o idioma do resumo. Nunca use como padrão os Estados Unidos porque é conveniente.

Etapa 2: Filtrar e agrupar

Descarte: palavras-chave com volume zero e volume IA zero, erros ortográficos óbvios e termos de marca pertencentes a concorrentes.

Agrupe o que restou em clusters de tópicos. Marque cada palavra-chave com uma intenção:

• informational, quer entender ("o que é", "como funciona")
• commercial, comparando antes de comprar ("melhor", "vs", "avaliação")
• transactional, pronto para agir ("perto de mim", "reservar", "comprar", "preço")
• navigational, procurando uma marca específica

Em seguida, atribua a cada palavra-chave um papel:

• primary, exatamente um. O assunto do H1.
• secondary, merece seu próprio H2.
• support, use naturalmente no corpo do texto.
• skip, tópico certo, intenção errada para esta página. Mantenha-o visível para que o usuário veja que foi considerado e rejeitado, em vez de perdido.

Escolha a primária pela correspondência de intenção, não apenas pelo volume. Uma palavra-chave informacional de 2.400/mês é a primária errada para uma página de serviço, e escolhê-la é o erro mais comum em pesquisa de palavras-chave.

Etapa 3: Perguntas de expansão

Obtenha as consultas de acompanhamento nas quais os mecanismos de IA expandem este tópico:

• ai_optimization/llm_mentions para as consultas de expansão associadas ao tópico
• o bloco "As pessoas também perguntam" do endpoint SERP
• dataforseo_labs/google/related_keywords resultados em formato de pergunta

Mantenha aquelas que uma única página pode realmente responder. Cada uma se torna um H2 com uma resposta de duas frases diretamente abaixo. Descarte qualquer coisa que pertença a uma página diferente e informe isso.

Saída

Escreva dois arquivos.

01-keyword-map.csv, colunas exatamente: cluster,keyword,intent,role,search_volume,ai_search_volume,competition,cpc Ordene por papel (primary, secondary, support, skip) e depois volume decrescente. Este é o arquivo que seo-content-writer lê, então os nomes das colunas importam.

01-keyword-map.html, preencha templates/keyword-map.html.template.

Construa um data.json e renderize:

python3 scripts/render.py templates/keyword-map.html.template data.json 01-keyword-map.html

Formato do data.json:

{
  "tokens": { "SUBJECT": "...", "KW_TOTAL": 42, "...": "..." },
  "rows": {
    "KEYWORD_ROW": [{ "ROW_CLUSTER": "...", "ROW_KEYWORD": "...", "...": "..." }],
    "FANOUT_ROW": [{ "ROW_QUESTION": "...", "ROW_QUESTION_NOTE": "..." }],
    "SERP_ROW": [{ "ROW_POSITION": 1, "ROW_DOMAIN": "...", "...": "..." }]
  }
}

Notas sobre os tokens:

• ROW_INTENT_CLASS deve ser um de info, comm, trans, nav.
• Se você pulou a verificação SERP, defina SERP_TABLE_DISPLAY como none e SERP_EMPTY_DISPLAY como block. Caso contrário, block e none.
• DATA_WINDOW é a janela de volume, normalmente "média de 12 meses".
• DATA_NOTES deve informar a localização e o idioma usados. É assim que o usuário detecta uma execução no mercado errado.

Não reformate o modelo. Não adicione fontes, cores ou gráficos.

Regras de honestidade

• Nunca escreva um volume que você não obteve da API. Se uma palavra-chave não retornou volume, mostre "sem dados", não 0 e nem uma estimativa.
• O volume de pesquisa IA é mais recente e mais limitado que o volume do Google. Onde estiver faltando, informe que está faltando, em vez de implicar que a demanda é zero.
• Se a contagem total de palavras-chave for pequena porque o nicho é pequeno, diga isso. Um mapa curto e honesto é melhor que um inflado.

Entregando

Termine informando ao usuário:

Próximo passo: execute seo-content-writer. Ele lê 01-keyword-map.csv sozinho, então você não precisará repetir a palavra-chave. Ele fará três perguntas, e uma delas só você pode responder.