Compétence de Construction de Prompts selon la Méthode Karpathy

# Spécification - kp-prompting ## Description Construire des prompts avancés, des spécifications de tâches, des critères de vérification et une configuration Claude Code en utilisant la méthode spec / verifier / environment d'Andrej Karpathy. Utilisez cette compétence chaque fois que vous devez spécifier une tâche ou un projet, resserrer ou réécrire un prompt, définir des critères de vérification ou de réussite pour la sortie d'un agent, ou configurer/mettre à jour une base de connaissances, une compétence ou des garde-fous pour un agent. --- ## Spec - ce qui est réellement voulu, assez précisément pour que le modèle ne devine pas ## Verifier - comment vous (ou le modèle) saurez que la sortie est réellement correcte ## Environment - le contexte persistant et les garde-fous pour que l'agent ne réapprenne pas tout de zéro à chaque fois Le fil conducteur reliant les trois : vous pouvez déléguer l'exécution, mais pas la compréhension. Chaque couche ci-dessous doit garder Tom dans la boucle sur les véritables décisions de jugement, et non pas simplement produire une sortie au rendu soigné qui masque des lacunes sur lesquelles il n'a jamais été interrogé. ## Deux modes - déterminez dans lequel vous vous trouvez avant de faire quoi que ce soit **Mode coaching (par défaut).** Tom vous confie une tâche, un prompt approximatif ou une demande de rédaction d'instructions pour quelque chose de spécifique. Resserrez-le en utilisant la lentille à trois couches ci-dessous et renvoyez une version améliorée dans le chat - sans fichiers. C'est le mode par défaut pour « aidez-moi à rédiger/améliorer un prompt pour X ». **Mode configuration complète.** Tom met en place un nouveau projet, un outil ou un flux de travail récurrent et souhaite l'échafaudage réel : un document de spécification, des critères de vérification et une configuration d'environnement (ajouts CLAUDE.md, garde-fous, pointeurs vers la base de connaissances). Déclenchez ce mode sur des phrases comme « spécifier », « configurer l'environnement pour », « développer la méthode Karpathy pour X », ou une demande explicite pour les trois couches. S'il n'est pas vraiment clair lequel convient, posez UNE question rapide plutôt que de deviner - construire le mauvais fait perdre plus de temps que de demander. La plupart du temps, c'est déductible : une tâche unique ou un brouillon de prompt en main → coaching ; un nouveau projet/fonctionnalité sans prompt encore → configuration complète. --- ## Couche 1 : Spec ### Pourquoi c'est important L'exemple de Karpathy : demandez à un modèle de pointe s'il faut conduire ou marcher jusqu'à un lave-auto à 50 mètres, et il répond marcher - manquant le fait évident que la voiture doit aussi y arriver. Les modèles sont excellents pour tout ce qui est vérifiable et étonnamment mauvais pour les décisions de jugement du monde réel, car les décisions de jugement sont précisément ce qui manque dans un signal d'entraînement propre. Le rôle d'une spec est de fournir au modèle le jugement qu'il ne peut pas déduire seul, afin qu'il ne soit pas réduit à deviner le contexte. Le prompting superficiel de haut niveau de type « mode plan » ne fait pas cela - il est trop mince pour porter une compréhension réelle. ### Comment en construire une - **Trouvez l'objectif réel, pas seulement la tâche.** « Rédiger le rapport de fin de mois » est une tâche. L'objectif est la décision que ce rapport est censé soutenir. Si ce n'est pas évident d'après ce que Tom a dit, demandez - quelques questions rapides ici évitent une bien plus grande réécriture plus tard. - **Travaillez par petites étapes de contrôle, pas en un seul gros transfert.** Tout remettre et ne se retrouver qu'à un résultat fini laisse la dérive se cumuler silencieusement. Découpez la spec en morceaux assez petits pour être vérifiés à chaque étape, surtout là où il y a une réelle ambiguïté. - **Soyez précis sur ce qui ne doit pas être supposé.** Chaque mot vague dans une spec devient une hypothèse que le modèle comble - avec confiance, dans la direction statistiquement probable, pas nécessairement ce que Tom veut réellement. Nommez les décisions de jugement spécifiques (conventions de nommage, cas limites, que faire en cas de données conflictuelles) au lieu de les laisser implicites. Une ligne comme « signalez toute hypothèse que vous faites au lieu d'en choisir une silencieusement » fait un travail réel ici. ### Ce qu'une spec doit contenir **Objectif** (la décision/résultat que cela sert, pas seulement la tâche), **limites de portée** (explicitement inclus vs. exclu), **les décisions de jugement à signaler plutôt qu'à résoudre silencieusement**, et **les contraintes** divisées en non-négociables vs. préférences. --- ## Couche 2 : Verifier ### Pourquoi c'est important Le cadre de Karpathy : ces modèles sont plus proches de « fantômes » que d'animaux - des simulateurs statistiques, pas des agents motivés. Crier sur un modèle, le supplier, ou lui dire que quelque chose compte beaucoup ne change pas la qualité de la sortie. Ce qui change la qualité de la sortie, c'est de savoir s'il y a quelque chose qui peut réellement vérifier le travail. C'est aussi pourquoi les modèles sont superhumains en code et en mathématiques (facilement vérifiables) et peu fiables en matière de goût et de jugement (rien à vérifier) - donc plus « bien fait » est explicite et vérifiable pour une tâche donnée, plus la sortie peut réellement être fiable plutôt que survolée avec une fatigue de relecture. ### Comment en construire un - **Établissez des critères de réussite/échec à l'avance, dans le prompt lui-même, pas après coup.** « Faire en sorte que le rapport soit beau » n'est pas vérifiable. « Le rapport a trois sections et chacune se termine par une recommandation » l'est. Rédigez les critères comme des choses qu'un second lecteur - humain ou modèle - pourrait vérifier sans lire dans les pensées de Tom. - **Utilisez un second modèle comme critique lorsque c'est peu coûteux.** Un modèle différent (ou le même modèle dans un contexte frais) évaluant la sortie du premier modèle par rapport à la spec attrape des choses que l'exécution originale rationalisera. - **Intégrez un signal externe réel lorsqu'il existe.** Pour le code : est-ce que ça se déploie réellement, est-ce que les tests passent ? Pour le travail non technique : est-ce que ça correspond au format/ton des exemples déjà connus comme bons ? Un vérificateur qui ne vérifie que la cohérence interne est plus faible qu'un qui vérifie par rapport à quelque chose de réel. ### Ce qu'un verifier doit contenir **Les critères spécifiques et vérifiables de réussite/échec** (pas des impressions), **qui ou quoi effectue la vérification** (auto-vérification, second modèle, signal de déploiement/test), et **ce qui se passe en cas d'échec** (réessayer avec quel retour spécifique, ou escalader vers Tom). --- ## Couche 3 : Environment ### Pourquoi c'est important La plupart des gens reconstruisent le contexte de zéro à chaque session - réexpliquant le projet, réaffirmant les règles, espérant que l'agent se souvienne de ce qu'il ne doit pas toucher. Garder l'historique de chat n'est pas la même chose qu'un véritable environnement. Un atelier avec les outils déjà en place vaut mieux que de réexpliquer tout l'atelier à chaque visite. ### Comment en construire un - **Un CLAUDE.md que l'agent lit automatiquement.** Couvrez : ce qu'est cet espace de travail/dépôt, quelles compétences personnalisées existent et quand les utiliser, où trouver les choses (l'architecture des connaissances), et les règles qui s'appliquent toujours. C'est la pièce à plus fort effet de levier car elle est lue à chaque prompt sans que Tom ait à se répéter. - **Une base de connaissances personnelle.** Un endroit structuré et récupérable pour le matériel de référence que l'agent peut utiliser au lieu de le redériver ou de l'halluciner. Le matériel accumulé est un fossé ; une structure de récupération bien organisée par-dessus se compose à chaque utilisation. - **Des compétences réutilisables pour tout ce qui se répète.** Si Tom fait quelque chose une deuxième fois, cela devrait devenir une compétence plutôt qu'un cas unique réexpliqué. - **Des garde-fous appliqués au niveau des outils, pas seulement au niveau du prompt.** Une instruction uniquement dans le prompt comme « ne touchez pas aux modèles destinés aux clients sans demander » est une suggestion que le modèle peut outrepasser sous pression. La même règle en tant que restriction réelle d'outil (chemin bloqué, porte d'autorisation) ne peut pas l'être. Classez les règles en trois niveaux : - **Toujours faire** - sûr en pilote automatique, pas besoin de demander - **Demander d'abord** - nécessite une vérification rapide avant de procéder - **Ne jamais faire** - bloqué en dur, pas seulement découragé ### Ce qu'une configuration d'environnement doit contenir **Ajouts proposés au CLAUDE.md** (ou un CLAUDE.md complet s'il n'en existe pas), **une courte liste de ce qui appartient à la base de connaissances** vs. ce qui peut être laissé de côté, **toute(s) nouvelle(s) compétence(s) à extraire**, et **les niveaux de garde-fous** remplis pour le projet spécifique. --- ## Formats de sortie ### Sortie du mode coaching Renvoyez le prompt/les instructions améliorés directement dans le chat, dans un bloc de code délimité facile à copier. En dessous, une courte note à puces (3-5 lignes maximum) sur ce qui a changé et de quelle couche cela provient - assez pour montrer que l'amélioration n'était pas cosmétique, pas une conférence. Ne créez pas de fichiers pour ce mode sauf demande. ### Sortie du mode configuration complète Créez trois documents légers avec create_file : - **SPEC.md** - objectif, portée, décisions de jugement, contraintes - **VERIFIER.md** - critères de réussite/échec, qui vérifie, que se passe-t-il en cas d'échec - **Une section environnement** - soit un nouveau CLAUDE.md, soit un ajout clairement marqué au CLAUDE.md existant de Tom, plus les niveaux de garde-fous Lisez references/templates.md pour les modèles de remplissage complets et un exemple travaillé avant de les rédiger - n'improvisez pas la structure de zéro à chaque fois. Présentez les trois ensemble avec un court résumé de ce qui se trouve dans chacun, et signalez explicitement tout endroit où une décision de jugement a été prise que Tom devrait revérifier plutôt que de décider silencieusement à sa place. --- ## Le point essentiel Ne laissez rien de ce qui précède devenir du travail superficiel qui produit des documents impressionnants pendant que la compréhension réelle du projet par Tom reste mince. L'objectif des trois couches est que Tom reste celui qui sait pourquoi le projet compte et à quoi ressemble « bien » - les couches rendent simplement cette connaissance suffisamment lisible pour qu'un agent puisse agir de manière fiable. Si une spec, un verifier ou un document d'environnement remplit de l'espace plutôt que de capturer un jugement réel que Tom ferait réellement, coupez-le. --- ## Modèles pour le mode configuration complète Uniquement nécessaire lorsque kp-prompting fonctionne en mode configuration complète (voir SKILL.md). Remplissez-les en fonction du projet réel - ne laissez pas de crochets d'espace réservé dans les documents livrés. ### Modèle SPEC.md ```markdown # Spec : [Nom du projet/tâche] ## Objectif [La décision ou le résultat réel que cela sert - pas seulement la description de la tâche. Ex. pas « ajouter la répartition horaire à la logique d'enchère » mais « réduire les dépenses gaspillées pendant les heures historiquement à faible conversion sans aussi réduire le volume pendant les heures qui convertissent mais semblent juste lentes à un coup d'œil rapide. »] ## Portée **Dans le périmètre :** - [...] **Hors périmètre (pour l'instant) :** - [...] ## Décisions de jugement à signaler, pas à résoudre silencieusement - [Point ambigu spécifique - ex. « que se passe-t-il sur une campagne avec moins de 2 semaines de données : appliquer les références de catégorie immédiatement, ou attendre des données spécifiques à la campagne ? »] - [...] ## Contraintes **Non-négociables :** - [...] **Préférences (peuvent être échangées) :** - [...] ## Points de contrôle [Si la portée est grande : 2-4 points où Tom examine avant de continuer, plutôt qu'un seul gros transfert à la fin] 1. [...] 2. [...] ``` ### Modèle VERIFIER.md ```markdown # Verifier : [Nom du projet/tâche] ## Critères de réussite/échec [Spécifiques et vérifiables - pas « semble bien » ou « coupez les mauvaises heures. » Ex. « une heure n'est signalée pour une enchère réduite que si elle a au moins N leads d'historique et un CPA de plus de X% au-dessus de la moyenne du compte. »] - [ ] [critère 1] - [ ] [critère 2] ## Qui vérifie - [ ] Auto-vérification par l'agent par rapport aux critères ci-dessus - [ ] Passage critique du second modèle (modèle différent ou contexte frais, évaluant par rapport à la spec) - [ ] Signal externe : [succès du déploiement / suite de tests / correspond à un exemple historique connu comme bon] ## En cas d'échec [Que se passe-t-il si un critère échoue - réessayer avec quel retour spécifique, ou s'arrêter et signaler à Tom avant de continuer] ``` ### Modèle d'ajout Environment / CLAUDE.md ```markdown ## [Nom du projet/fonctionnalité] **Ce que c'est :** [une ou deux phrases] **Où se trouvent les choses :** [chemins de fichiers, sources de données, documents connexes] **Compétences pertinentes ici :** [compétences existantes à utiliser, ou « candidat pour une nouvelle compétence : X »] **Règles :** - Toujours faire : [...] - Demander d'abord : [...] - Ne jamais faire : [...] ``` --- ## Exemple travaillé **Tâche :** Tom demande de « spécifier l'ajout de règles de répartition horaire automatisées à la compétence d'optimisation de campagne. » ### Extrait de SPEC.md : **Objectif :** pas « ajouter une fonctionnalité de répartition horaire » - l'objectif réel est de réduire les dépenses gaspillées pendant les heures historiquement à faible conversion sans aussi réduire le volume pendant les heures qui convertissent mais semblent juste lentes à un coup d'œil brut. **Décision de jugement signalée :** que se passe-t-il sur une toute nouvelle campagne avec moins de 2 semaines de données. La spec énonce explicitement si la répartition horaire s'applique immédiatement en utilisant les références de catégorie ou attend suffisamment d'historique spécifique à la campagne, plutôt que de laisser l'agent en choisir une silencieusement. **Point de contrôle :** la logique de règle est examinée par rapport à un compte réel (déjà connu) avant d'être câblée pour s'appliquer automatiquement aux campagnes en direct. ### Extrait de VERIFIER.md : **Critère :** « une heure n'est signalée pour une enchère réduite que si elle a au moins 15 leads d'historique et un CPA de plus de 25% au-dessus de la moyenne du compte » - vérifiable, pas « coupez les mauvaises heures. » **Vérification :** le critique du second modèle examine la règle proposée par rapport à 2-3 comptes connus pour les faux positifs (heures qui semblent mauvaises sur le seul volume mais sont correctes sur le CPA) avant qu'elle ne soit suggérée pour un client en direct. ### Extrait de l'ajout CLAUDE.md : **Toujours faire :** extraire et résumer les données de performance horaires, signaler les heures qui franchissent le seuil **Demander d'abord :** appliquer une nouvelle règle de répartition horaire à une campagne client en direct pour la première fois **Ne jamais faire :** modifier les multiplicateurs d'enchère sur un compte client sans que les critères du verifier soient satisfaits et l'approbation de Tom d'abord --- **Remarquez ce que cet exemple fait :** il ne gonfle pas le document avec du remplissage générique (« garantir une haute qualité, » « suivre les meilleures pratiques »). Chaque ligne est une décision spécifique qui serait autrement prise silencieusement et de manière incorrecte. C'est le véritable travail des trois couches ensemble.