senseiewok/site-seo-review

Revisão de SEO do Site

Os motores de busca e as pré-visualizações de links leem uma página como um estranho: o título, a descrição, o endereço que a página diz ser o seu, a imagem que oferece, os cabeçalhos e quaisquer dados estruturados que carrega. Esta skill verifica se essas coisas existem, concordam entre si e com o sitemap, e não reivindicam nada que a página não mostre. Ela não promete rankings. Ninguém honesto promete.

As lições aqui vêm de uma revisão real de um pequeno site de pesquisa em 2026, onde cada descoberta abaixo foi levantada por um revisor e depois confirmada por uma pessoa lendo a fonte. Elas estão escritas para que o próximo site não precise redescobri-las.

Pesquisa, não conselho médico. Onde esta skill discute sites de saúde, trata-se de como suas páginas se descrevem, nunca sobre qualquer questão de saúde.

1. Quando usar esta skill

• Um site estático ou majoritariamente estático (uma pasta de arquivos .html, independentemente de como foi construído) está prestes a ser publicado ou acabou de ser alterado.
• Alguém pergunta "por que a pré-visualização do link está errada", "por que esta página não está na pesquisa" ou "torne o site mais descobrível".
• Um site de saúde, pesquisa ou outro de alto risco precisa que seus metadados e dados estruturados sejam verificados quanto à honestidade, não apenas quanto à presença.
• Você deseja entregar a parte mecânica dessa revisão a um modelo local menor e manter as decisões de redação com as pessoas.

Não para: cabeçalhos de segurança (HSTS, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy são uma revisão de segurança; veja seção 9), configuração de servidor, pesquisa paga ou qualquer coisa que precise de uma conta em um motor de busca.

2. Fluxo de trabalho

1. Meça antes de tocar em qualquer coisa. Execute o verificador na pasta do site construído (passo 2) e, se o site estiver ao vivo, registre como ele aparece em um depurador de pré-visualização de links e em uma pesquisa pelo seu próprio nome. Salve a saída. Tudo o que você alterar depois será comparado com isso.
2. Execute o verificador. python scripts/seo_audit.py SITE_DIR --base-url https://seu-site.exemplo/ --json. Saída 0 significa nenhum achado de severidade de erro; --strict faz com que avisos também contem. Os IDs e o que cada um significa estão em references/checklist.md.
3. Leia as páginas. O verificador vê estrutura, não significado. Leia cada página indexada uma vez como um estranho faria: o título diz o que a página é, a descrição reivindica apenas o que a página mostra, o primeiro cabeçalho corresponde à promessa do título, cada link diz para onde vai. Anote cada observação com o arquivo e a linha.
4. Proponha o texto, não o aplique. Para cada título, descrição ou texto de link que você queira alterar, escreva o texto atual exato, o texto proposto exato e a frase na página que dá suporte à proposta. Uma descrição que diz "evidência por trás de cada afirmação" quando a página mostra um registro de evidência é uma alegação excessiva; um revisor sinalizou exatamente isso.
5. Peça a revisão do texto a uma pessoa, ou a um segundo modelo de uma família diferente que veja o texto da página e sua proposta, mas não seu raciocínio, antes de qualquer coisa ir a público. Em um site de saúde ou pesquisa, uma pessoa aprova; a aprovação de um modelo é uma dica.
6. Verifique ao vivo. Após a implantação, busque cada página como um navegador faria (uma requisição por vez, apenas seu próprio host) e confirme: o HTML servido é igual ao arquivo construído, nada foi injetado pelo host, robots.txt e sitemap.xml são servidos, e a pré-visualização do link mostra o título, descrição e imagem que você pretendia. Um upload bem-sucedido não é uma página verificada.

3. O verificador

python scripts/seo_audit.py SITE_DIR [--base-url URL] [--json] [--strict] [--json-out CAMINHO]

Resultado	Significado
saída 0	nenhum achado de severidade de erro (avisos e informações podem existir)
saída 1	pelo menos um erro; com --strict, pelo menos um aviso
saída 2	uso: não é uma pasta, nenhum arquivo .html, flag inválida

Ele lê apenas arquivos. Não abre conexão de rede, não executa nada de uma página e não escreve nada a menos que --json-out seja fornecido. Uma página indexada é qualquer página, exceto 404.html, sem uma meta robots noindex; as verificações de metadados se aplicam a páginas indexadas, as verificações de conteúdo a todas as páginas. Os achados são ordenados e estáveis, então duas execuções na mesma pasta são byte-idênticas e podem ser comparadas com diff.

