senseiewok/site-seo-review

Audit SEO de site

Les moteurs de recherche et les aperçus de liens lisent une page comme le ferait un inconnu : le titre, la description, l'adresse que la page revendique comme sienne, l'image qu'elle propose, les titres, et toutes les données structurées qu'elle porte. Cette compétence vérifie que ces éléments existent, sont cohérents entre eux et avec le sitemap, et ne revendiquent rien que la page ne montre pas. Elle ne promet pas de classement. Personne d'honnête ne le peut.

Les leçons ici proviennent d'un audit réel d'un petit site de recherche en 2026, où chaque constat ci-dessous a été soulevé par un relecteur puis confirmé par une personne lisant la source. Ils sont consignés pour que le site suivant n'ait pas à les redécouvrir.

Recherche, pas avis médical. Lorsque cette compétence aborde des sites de santé, il s'agit de la manière dont leurs pages se décrivent, jamais d'une question médicale.

1. Quand utiliser cette compétence

• Un site statique ou majoritairement statique (un dossier de fichiers .html, quelle que soit sa méthode de construction) est sur le point d'être publié ou vient d'être modifié.
• Quelqu'un demande « pourquoi l'aperçu du lien est incorrect », « pourquoi cette page n'est pas dans les résultats de recherche », ou « rendez le site plus découvrable ».
• Un site de santé, de recherche ou autre site à enjeux élevés a besoin que ses métadonnées et données structurées soient vérifiées pour leur honnêteté, et non seulement leur présence.
• Vous souhaitez confier la partie mécanique d'un tel audit à un petit modèle local et garder les décisions de rédaction pour les humains.

