Lisez ces fichus documents

Ne cherchez pas à deviner où la documentation officielle peut répondre à votre question. La bonne approche, la plus courante, consiste à rechercher sur le Web la documentation officielle à jour, à ouvrir les pages pertinentes et à les lire avant de coder. Pour les API, les versions, le comportement des fournisseurs, la configuration, les limites, les hooks de cycle de vie ou les flux sensibles en matière de sécurité, basez votre réponse sur ce que dit réellement la documentation.

Situations justifiant de consulter d’abord la documentation

Lisez la documentation avant de continuer si l’une des situations suivantes s’applique :

• L'utilisateur demande « la dernière version », « la version actuelle », « officielle », « prise en charge », « les meilleures pratiques », « recommandé », « aujourd’hui », « maintenant » ou « vérifie ça ».
• La documentation nécessaire ne se trouve pas déjà dans le dépôt ni n’est fournie par l’utilisateur. Recherchez la documentation officielle sur le Web plutôt que de compter sur la mémoire du modèle pour qu’elle soit à jour.
• La tâche consiste à ajouter, mettre à jour, configurer ou importer un paquet, un SDK, un framework, un plugin, une CLI, un modèle, une ressource cloud ou une intégration de fournisseur.
• L’API évolue rapidement ou est sensible aux versions : SDK d’IA, API OpenAI/Anthropic/Google, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, API de navigateur, plateformes de déploiement, bibliothèques d’authentification et autres éléments similaires.
• La mise en œuvre dépend de l’authentification, des champs d’application OAuth, des autorisations, des secrets, des webhooks, de la facturation, des paiements, des données à caractère personnel, du chiffrement, de la conservation des données, des migrations, des tentatives de reconnexion, des limites de débit, des quotas, de la mise en cache, des déploiements ou de la conformité.
• Une erreur peut faire référence à une fonctionnalité obsolète, à des options inconnues, à des exportations manquantes, à une configuration non valide, à des champs non pris en charge, à des valeurs par défaut modifiées ou à une incompatibilité de version.
• Un dépôt contient de la documentation locale, des ADR, des schémas générés, des spécifications OpenAPI, des registres de routes/actions, de la documentation sur le système de conception ou des fichiers README au niveau du paquet qui pourraient définir le contrat.
• Il est coûteux de revenir sur ce choix : formats de transmission publics, schéma de base de données, stratégie de migration, identifiants persistants, noms d’événements, comportement visible par le client ou contrats d’automatisation externes.
• Vous vous surprenez à écrire « généralement », « probablement », « je pense », « de mémoire », ou à copier du code issu de la mémoire du modèle pour une API externe.

Ce qui compte comme de la documentation

Utilisez la source la plus fiable disponible :

• documentation du dépôt local, spécifications, ADR, schémas, types générés, fichiers README des paquets et tests pour le comportement spécifique au projet.
• Documentation officielle du produit, références API, guides de migration, journaux de modifications, notes de mise à jour et source/types du SDK pour les comportements tiers. Recherchez-les sur le Web si vous ne disposez pas déjà de l’URL exacte.
• Métadonnées du registre de paquets pour les versions. Avant d’ajouter une dépendance, exécutez npm view version, pnpm view versionou son équivalent dans l’écosystème, puis consultez la documentation relative à cette version majeure.
• Code source ou définitions de types lorsque la documentation officielle est incomplète. Considérez cela comme une preuve, et non comme une légende urbaine.

Évitez Stack Overflow, les anciens articles de blog, les extraits de code aléatoires et votre mémoire comme source principale lorsqu’une documentation officielle existe. N’utilisez les sources communautaires que pour déboguer des symptômes une fois que le contrat faisant autorité est connu.

Workflow requis