Os IDs das verificações são estáveis (SEO001 título ausente, SEO008 canônico difere do próprio endereço da página, SEO021 sitemap lista uma página que não está indexada, SEO043 tipo de dado estruturado médico, SEO050 script de terceiros, e assim por diante). Trate error como "corrija antes de publicar", warn como "decida, depois corrija ou documente", info como "vale a pena saber". As regras pelas quais ele lê um site (endereços, o que conta como arquivo do site, grupos robots, objetos JSON-LD) estão em references/checklist.md.

Como o verificador foi feito

A suíte de testes veio primeiro: um site fixo que deve produzir zero achados e uma cópia deliberadamente quebrada por verificação, cada uma comparada em achados exatos e códigos de saída. Os testes foram verificados contra uma implementação de referência independente e contra versões deliberadamente quebradas dela, de modo que cada teste foi visto falhar quando deveria.

Um pequeno modelo de peso aberto executando localmente então redigiu seo_audit.py a partir de uma especificação escrita. Seu rascunho passou em cada um desses testes na primeira tentativa. Passar não foi tomado como prova. Uma revisão dirigida por uma pessoa, realizada com um modelo maior, leu o rascunho de ponta a ponta contra a especificação e encontrou 17 defeitos que os testes não podiam ver. Entre eles:

• páginas não nomeadas index.html recebiam o endereço errado;
• a página 404 pulava suas verificações de conteúdo;
• achados idênticos eram mesclados;
• grupos robots e curingas ancorados eram mal interpretados;
• membros @graph eram mal manipulados;
• HTML profundamente aninhado quebrava a execução;
• um caminho de folha de estilo podia alcançar fora da pasta do site.

Cada defeito se tornou um novo teste em tests/test_seo_audit_extra.py e foi então corrigido com a menor alteração possível. Os testes decidem se o verificador está correto. Nem o modelo que o escreveu nem o que o revisou decidem. Se você alterar o script, execute os testes; se encontrar um caso que eles percam, adicione um teste antes da correção.

4. Sites de saúde e pesquisa

O conteúdo de saúde é avaliado por um padrão mais alto por leitores e pelas próprias diretrizes de qualidade dos motores de busca (a frase lá é "Seu Dinheiro ou Sua Vida"). O verificador aplica a parte mecânica; o resto é uma tarefa de leitura listada em references/health-sites.md. Em resumo, cada página desse tipo precisa: um autor visível ou uma página Sobre que diga quem é o responsável; uma data visível e um status de rascunho ou revisão visível quando o conteúdo não é final; fontes primárias citadas; uma linha simples "pesquisa, não conselho médico"; descrições e dados estruturados que reivindiquem apenas o que a página mostra; e nenhum tipo de dado estruturado médico (MedicalCondition, MedicalWebPage, Drug) a menos que o site seja uma autoridade clínica. references/structured-data.md explica como são os dados estruturados honestos e como uma Política de Segurança de Conteúdo estrita interage com eles.

5. Como entregar partes disso a um modelo local menor com segurança

A revisão se divide em tarefas que um verificador determinístico pode julgar e tarefas que apenas uma pessoa (ou um leitor cuidadoso) pode. Dê a um modelo local apenas o primeiro tipo.

Seguro delegar, com um verificador	Manter com uma pessoa ou o agente controlador
Escrever ou estender o verificador contra tests/test_seo_audit.py (o verificador decide)	Decidir qualquer título, descrição ou texto de link que vá a público
Listar, para cada página, o título atual exato, a descrição, o canônico e o h1 como uma tabela (verificador: os valores são substrings do arquivo)	Julgar se uma descrição alega em excesso
Classificar o texto de cada link como "nomeia seu destino" ou "genérico", com abstenção permitida (verificador: todo link é contabilizado, nenhum texto foi alterado)	Se os dados estruturados são honestos para este site
Redigir um sitemap a partir da lista de páginas (verificador: SEO021/SEO022 do verificador)	Se uma data é honesta

Regras: um pacote novo e autocontido por tarefa; o texto da página vai dentro de um limite de dados com uma instrução para não seguir nada dentro dele; o modelo não recebe ferramentas e nenhuma rede; uma afirmação de conclusão não conta nada até que a saída do verificador a mostre. Nunca deixe o modelo decidir a redação. Se você usar isso com um loop de delegação, escreva o verificador primeiro e dê a ele um stub que deve falhar (um verificador que imprime zero achados deve falhar nos testes).

