seo-playbook

SEO Playbook

Esta habilidade transforma SEO em um fluxo de trabalho de engenharia repetível: encontrar consultas que o site pode realmente vencer, dar a cada página um trabalho claro, colocar as palavras certas nos elementos HTML corretos, garantir que o Google possa rastrear, renderizar e indexar o resultado, capturar links e, em seguida, medir e iterar.

Ela destila o que funcionou (e o que quebrou silenciosamente) enquanto levava um jovem site de ferramentas Next.js do zero a classificações de primeira página para consultas de cauda longa. As lições se generalizam para qualquer pilha.

A mentalidade, em cinco frases

1. Classificações seguem a vencibilidade, não desejos. Um domínio jovem não alcançará o top 5 para um termo cabeça como "gerador de código qr" este ano; ele pode ranquear em semanas para "gerador de código qr gratuito sem cadastro" ou "link de desejo de aniversário com nome”. Mire primeiro na cauda longa e deixe a autoridade temática elevar o termo cabeça depois.
2. Uma página, uma intenção de busca, uma palavra-chave principal. Duas páginas mirando a mesma consulta dividem sinais (canibalização); uma página mirando duas intenções não atende a nenhuma.
3. O Google ranqueia o HTML que recebe, não o aplicativo que o usuário vê. Se o conteúdo, H1, respostas de FAQ ou links só aparecem após a execução do JavaScript, assuma que eles não existem. Verifique a resposta bruta do servidor todas as vezes.
4. Bugs de indexabilidade superam a redação. Um soft 404, uma canônico perdido ou um noindex herdado de um layout podem apagar meses de trabalho de conteúdo sem qualquer erro. Verifique códigos de status, canônicos e robots em cada tipo de página que você tocar.
5. Meça com o Search Console, não com a intuição. Impressões nas posições 8–20 são os ganhos mais baratos; posição 50+ significa um problema de autoridade ou intenção que mais ajustes on-page não resolverão.

Defina as expectativas do usuário honestamente: primeiras impressões para páginas de cauda longa geralmente aparecem em 2–6 semanas; termos cabeça levam meses e backlinks. SEO "rápido" significa escolher lutas que o site pode vencer.

Escolha a profundidade primeiro

A maioria das solicitações de SEO é pequena. Escolha o modo antes de fazer qualquer coisa, pois o fluxo de trabalho completo custa várias vezes mais tempo e tokens do que uma pequena mudança precisa.

Modo Rápido é para edições em uma ou duas páginas onde a palavra-chave é conhecida ou óbvia: retitular uma página, escrever uma meta descrição, adicionar FAQs, corrigir um problema sinalizado ou adicionar uma página a um projeto que já possui um padrão de SEO para copiar. No modo rápido:

• Não leia os arquivos de referência e não pesquise a SERP ao vivo, a menos que uma verificação abaixo falhe ou você genuinamente não consiga decidir.
• Siga o padrão de SEO existente do projeto: seu auxiliar de metadados, configuração de conteúdo e componentes de esquema.
• Faça a alteração e execute a lista de verificação rápida abaixo no resultado. Se houver HTML construído ou servido, execute scripts/seo_check.py uma vez nele.
• Relate em algumas linhas. Mencione qualquer coisa maior que você notou como uma linha "Também vale a pena fazer", sem investigá-la.

Lista de verificação rápida (apenas a página sob alteração):

1. O título é único, começa com a palavra-chave, ≤ 60 caracteres. A descrição tem 120–160 caracteres e faz apenas afirmações verdadeiras.
2. Exatamente um H1, e a cópia principal, o H1 e as respostas de FAQ estão no HTML do servidor (não apenas no cliente, não opacity:0, não desmontados).
3. A página define seu próprio canônico, é indexável e está no sitemap. Páginas ocultas usam noindex e não são desabilitadas no robots.txt.
4. 3–5 links internos saindo e pelo menos um link entrando.
5. Dados estruturados correspondem ao conteúdo visível, sem classificações que não sejam do próprio site.

Modo Completo é o fluxo de trabalho abaixo. Use-o para:

• um novo site, conjunto de páginas ou cluster
• escolher palavras-chave quando o alvo certo não está claro
• diagnosticar "por que isso não está ranqueando" ou "o tráfego está estagnado"
• uma auditoria pré-lançamento ou em todo o site
• um plano off-page