1. Identifiez la surface exacte : nom du paquet, version installée, version cible, point de terminaison du fournisseur, commande CLI, fichier de configuration, aide locale, schéma ou fonctionnalité du produit.
2. Recherchez sur le Web la documentation officielle actuelle, sauf si les documents pertinents sont déjà disponibles localement ou si l’utilisateur a fourni une URL. Effectuez des recherches ciblées telles que official docs, migration guide, ou API reference.
3. Ouvrez et lisez la documentation la plus proche de cette surface. Privilégiez d’abord la documentation locale pour le code interne, puis la documentation officielle en amont. Pour les nouveaux paquets, vérifiez la dernière version avant d’écrire des commandes d’importation, de configuration ou d’installation.
4. Extraire les quelques informations nécessaires à la tâche : noms d’options, importations, règles de cycle de vie, comportement par défaut, changements rompant la compatibilité, limites, autorisations et exemples pour la version majeure actuelle.
5. Implémentez ou répondez en utilisant ces informations. Si la documentation est en contradiction avec le code existant, examinez le chemin d’exécution du code local et signalez la divergence.
6. Vérifiez à l’aide du test le plus simple possible : vérification des types, tests, compilation, simulation CLI, validation du schéma de l’API ou reproduction locale.
7. Dans la réponse finale, citez les documents ou fichiers locaux consultés lorsque ces éléments influencent la recommandation ou la mise en œuvre.

Exemples devant donner lieu à la création d’une documentation

• « Ajouter Tailwind à cette application. » Vérifiez la version majeure actuelle de Tailwind et sa documentation d’installation sur le Web avant de créer des fichiers de configuration ou de supposer une ancienne configuration PostCSS.
• « Utilisez le SDK d’IA pour diffuser les réponses en continu. » Vérifiez la version majeure actuelle du SDK d’IA, les importations, les noms des paquets des fournisseurs, les aides à la diffusion en continu et les exemples de serveur/d’exécution dans la documentation officielle.
• « Configurer les webhooks Stripe. » Lisez la documentation actuelle de Stripe concernant la vérification des signatures, les tentatives de réessai d’événements, les secrets des points de terminaison et l’analyse du corps des requêtes avant de coder.
• « Corrigez ce bug de mise en cache de Next.js. » Lisez la documentation relative à la version principale de Next.js installée et au mode de routage avant de supposer la sémantique d’invalidation du cache.
• « Ajouter des migrations Drizzle. » Lisez la documentation actuelle du kit Drizzle et les conventions de migration existantes du dépôt avant de générer des fichiers.
• « Créer une action GitHub. » Consultez la documentation officielle sur la syntaxe et les autorisations des actions, en particulier concernant pull_request, workflow_run, l’OIDC, les jetons et les artefacts.
• « Pourquoi ce flux OAuth échoue-t-il ? » Lisez la documentation du fournisseur concernant les champs d’application, l’URI de redirection, le PKCE, l’actualisation des jetons et la vérification des applications avant de modifier le code.
• « Utilisez le système de plan/commentaire/action de ce dépôt. » Lisez la documentation locale, les registres de routes/actions, les schémas et les tests avant de créer des points de terminaison ou des propriétés.
• « Mettre à jour Vite/Nitro/React. » Consultez le guide de migration pour connaître la version majeure cible exacte avant de modifier la configuration ou les importations.
• « Quel modèle devrions-nous utiliser ? » Lisez la documentation actuelle sur les modèles du fournisseur, les pages de tarification et de limites ainsi que les exemples du SDK avant de faire une recommandation.

Quand une lecture rapide en local suffit

Ne parcourez pas le Web pour chaque modification mineure. Une consultation de la documentation peut se faire localement et rapidement lorsque la réponse se trouve déjà dans le dépôt : utilisation des aides existantes, tests à proximité, interfaces typées, clients générés, ADR ou fichiers README des paquets. Mais si la tâche dépend d’un outil externe, d’un paquet, d’un fournisseur ou du comportement actuel du produit, une recherche sur le Web est généralement la bonne première étape. Pour les questions de syntaxe de langage triviales, les corrections de fautes de frappe, le formatage ou le code autonome sans contrat externe, procédez normalement.

Si la documentation n’est pas disponible

Si l’accès au réseau, l’authentification ou l’absence de fichiers locaux empêche la lecture de la documentation, indiquez-le clairement avant de vous fier à votre mémoire. Limitez l’incertitude, examinez le code source ou les types s’ils sont disponibles, et évitez de présenter le résultat comme étant confirmé et à jour.