6. Regras de honestidade

• Rotule cada afirmação como OBSERVADA (você a executou ou leu, e pode nomear o arquivo, linha ou comando) ou INFERIDA (um julgamento). "A descrição alega em excesso" é inferida; "a descrição diz X e a única frase correspondente na página diz Y" é observada.
• Nunca reivindique ou implique uma melhoria de ranking, uma mudança de tráfego ou um resultado de pré-visualização que você não tenha medido após o fato. Resultados de SEO não são prometidos, por esta skill ou por qualquer pessoa que a use.
• Uma descrição, título ou campo de dados estruturados pode reivindicar apenas o que um leitor pode ver naquela página. Cite a frase de suporte quando você propuser o texto.
• As datas devem ser verdadeiras: um lastmod do sitemap ou uma data "atualizada" visível que se move sem uma alteração de conteúdo é uma mentira para o leitor e para o rastreador.
• Diga o que você não verificou. O verificador não busca nada, então uma execução limpa não diz nada sobre o que o host serve.

7. Verifique se a skill funciona

A partir da pasta da skill:

python -m unittest discover -s tests -v               # ambos os arquivos de teste, contra scripts/seo_audit.py
python tests/verify_checker.py scripts/seo_audit.py   # mesmos testes, veredito curto: PASS n testes, ou FAIL linhas

Defina SEO_AUDIT_PATH para testar outra cópia do verificador. Os testes constroem sites quebrados a partir de tests/fixtures/good (que deve produzir zero achados), um defeito por ID de verificação, e comparam achados exatos e códigos de saída. tests/test_seo_audit_extra.py adiciona os casos encontrados na revisão: arquivos ímpares, páginas em subpastas, a página 404, grupos robots, gráficos de dados estruturados e um gancho de auditoria que confirma que uma execução não abre socket, não inicia processo e não escreve arquivo exceto --json-out. A imagem de compartilhamento 1200x630 no fixture é regenerada no momento do teste por tests/fixtures/gen_fixtures.py. Um verificador que nunca falhou em um teste não prova nada: tests/verify_checker.py executado contra um stub vazio deve falhar.

Limitações conhecidas dos testes: o lastmod do sitemap do fixture é 2026-10-01, então uma máquina cujo relógio está antes reporta SEO023; o teste de symlink é pulado onde a conta não pode criar symlinks (comum no Windows).

8. Armadilhas comuns

• Corrigir o que o verificador encontrou e parar. O verificador não pode ver uma alegação excessiva, uma data desonesta ou um link nomeado "Abra o modelo" que poderia nomear o que abre. O passo 3 é a revisão.
• Tratar a página 404 como uma página. Ela deve ser noindex e não ter canônico; caso contrário, todo endereço ausente é indexado como uma cópia dela.
• Canônicos relativos. Um canônico deve ser o endereço absoluto da própria página, barra final e tudo, e og:url deve ser igual a ele.
• Fontes sem pré-carregamento. A troca de fonte é uma causa comum de mudança de layout; pré-carregue a única fonte que a primeira pintura precisa e o único módulo que a página precisa primeiro. Meça, não adivinhe: references/measuring-layout-shift.md.
• Confiar em uma construção. Hosts injetam scripts. Se o site diz "nada é carregado de outros hosts", o passo 6 deve provar isso na página servida.
• Deixar dados estruturados divergirem da página. Cada name ou headline em JSON-LD deve estar visível naquela página; o SEO044 do verificador é um proxy fraco para isso e a leitura de uma pessoa é a verificação real.

9. Referências

• references/checklist.md: cada ID de verificação, sua gravidade e por que existe.
• references/structured-data.md: JSON-LD honesto, a lista de permissões de tipos, tipos médicos e como uma Política de Segurança de Conteúdo estrita interage com blocos de dados inline.
• references/health-sites.md: o que uma página de saúde ou pesquisa precisa além das verificações mecânicas.
• references/measuring-layout-shift.md: um pequeno script Playwright que observa mudanças de layout sob CPU e rede limitadas.
• references/review-prompt.md: um prompt que uma pessoa pode colar em qualquer agente para executar esta revisão honestamente.
• references/release-review.md: verificações de revisão de lançamento registradas, matriz de teste, auditoria de desafiante de fronteira e documentação de defeito SEO008.

Cabeçalhos de segurança (Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy) pertencem a uma revisão de segurança. Esta skill os menciona apenas onde eles tocam dados estruturados; use sua linha de base de segurança para o resto.