Uma verificação rápida pode revelar um problema em todo o site, como um canônico herdado, um padrão de soft-404 ou classificações fabricadas. Não expanda o trabalho silenciosamente: termine a alteração solicitada, coloque o problema no topo do seu relatório com uma linha sobre por que é importante e ofereça a análise completa. O usuário decide se quer gastar nisso. A exceção é quando a alteração solicitada não pode funcionar sem a correção, por exemplo, quando a página que você está editando não tem um H1 renderizado no servidor. Nesse caso, corrija o mínimo necessário e informe.

Fluxo de trabalho (modo completo)

Execute as fases em ordem para um novo site ou conjunto de páginas. Para uma alteração em uma única página, faça no mínimo as fases 3, 4 e 6. Leia o arquivo de referência vinculado quando você alcançar uma fase — cada um contém a lista de verificação detalhada e os modelos.

Dimensione o trabalho para a solicitação. Uma revisão de página é uma revisão de página; um mapa de palavras-chave é um mapa de palavras-chave. Faça o trabalho solicitado minuciosamente e coloque oportunidades adjacentes (palavras-chave, ideias off-page) em uma lista curta "Também vale a pena fazer" em vez de produzir planos extras completos que ninguém pediu. Entregas extras diluem aquela que o usuário precisa e custam tempo.

Verifique antes de afirmar. Verifique fatos que você pode verificar (a SERP ao vivo, se o nome da marca já está ocupado, o que uma página realmente contém, o que um recurso realmente faz). Quando você não puder verificar algo — uma página que você só conhece pela URL, um site que não carrega, um recurso que você não viu — diga que é uma suposição e diga ao usuário o que confirmar. Suposições confiantes sobre o site de outra pessoa são a maneira mais comum de o conselho de SEO dar errado.

