Audit du Cookbook

Instructions

Examinez le notebook Cookbook demandé en utilisant les directives et grilles d'évaluation figurant dans style_guide.md. Fournissez une note basée sur les directives de scoring et des recommandations pour améliorer le cookbook.

Le style guide fournit des modèles détaillés et des exemples pour :

• Les introductions centrées sur les problèmes avec Terminal Learning Objectives (TLOs) et Enabling Learning Objectives (ELOs)
• Les modèles de prérequis et de configuration
• La structure du contenu principal
• Les conclusions qui reviennent aux objectifs d'apprentissage

IMPORTANT : Lisez toujours style_guide.md en premier avant de mener un audit. Le style guide contient les modèles canoniques et les bons/mauvais exemples à consulter.

Flux de travail

Suivez ces étapes pour un audit complet :

1. Lire le style guide : Commencez par examiner style_guide.md pour comprendre les bonnes pratiques actuelles
2. Identifier le notebook : Demandez le chemin d'accès à l'utilisateur s'il n'est pas fourni
3. Exécuter les vérifications automatisées : Utilisez python3 validate_notebook.py <path> pour détecter les problèmes techniques et générer un markdown
   • Le script exécute automatiquement detect-secrets pour analyser les clés API et identifiants codés en dur
   • Utilise des motifs personnalisés définis dans scripts/detect-secrets/plugins.py
   • Vérifie par rapport à la base de référence à scripts/detect-secrets/.secrets.baseline
4. Examiner la sortie markdown : Le script génère un fichier markdown dans le dossier tmp/ pour faciliter la révision (économise du contexte par rapport au .ipynb brut)
   • Le dossier tmp/ est dans gitignore pour éviter de valider des artefacts de révision
   • Le markdown inclut les cellules de code mais exclut les sorties pour une révision plus claire
5. Révision manuelle : Parcourez la version markdown en évaluant par rapport au style guide et à la grille
6. Noter chaque dimension : Appliquer les directives de scoring objectivement
7. Générer le rapport : Suivre le format du rapport d'audit ci-dessous
8. Fournir des exemples spécifiques : Montrer des améliorations concrètes avec des références de ligne en utilisant les modèles du style guide

Format du rapport d'audit

Présentez votre audit en utilisant cette structure :

Résumé exécutif

• Score global : X/20
• Points forts clés (2-3 puces)
• Problèmes critiques (2-3 puces)

Scoring détaillé

1. Qualité narrative : X/5

[Justification brève avec exemples spécifiques]

2. Qualité du code : X/5

[Justification brève avec exemples spécifiques]

3. Exactitude technique : X/5

[Justification brève avec exemples spécifiques]

4. Exploitabilité et compréhension : X/5

[Justification brève avec exemples spécifiques]

Recommandations spécifiques