Pas pour : les en-têtes de sécurité (HSTS, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy relèvent d'un audit de sécurité ; voir section 9), la configuration serveur, la recherche payante, ou tout ce qui nécessite un compte auprès d'un moteur de recherche.

2. Workflow

1. Mesurez avant de toucher à quoi que ce soit. Exécutez le vérificateur sur le dossier du site construit (étape 2) et, si le site est en ligne, enregistrez son apparence dans un débogueur d'aperçu de lien et dans une recherche pour son propre nom. Sauvegardez la sortie. Tout ce que vous modifierez ensuite sera comparé à cela.
2. Exécutez le vérificateur. python scripts/seo_audit.py SITE_DIR --base-url https://votre-site.example/ --json. Le code de sortie 0 signifie qu'aucun résultat de niveau erreur n'a été trouvé ; --strict fait aussi compter les avertissements. Les identifiants et leur signification se trouvent dans references/checklist.md.
3. Lisez les pages. Le vérificateur voit la structure, pas le sens. Lisez chaque page indexée une fois comme le ferait un inconnu : le titre indique-t-il ce qu'est la page, la description ne revendique-t-elle que ce que la page montre, le premier titre correspond-il à la promesse du titre, chaque lien dit-il où il mène. Notez chaque observation avec le fichier et la ligne.
4. Proposez du texte, ne l'appliquez pas. Pour chaque titre, description ou texte de lien que vous souhaitez modifier, écrivez le texte exact actuel, le texte exact proposé, et la phrase sur la page qui soutient la proposition. Une description qui dit « les preuves derrière chaque affirmation » alors que la page montre un seul élément de preuve est une surestimation ; un relecteur a précisément signalé cela.
5. Faites réviser le wording par une personne, ou par un second modèle d'une famille différente qui voit le texte de la page et votre proposition mais pas votre raisonnement, avant que quoi que ce soit ne soit rendu public. Sur un site de santé ou de recherche, une personne approuve ; l'approbation d'un modèle est un indice.
6. Vérifiez en ligne. Après le déploiement, récupérez chaque page comme le ferait un navigateur (une requête à la fois, uniquement votre propre hôte) et confirmez : le HTML servi est identique au fichier construit, rien n'a été injecté par l'hôte, robots.txt et sitemap.xml sont servis, et l'aperçu du lien montre le titre, la description et l'image que vous aviez prévus. Un téléchargement réussi n'est pas une page vérifiée.

3. Le vérificateur

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

Résultat	Signification
sortie 0	aucun résultat de niveau erreur (des avertissements et informations peuvent exister)
sortie 1	au moins une erreur ; avec --strict, au moins un avertissement
sortie 2	utilisation : pas un dossier, pas de fichier .html, mauvais drapeau

Il lit uniquement des fichiers. Il n'ouvre aucune connexion réseau, n'exécute rien à partir d'une page et n'écrit rien sauf si --json-out est fourni. Une page indexée est toute page sauf 404.html sans balise meta robots noindex ; les vérifications de métadonnées s'appliquent aux pages indexées, les vérifications de contenu à toutes les pages. Les résultats sont triés et stables, donc deux exécutions sur le même dossier sont octet-identiques et peuvent être comparées.

Les identifiants des vérifications sont stables (SEO001 titre manquant, SEO008 canonique différent de sa propre adresse, SEO021 le sitemap liste une page qui n'est pas indexée, SEO043 type de donnée structurée médicale, SEO050 script tiers, etc.). Considérez error comme « à corriger avant publication », warn comme « décidez, puis corrigez ou documentez », info comme « bon à savoir ». Les règles avec lesquelles il lit un site (adresses, ce qui compte comme fichier du site, groupes robots, objets JSON-LD) sont dans references/checklist.md.

Comment le vérificateur a été créé

La suite de tests est venue en premier : un site de fixture qui doit produire zéro résultat, et une copie délibérément cassée par vérification, chacune comparée sur les résultats exacts et les codes de sortie. Les tests ont été vérifiés par rapport à une implémentation de référence indépendante et par rapport à des versions délibérément cassées de celle-ci, de sorte que chaque test a été vu échouer quand il le devait.

Un petit modèle à poids ouverts exécuté localement a ensuite rédigé seo_audit.py à partir d'une spécification écrite. Son brouillon a passé chacun de ces tests du premier coup. La réussite n'a pas été considérée comme une preuve. Un examen dirigé par une personne, effectué avec un modèle plus grand, a lu le brouillon du début à la fin par rapport à la spécification et a trouvé 17 défauts que les tests ne pouvaient pas voir. Parmi eux :

• les pages non nommées index.html obtenaient la mauvaise adresse ;
• la page 404 ignorait ses vérifications de contenu ;
• les résultats identiques étaient fusionnés ;
• les groupes robots et les wildcards ancrés étaient mal lus ;
• les membres @graph étaient mal traités ;
• le HTML profondément imbriqué faisait planter l'exécution ;
• un chemin de feuille de style pouvait sortir du dossier du site.

Chaque défaut est devenu un nouveau test dans tests/test_seo_audit_extra.py et a ensuite été corrigé avec le plus petit changement possible. Les tests décident si le vérificateur est correct. Ni le modèle qui l'a écrit ni celui qui l'a examiné ne le fait. Si vous modifiez le script, exécutez les tests ; si vous trouvez un cas qu'ils manquent, ajoutez un test avant la correction.

4. Sites de santé et de recherche

Le contenu de santé est soumis à des normes plus élevées par les lecteurs et par les directives de qualité des moteurs de recherche (l'expression est « Your Money or Your Life »). Le vérificateur applique la partie mécanique ; le reste est une tâche de lecture listée dans references/health-sites.md. En bref, chaque page de ce type a besoin : d'un auteur visible ou d'une page À propos qui indique qui est responsable ; d'une date visible et d'un statut de brouillon ou de révision visible lorsque le contenu n'est pas définitif ; de sources primaires citées ; d'une mention claire « recherche, pas avis médical » ; de descriptions et de données structurées qui ne revendiquent pas plus que ce que la page montre ; et d'aucun type de donnée structurée médicale (MedicalCondition, MedicalWebPage, Drug) à moins que le site ne soit une autorité clinique. references/structured-data.md explique à quoi ressemblent des données structurées honnêtes et comment une Content-Security-Policy stricte interagit avec elles.

5. Comment confier des parties de cela à un petit modèle local en toute sécurité

L'audit se divise en tâches qu'un vérificateur déterministe peut juger et en tâches que seule une personne (ou un lecteur attentif) peut faire. Ne donnez à un modèle local que le premier type.

Sûr à déléguer, avec un vérificateur	Garder avec une personne ou l'agent de contrôle
Écrire ou étendre le vérificateur par rapport à tests/test_seo_audit.py (le vérificateur décide)	Décider de tout titre, description ou texte de lien qui devient public
Lister, pour chaque page, le titre actuel exact, la description, le canonique et le h1 sous forme de tableau (vérificateur : les valeurs sont des sous-chaînes du fichier)	Juger si une description surestime
Classifier le texte de chaque lien comme « nomme sa cible » ou « générique », avec possibilité d'abstention (vérificateur : chaque lien est comptabilisé, aucun texte n'a été modifié)	Si les données structurées sont honnêtes pour ce site
Rédiger un sitemap à partir de la liste des pages (vérificateur : les SEO021/SEO022 du vérificateur)	Si une date est honnête

Règles : un seul paquet frais et autonome par tâche ; le texte de la page va à l'intérieur d'une limite de données avec une instruction de ne rien suivre à l'intérieur ; le modèle n'a pas d'outils ni de réseau ; une affirmation d'achèvement ne compte pour rien tant que la sortie du vérificateur ne la montre pas. Ne laissez jamais le modèle décider du wording. Si vous utilisez cela avec une boucle de délégation, écrivez d'abord le vérificateur et donnez-lui un stub qui doit échouer (un vérificateur qui affiche zéro résultat doit échouer aux tests).

6. Règles d'honnêteté

• Étiquetez chaque déclaration OBSERVÉ (vous l'avez exécutée ou lue, et pouvez nommer le fichier, la ligne ou la commande) ou INFÉRÉ (un jugement). « La description surestime » est inféré ; « la description dit X et la seule phrase correspondante de la page dit Y » est observé.
• Ne prétendez ou n'impliquez jamais une amélioration de classement, un changement de trafic ou un résultat d'aperçu que vous n'avez pas mesuré après coup. Les résultats SEO ne sont pas promis, ni par cette compétence ni par quiconque l'utilise.
• Une description, un titre ou un champ de donnée structurée ne peut revendiquer que ce qu'un lecteur peut voir sur cette page. Citez la phrase de soutien lorsque vous proposez du texte.
• Les dates doivent être vraies : un lastmod de sitemap ou une date de mise à jour visible qui bouge sans changement de contenu est un mensonge pour le lecteur et pour le robot d'exploration.
• Dites ce que vous n'avez pas vérifié. Le vérificateur ne récupère rien, donc une exécution propre ne dit rien sur ce que l'hôte sert.

7. Vérifier que la compétence fonctionne

Depuis le dossier de la compétence :

python -m unittest discover -s tests -v               # les deux fichiers de test, contre scripts/seo_audit.py
python tests/verify_checker.py scripts/seo_audit.py   # mêmes tests, verdict court : PASS n tests, ou FAIL lignes

Définissez SEO_AUDIT_PATH pour tester une autre copie du vérificateur. Les tests construisent des sites cassés à partir de tests/fixtures/good (qui doit produire zéro résultat), un défaut par identifiant de vérification, et comparent les résultats exacts et les codes de sortie. tests/test_seo_audit_extra.py ajoute les cas trouvés lors de l'examen : fichiers impairs, pages de sous-dossiers, page 404, groupes robots, graphes de données structurées, et un crochet d'audit qui confirme qu'une exécution n'ouvre aucun socket, ne démarre aucun processus et n'écrit aucun fichier sauf --json-out. L'image de partage 1200x630 dans la fixture est régénérée au moment du test par tests/fixtures/gen_fixtures.py. Un vérificateur qui n'a jamais échoué à un test ne prouve rien : tests/verify_checker.py exécuté contre un stub vide doit échouer.

Limites connues des tests : le lastmod du sitemap de la fixture est le 2026-10-01, donc une machine dont l'horloge est antérieure signale SEO023 ; le test de lien symbolique est ignoré là où le compte ne peut pas créer de liens symboliques (courant sous Windows).

8. Pièges courants

• Corriger ce que le vérificateur a trouvé et s'arrêter. Le vérificateur ne peut pas voir une surestimation, une date malhonnête ou un lien nommé « Ouvrir le modèle » qui pourrait nommer ce qu'il ouvre. L'étape 3 est l'examen.
• Traiter la page 404 comme une page. Elle doit être noindex et n'avoir aucun canonique ; sinon, chaque adresse manquante est indexée comme une copie de celle-ci.
• Canoniques relatifs. Un canonique doit être l'adresse absolue de la page elle-même, avec la barre oblique finale, et og:url doit lui être égal.
• Polices sans préchargement. La permutation de polices est une cause courante de changement de mise en page ; préchargez la police dont le premier affichage a besoin, et le module dont la page a besoin en premier. Mesurez, ne devinez pas : references/measuring-layout-shift.md.
• Faire confiance à une construction. Les hôtes injectent des scripts. Si le site dit « rien n'est chargé depuis d'autres hôtes », l'étape 6 doit le prouver sur la page servie.
• Laisser les données structurées dériver de la page. Chaque name ou headline en JSON-LD doit être visible sur cette page ; le SEO044 du vérificateur est un proxy faible pour cela et la lecture par une personne est la véritable vérification.

9. Références

• references/checklist.md : chaque identifiant de vérification, sa sévérité et pourquoi il existe.
• references/structured-data.md : JSON-LD honnête, la liste blanche des types, les types médicaux, et comment une Content-Security-Policy stricte interagit avec les blocs de données en ligne.
• references/health-sites.md : ce dont une page de santé ou de recherche a besoin au-delà des vérifications mécaniques.
• references/measuring-layout-shift.md : un court script Playwright qui observe les changements de mise en page sous CPU et réseau limités.
• references/review-prompt.md : une invite qu'une personne peut coller dans n'importe quel agent pour réaliser cet audit honnêtement.
• references/release-review.md : vérifications de révision de version enregistrées, matrice de tests, audit challenger frontalier et documentation du défaut SEO008.

Les en-têtes de sécurité (Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy) relèvent d'un audit de sécurité. Cette compétence ne les mentionne que là où ils touchent aux données structurées ; utilisez votre base de sécurité pour le reste.