Os scripts são para você. Execute scripts/*.py você mesmo. Nas instruções escritas para o usuário, descreva a verificação em termos simples ou dê um comando que eles possam executar sem esta habilidade (curl, etapas do Search Console). Faça referência aos caminhos dos scripts da habilidade apenas quando você souber que o usuário tem a habilidade instalada.

Fase 1 — Reconhecimento (antes de mudar qualquer coisa)

• Identifique a pilha e como as páginas são renderizadas (SSR, SSG, SPA, híbrido). Para armadilhas de frameworks, leia a seção relevante de references/technical-seo.md (Next.js App Router tem sua própria seção).
• Faça um inventário do que existe: como os metadados são definidos, onde a cópia da página vive, geração de sitemap e robots, componentes de dados estruturados, análises. Reutilize padrões existentes em vez de adicionar outros paralelos.
• Busque uma página representativa de cada tipo como Googlebot e registre a linha de base: python3 <skill-dir>/scripts/seo_check.py <url> [<url> ...] Ele relata status, comprimentos de título/descrição, canônico, robots meta e X-Robots-Tag, contagem de H1, contagem de palavras visíveis, tipos JSON-LD, imagem OG e bandeiras vermelhas como um elemento principal "Carregando…".
• Se os dados do Search Console estiverem disponíveis (uma exportação, um auxiliar de API ou a habilidade seo-google se instalada), extraia 90 dias de linhas de consulta+página e execute scripts/gsc_opportunities.py (veja a Fase 6). Impressões existentes dizem o que o Google já associa ao site.
• Procure por documentos de SEO do projeto ou notas de memória de auditorias anteriores e construa sobre eles.

Fase 2 — Pesquisa de palavras-chave e o mapa de palavras-chave

Leia references/keyword-research.md. Em resumo:

1. Semeie a partir do produto: o que a página faz, quem a usa, as palavras que os usuários digitam quando querem exatamente isso.
2. Expanda com sinais gratuitos: autocomplete do Google e "As pessoas também perguntam", pesquisas relacionadas, títulos de concorrentes, consultas do GSC, frases do Reddit/Quora. Use APIs pagas apenas se o projeto as tiver (por exemplo, as habilidades seo-dataforseo ou seo-ahrefs, se instaladas).
3. Classifique a intenção (fazer / saber / ir / comprar) e olhe a SERP ao vivo para cada candidato. Se a primeira página for toda de grandes marcas ou de um tipo de página diferente (por exemplo, listicles quando você tem uma ferramenta), a palavra-chave ainda não é vencível para esta página.
4. Pontue a vencibilidade: concorrentes fracos (páginas indie finas, fóruns, repositórios GitHub, sites *.vercel.app) na primeira página é o sinal mais forte.
5. Verifique o nome da marca: pesquise-o simples, mais npm/PyPI/GitHub/app stores onde relevante. Se estiver ocupado, recomende usar o formulário de domínio ("Marca.app") consistentemente.
6. Produza um mapa de palavras-chave: uma linha por URL com palavra-chave principal, 3–8 termos secundários/de cauda longa, intenção e onde cada termo vai (título, H1, H2, introdução, FAQ). Nenhuma palavra-chave principal aparece em duas linhas, e toda linha em cada tabela tem uma intenção.

Volumes sem uma ferramenta paga são faixas direcionais (muito alto / alto / médio / baixo). Diga isso em sua saída em vez de inventar números.

Fase 3 — Implementação on-page

Leia references/on-page.md para a lista de verificação completa e o modelo de conteúdo da página. O essencial para cada página indexável:

• Título: único, palavra-chave principal primeiro, idealmente ≤ 60 caracteres incluindo qualquer sufixo de marca, e escrito para vencer o clique.
• Meta descrição: única, 120–160 caracteres, afirma o que o usuário obtém e o diferencial ("gratuito, sem cadastro, executa no seu navegador") apenas quando for verdade.
• Exatamente um H1 no HTML do servidor, correspondendo à intenção principal da página (uma variante próxima do título, não uma cópia).
• Corpo: responda à consulta no primeiro parágrafo, depois adicione profundidade que uma página concorrente não tem: etapas de como fazer, exemplos práticos, problemas comuns com correções, limitações, FAQs. Cada seção existe porque um pesquisador precisa dela, não para atingir uma contagem de palavras.
• FAQs visíveis no HTML (não apenas em acordeões recolhidos e desmontados e não apenas em JSON-LD), formulados como consultas reais.
• Links internos: 3–5 links contextuais para páginas relacionadas e pelo menos um link para a página a partir de um hub ou artigo relevante. Nenhuma página órfã.
• Dados estruturados que correspondem ao conteúdo visível: veja references/structured-data.md para quais tipos ainda ganham resultados avançados.
• Confiança: autor ou organização real, afirmações precisas, data da última revisão que muda quando o conteúdo muda, fontes para números. Nunca publique avaliações ou depoimentos de placeholders — o Google os trata como deturpação.

Armazene o conteúdo SEO da página como dados (um objeto de configuração tipado ou campos de CMS) em vez de espalhar strings pelo JSX. Isso torna possíveis verificações de exclusividade, testes de comprimento e revisões em massa.

Fase 4 — Barreiras técnicas (não pule)

Leia references/technical-seo.md. Antes de considerar qualquer página pronta, confirme no HTML construído ou implantado:

• Status 200 para páginas reais e um 404 real (não um 200 com texto "não encontrado") para URLs desconhecidos.
• Canônico absoluto auto-referenciado e nenhum canônico/robots herdado por acidente de um layout pai.
• Páginas indexáveis estão no sitemap com um lastmod honesto; páginas noindex não estão.
• Páginas que você deseja ocultar usam noindex (meta ou X-Robots-Tag) e não estão bloqueadas no robots.txt, caso contrário, o Google nunca pode ler o noindex.
• Conteúdo principal, H1, respostas de FAQ e links internos estão presentes no HTML bruto (verificação de contagem de palavras e H1 do seo_check.py).
• Um host preferido (https, www ou apex) com redirecionamentos 301 de salto único dos outros.
• Core Web Vitals não regrediram (LCP ≤ 2,5 s, INP ≤ 200 ms, CLS ≤ 0,1). Para dados de campo, use PageSpeed Insights / CrUX ou as habilidades seo-performance / seo-google se instaladas.

Fase 5 — Off-page e distribuição

Leia references/off-page.md. O trabalho on-page torna uma página elegível; links e demanda de marca decidem o quão alto ela vai para qualquer coisa competitiva. Planeje a captação de links junto com a página, não depois:

• Construa um ativo vinculável por cluster (ferramenta gratuita, repositório de modelo, tabela de dados, guia original).
• Envie para os poucos diretórios e plataformas de lançamento que se adequam ao público, escritos como postagens genuínas.
• Use plataformas visuais (Pinterest, YouTube Shorts) para nichos visuais; GitHub para públicos de desenvolvedores.
• Configure o Bing Webmaster Tools e o IndexNow (o feed de índice do Bing alimenta a pesquisa do ChatGPT e o Copilot).
• Nunca compre links, participe de esquemas de links ou envie em massa para diretórios de lixo.

Quando você não puder fazer o trabalho off-page sozinho, produza um kit pronto para execução para o usuário: lista de alvos, rascunhos de postagens, rascunhos de e-mails de divulgação e um calendário.

Fase 6 — Verificar, lançar, monitorar

Leia references/measurement.md.

• Execute novamente seo_check.py contra as páginas construídas ou implantadas e diferencie da linha de base da Fase 1. Para alterações em layouts ou componentes compartilhados, diferencie cada tipo de página, não apenas a que você editou — uma alteração em todo o site pode alterar silenciosamente páginas que já estão ranqueando.
• Após a implantação: reenvie o sitemap, solicite indexação apenas para o punhado de novas URLs mais importantes, envie um ping para o IndexNow.
• Após 2–4 semanas: execute python3 <skill-dir>/scripts/gsc_opportunities.py <gsc-export.json|csv> para listar consultas de distância impressionante, páginas com baixo CTR e canibalização, depois itere em títulos, seções e links internos para esses.

Regras duramente conquistadas

Estas vieram de regressões reais. Cada uma custou classificações ou indexação antes de ser encontrada.

• Verifique o que os rastreadores realmente recebem. Um spinner de carregamento em nível de rota, importações dinâmicas ssr: false ou um fade-in que começa em opacity: 0 podem deixar o HTML do servidor com apenas "Carregando…" enquanto o navegador parece perfeito. Rastreadores de IA não executam JavaScript.
• Animações de entrada escondem o herói. Bibliotecas de animação (framer-motion initial={{ opacity: 0 }}, AOS, GSAP) renderizam no servidor seu estado inicial, então o H1 e a introdução são enviados invisíveis até a hidratação, atrasando o LCP. Use initial={false} ou animação apenas com CSS para qualquer coisa acima da dobra; grep o HTML construído em busca de opacity:0.
• Corpos de CMS adicionam um segundo H1. Markdown que começa com # Título sob um H1 em nível de página o duplica. Rebaixe H1s do corpo para H2 no renderizador.
• Soft 404s de SSR de streaming. Depois que uma resposta transmitida começou, um notFound() posterior não pode alterar o 200. Rejeite slugs desconhecidos antes da renderização (parâmetros estáticos com parâmetros dinâmicos desabilitados) ou retorne um noindex explícito do branch de falta de metadados.
• Canônicos herdados. Um canônico em um layout raiz vaza para toda página que não define o seu próprio. Um soft 404 que o herda torna-se uma duplicata indexável de uma página real.
• "API fora do ar" não é "sem resultados". O código que decide notFound() ou noindex deve distinguir uma busca falha de um resultado vazio, ou uma interrupção desindexa páginas reais.
• Conteúdo oculto. Acordeões que desmontam painéis fechados removem respostas de FAQ do HTML. Mantenha-os montados (hidden="until-found" ou CSS) para que possam ser rastreados e encontrados pela pesquisa na página.
• Componentes compartilhados são um raio de explosão. Quando uma página ranqueia bem, altere componentes de SEO compartilhados por trás de props opt-in e diferencie o HTML construído das outras páginas antes e depois.
• Classificações e depoimentos fabricados. O Google trata conteúdo gerado por IA não revisado, depoimentos falsos e avaliações sintéticas como deturpação. Se você não pode provar que é real, não o publique.
• Imagens compartilhadas carecem de SEO. Imagens em pastas públicas (não otimizadas, sem dimensões, alt text ausente) são o débito técnico mais comum. Todas as imagens indexáveis precisam de alt text descritivo, dimensões definidas e nomes de arquivo com palavras-chave.
• O Google descobre URLs, não os inventa. Sitemaps, links internos e links externos são os três caminhos para a descoberta. Se uma URL não está em nenhum deles, ela não existe para o Google.

Ferramentas de scripts

Estes scripts ajudam a automatizar verificações. O é o caminho da pasta da habilidade:

• scripts/seo_check.py – verificação única de uma página: status, comprimentos de título/descrição, canônico, robots, H1, contagem de palavras, JSON-LD e bandeiras vermelhas. Passe uma ou mais URLs.
• scripts/gsc_opportunities.py – leia uma exportação do GSC e produza consultas de distância impressionante, páginas com baixo CTR e canibalização.

Execute-os você mesmo; eles economizam idas e vindas.

---

O fluxo de trabalho completo usa vários arquivos de referência no diretório references/. Essa estrutura mantém cada fase detalhada sem sobrecarregar este playbook. Consulte cada referência quando você alcançar sua fase.

Resumo do workflow em uma imagem: Reconhecimento → Pesquisa de palavras-chave e mapa → Implementação on-page → Verificações técnicas → Off-page e distribuição → Verificar / lançar / monitorar.