[Liste priorisée et exploitable d'améliorations avec références à des sections spécifiques]

Exemples et suggestions

[Afficher des extraits spécifiques du notebook avec des suggestions concrètes pour l'amélioration]

Liste de contrôle de référence rapide

Utilisez ceci pour assurer une couverture complète :

Introduction (Voir section 1 du style_guide.md)

• [ ] Crochets avec le problème en cours de résolution (1-2 phrases)
• [ ] Explique pourquoi c'est important (1-2 phrases)
• [ ] Liste les objectifs d'apprentissage comme puces (2-4 TLOs/ELOs)
• [ ] Se concentre sur la valeur livrée, pas sur la machinerie construite
• [ ] Optionnel : mentionne les applications plus larges (1 phrase)

Prérequis et configuration (Voir section 2 du style_guide.md)

• [ ] Liste les connaissances requises clairement
• [ ] Liste les outils requis (version Python, clés API)
• [ ] Mentionne les connaissances recommandées si applicable
• [ ] Utilise %%capture pour pip install pour supprimer la sortie
• [ ] Utilise dotenv.load_dotenv() pas os.environ
• [ ] Définit la constante MODEL au début
• [ ] Groupe les installations connexes en une seule commande

Structure et organisation

• [ ] A une progression logique des sections
• [ ] Chaque section enseigne par la démonstration
• [ ] Les blocs de code ont un texte explicatif avant eux
• [ ] Inclut ce que nous avons appris après les blocs de code
• [ ] Utilise des en-têtes pour casser les sections

Conclusion (Voir section 4 du style_guide.md)

• [ ] Revient aux objectifs d'apprentissage
• [ ] Résume ce qui a été réalisé
• [ ] Suggère des moyens d'appliquer les leçons au contexte de l'utilisateur
• [ ] Pointe vers les prochaines étapes ou ressources connexes

Qualité du code

• [ ] Tous les blocs de code ont un texte explicatif avant eux
• [ ] Pas de clés API codées en dur (vérifiées automatiquement par detect-secrets)
• [ ] Noms de variables significatifs
• [ ] Les commentaires expliquent « pourquoi » pas « quoi »
• [ ] Suit les bonnes pratiques linguistiques
• [ ] Le nom du modèle défini comme constante en haut du notebook

Gestion des sorties

• [ ] Les journaux pip install supprimés avec %%capture
• [ ] Pas de sortie de débogage détaillée
• [ ] Affiche les réponses API pertinentes
• [ ] Stack traces uniquement lors de la démonstration de la gestion des erreurs

Qualité du contenu

• [ ] Explique pourquoi les approches fonctionnent
• [ ] Discute quand utiliser cette approche
• [ ] Mentionne les limitations/considérations
• [ ] Fournit des connaissances transférables
• [ ] Sélection de modèle appropriée

Exigences techniques

• [ ] Exécutable sans modification (sauf clés API)
• [ ] Utilise des modèles d'API non obsolètes
• [ ] Utilise des noms de modèles valides (claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-6)
• [ ] Utilise des alias de modèles non datés (jamais d'ID datés comme claude-sonnet-4-6-20250514)
• [ ] Le nom du modèle défini comme constante en haut du notebook
• [ ] Inclut les spécifications de dépendances
• [ ] Assigné à la catégorie principale
• [ ] A des étiquettes pertinentes

Philosophie du contenu : Action + Compréhension

Les cookbooks sont principalement orientés vers l'action mais intègrent stratégiquement la compréhension et sont informés par le cadre Diataxis.

Principes fondamentaux :

• Focus pratique : Montrez aux utilisateurs comment accomplir des tâches spécifiques avec du code fonctionnel
• Cadrage centré sur les problèmes : Commencez par le problème en cours de résolution et la valeur livrée, pas la machinerie
• Perspective du constructeur : Écrit du point de vue de l'utilisateur, résolvant les problèmes réels
• Autonomisation de l'agence : Aidez les utilisateurs à comprendre pourquoi les approches fonctionnent, pas seulement comment
• Connaissances transférables : Enseignez des modèles et des principes qui s'appliquent au-delà de l'exemple spécifique
• Pensée critique : Encouragez les utilisateurs à remettre en question les résultats, à reconnaître les limitations, à faire des choix éclairés
• Contrats d'apprentissage : Énoncez les objectifs d'apprentissage à l'avance, puis cartographiez-les dans les conclusions

Ce qui fait un bon cookbook

Un bon cookbook n'aide pas seulement les utilisateurs à résoudre le problème d'aujourd'hui, il les aide également à comprendre les principes sous-jacents derrière les solutions, les encourageant à reconnaître quand et comment adapter les approches. Les utilisateurs seront en mesure de prendre des décisions plus éclairées sur la conception des systèmes IA, de développer un jugement sur les résultats du modèle et de développer des compétences qui se transfèrent aux futurs systèmes IA.

Ce que les cookbooks NE SONT PAS

Les cookbooks ne sont pas des tutoriels purs : Nous supposons que les utilisateurs ont des compétences techniques de base et la familiarité avec l'API. Nous énumérons clairement les prérequis dans nos cookbooks et orientons les utilisateurs vers l'Academy pour en savoir plus sur les sujets. Ce ne sont pas des explications exhaustives : Nous n'enseignons pas l'architecture de transformateur ou la théorie des probabilités. Nous devons comprendre que nos utilisateurs suivent nos cookbooks pour résoudre les problèmes auxquels ils sont confrontés aujourd'hui. Ils sont occupés, en train d'apprendre ou de construire, et veulent être en mesure d'utiliser ce qu'ils apprennent pour résoudre leurs besoins immédiats. Les cookbooks ne sont pas des documents de référence : Nous ne documentons pas exhaustivement tous les paramètres, nous lions vers les ressources appropriées de notre documentation si nécessaire. Les cookbooks ne sont pas de simples conseils et astuces : Nous n'enseignons pas les « hacks » qui ne fonctionnent que pour la génération actuelle du modèle. Nous ne surpromet pas et ne sous-livrons pas. Les cookbooks ne sont pas du code prêt pour la production : Ils mettent en avant les cas d'usage et les capacités, pas les modèles de production. La gestion des erreurs excessive n'est pas requise.

Directives de style

Voix et ton

• Éducatif et autonomisant
• Professionnel mais accessible
• Respectueux de l'intelligence et du temps de l'utilisateur
• Soit deuxième personne (« vous ») soit première personne du pluriel (« nous ») - soyez cohérent dans un notebook

Qualité de l'écriture

• Explications claires et concises
• Voix active préférée
• Paragraphes courts (3-5 phrases)
• Évitez le jargon sans définition
• Utilisez des en-têtes pour casser les sections

Présentation du code

• Toujours expliquer avant de montrer : Chaque bloc de code doit être précédé d'un texte explicatif
• Expliquer après l'exécution : Incluez ce que nous avons appris après l'exécution des blocs de code
• Les commentaires expliquent pourquoi, pas quoi : Utilisez des noms de variables significatifs
• Utiliser les constantes : Définir MODEL comme une constante en haut
• Bonnes habitudes : Utiliser dotenv.load_dotenv() au lieu de os.environ

Gestion des sorties

Supprimer la sortie extraneous avec %%capture :

• Les journaux pip install (toujours les supprimer)
• Les déclarations de débogage détaillées
• Les longues stack traces (sauf lors de la démonstration de la gestion des erreurs)

Afficher la sortie pertinente :

• Les réponses API qui démontrent la fonctionnalité
• Les exemples d'exécution réussie

Exigences structurelles

Voir style_guide.md pour les modèles détaillés et les exemples

1. Introduction (Obligatoire)

Doit inclure :

• Crochet problématique (1-2 phrases) : Quel problème résolvons-nous ?
• Pourquoi c'est important (1-2 phrases) : Pourquoi est-ce important ?
• Objectifs d'apprentissage (2-4 puces) : « À la fin de ce cookbook, vous serez capable de... »
  • Utiliser des verbes d'action (Construire, Implémenter, Déployer, etc.)
  • Être spécifique sur les capacités
  • Inclure le contexte/les contraintes
• Optionnel : Applications plus larges (1 phrase)

❌ Éviter : Commencer par la machinerie (« Nous allons construire un agent de recherche... ») ✅ Faire : Commencer par le problème/la valeur (« Votre équipe passe des heures à trier les défaillances CI... »)

2. Prérequis et configuration (Obligatoire)

Doit inclure :

• Connaissances requises : Compétences techniques nécessaires
• Outils requis : Version Python, clés API avec liens
• Recommandé : Connaissances de base optionnelles qui aident
• Configuration : Étape par étape avec explications
  • Utiliser %%capture pour pip install
  • Utiliser dotenv.load_dotenv() pas os.environ
  • Définir la constante MODEL en haut

3. Contenu principal (Obligatoire)

Organisé par étapes ou phases logiques, chacun avec :

• En-têtes de section clairs
• Texte explicatif avant les blocs de code (ce que nous sommes sur le point de faire)
• Exemples de code
• Texte explicatif après les blocs de code (ce que nous avons appris)
• Sorties attendues (le cas échéant)
• Optionnel : Callouts de compréhension (pourquoi cela fonctionne, quand l'utiliser, limitations)

4. Conclusion (Recommandée)

Doit inclure :

• Récapitulatif : Revenir aux objectifs d'apprentissage
• Ce qui a été réalisé : Résumé des points clés
• Directive d'application : Comment appliquer les leçons au contexte de l'utilisateur
• Prochaines étapes : Ressources connexes ou idées à poursuivre

❌ Éviter : Les résumés génériques (« Nous avons démontré comment le SDK permet... ») ✅ Faire : Les conseils exploitables (« Envisagez d'appliquer ceci à X... Ensuite, essayez Y... »)

Sections optionnelles

• Comment cela fonctionne : Brève explication du mécanisme sous-jacent
• Quand utiliser ceci : Cas d'usage et contextes appropriés
• Limitations et considérations : Mises en garde, modes de défaillance, contraintes
• Dépannage : Problèmes courants et solutions
• Variations : Approches alternatives ou extensions
• Notes de performance : Considérations d'optimisation
• Lectures complémentaires : Liens vers la documentation pertinente, articles ou explications plus approfondies

Anti-modèles courants à signaler

Référez-vous à style_guide.md pour les bons/mauvais exemples détaillés. Vigilance pour ces problèmes :

Anti-modèles d'introduction

❌ Commencer par la machinerie : « Nous allons construire un agent de recherche en utilisant le SDK Claude... » ❌ Vidages de fonctionnalités : Énumération des méthodes SDK ou des capacités d'outils ❌ Objectifs d'apprentissage vagues : « En savoir plus sur les agents » ou « Comprendre l'API » ✅ Cadrage centré sur les problèmes avec des objectifs d'apprentissage spécifiques et exploitables

Anti-modèles de configuration

❌ Sortie pip install bruyante sans %%capture ❌ Plusieurs commandes pip install distinctes ❌ Utilisation de os.environ["API_KEY"] = "your_key" au lieu de dotenv ❌ Codage des noms de modèles partout au lieu d'utiliser une constante MODEL ✅ Configuration propre avec installations groupées, dotenv et constantes

Anti-modèles de présentation du code

❌ Blocs de code sans texte explicatif avant eux ❌ Aucune explication de ce que nous avons appris après l'exécution du code ❌ Les commentaires qui expliquent « quoi » le code fait (le code doit être auto-documenté) ❌ Sur-explication du code évident ✅ Contexte avant le code, insights après le code, les commentaires expliquent « pourquoi »

Anti-modèles de conclusion

❌ Les résumés génériques : « Nous avons démontré comment le SDK permet... » ❌ Simplement reformuler ce que le notebook a fait sans conseils ❌ Ne pas revenir aux objectifs d'apprentissage énoncés ✅ Conseils exploitables sur l'application des leçons au contexte spécifique de l'utilisateur