Migration Sanity

Utilisez cette skill pour les travaux de migration CMS vers Sanity. Traitez la migration comme un projet de stratégie de contenu et d'ETL, pas comme un simple lift-and-shift aveugle.

Workflow Obligatoire

1. Lisez d'abord references/general.md.
2. Si la plateforme source est connue, consultez aussi son guide :
   • AEM / Adobe Experience Manager : references/aem.md
   • Contentful : references/contentful.md
   • Strapi : references/strapi.md
   • Webflow : references/webflow.md
   • WordPress / WXR / Elementor : references/wordpress.md
   • Payload : references/payload.md
   • Drupal : references/drupal.md
   • Markdown / MDX / fichiers frontmatter : references/markdown.md
3. Avant d'écrire le code, produisez un court plan de migration couvrant l'accès à la source, le périmètre de contenu, les décisions de schéma, l'extraction, la transformation, l'import, la validation, les redirects et la bascule.
4. Préférez les scripts déterministes et reproductibles pour les migrations réelles. Écrivez et examinez les scripts de migration, les mappings et les contrôles de validation ; ne comptez pas sur des opérations de contenu ponctuelles pour de gros volumes de contenu.

Livrables à Produire

Pour les tâches d'implémentation ou de planification, produisez ces artefacts ou expliquez pourquoi ils ne sont pas nécessaires :

• Inventaire de contenu : types de source, dénombrements, locales, périmètre statut/brouillon, ressources et types de relations.
• Mapping source-vers-Sanity : types de documents, types d'objets, références, champs Portable Text, champs ressources, IDs et contenu ignoré.
• Approche d'extraction : identifiants/accès nécessaires, commandes API/export, localisation du snapshot brut et angles morts connus.
• Plan de transformation/import : IDs déterministes, ordre d'écriture, gestion des ressources, conversion du texte enrichi, validation et stratégie de relance.
• Plan de bascule : sync delta/gel du contenu, redirects, contrôles de liens brisés, métadonnées SEO et nettoyage manuel.

Valeurs par Défaut

• Utilisez des IDs de documents stables dérivés des IDs source, slugs, chemins ou hashes.
• Utilisez createOrReplace, createIfNotExists ou sanity dataset import --replace pour que les relances convergent.
• Créez un snapshot des données source extraites sur disque avant de les transformer.
• Importez ou créez les documents référencés avant les documents qui les référencent.
• Convertissez le texte enrichi en Portable Text au lieu de stocker des chaînes HTML ou Markdown brutes.
• Uploadez les ressources vers Sanity ou la Media Library ; ne laissez pas le contenu de production dépendre des URLs CDN hérités.
• Suivez les problèmes de qualité par document et produisez un résumé de validation avant la bascule.
• Préservez les URLs hérités et les IDs source pour les redirects, QA et dépannage futur.

Garde-fous Sanity

• Modelez ce qu'est le contenu, pas comment l'ancien site l'a rendu.
• Utilisez les documents pour les entités réutilisables ou gérées indépendamment ; utilisez les objets pour le contenu détenu par un document.
• Utilisez defineType, defineField et defineArrayMember si vous créez des schémas Sanity.
• Utilisez les champs image/file avec des ressources Sanity uploadées ou des ressources Media Library, pas des URLs CDN hérités.
• Utilisez les tableaux Portable Text pour le texte enrichi et les blocs personnalisés ; ne stockez pas du HTML brut comme le body canonique.
• Exécutez l'extraction de schéma et TypeGen après des changements de schéma ou de requête GROQ quand le projet utilise TypeScript.
• Déployez ou appliquez les changements de schéma avant d'utiliser les outils MCP/contenu sur le dataset cible.

Pour un guide d'implémentation Sanity plus approfondi, utilisez sanity-best-practices s'il est déjà disponible. S'il n'est pas installé, dites à l'utilisateur qu'il peut l'ajouter avec :

npx skills add sanity-io/agent-toolkit --skill sanity-best-practices

Arrêtez-vous et Demandez

Arrêtez-vous avant de coder quand l'un de ces points n'est pas clair :

• Chemin d'accès à la source, identifiants, fichier d'export ou connexion à la base de données.
• Projet/dataset Sanity cible ou si un dataset de test doit être utilisé.
• Périmètre brouillon, archivé, planifié, locale ou historique de version.
• Si les fichiers média doivent être migrés et si les URLs/fichiers de ressources sont accessibles.
• Si le schéma de destination existe ou doit être conçu dans le cadre de la migration.

Ne Faites Pas Ceci

• Ne créez pas d'IDs aléatoires pour les documents soutenus par la source.
• Ne récupérez pas puis créez les documents référencés ; utilisez des IDs déterministes et createIfNotExists/createOrReplace.
• Ne lancez pas de migrations en masse via les outils MCP contenu quand NDJSON ou les scripts sont appropriés.
• N'aplatissez pas les valeurs de fallback de locale dans les traductions sauf demande explicite.
• Ne laissez pas de TODOs pour les ressources, auteurs, références ou conversion de texte enrichi requis.
• Ne déclarez pas une migration terminée sans contrôles de dénombrement, contrôles d'échantillons, contrôles de références et contrôles de route/redirect.

Carte de Référence

Utilisez references/general.md pour les principes de migration partagés et les références de plateforme pour les routes d'extraction propres à la source, les pièges de modélisation et les contrôles de validation.

Pour les systèmes source non explicitement couverts, appliquez references/general.md et adaptez le motif de plateforme le plus proche :

• CMSes API-first : commencez par Contentful, Strapi ou Payload.
• Systèmes monolithiques/page-builder : commencez par WordPress, Drupal, Webflow ou AEM.
• Exports riches en HTML : commencez par les guides de texte enrichi WordPress et Webflow.
• Sources Markdown-first : commencez par references/markdown.md.