doubt-driven-development

Sur le point de prendre une décision architecturale en situation d'incertitude

Sur le point de valider du code non trivial

Sur le point d'affirmer un fait non évident (« c'est sans risque », « ça s'adapte à l'échelle », « ça correspond au cahier des charges »)

Travailler sur du code que vous ne comprenez pas entièrement

Quand NE PAS l'utiliser :

• Opérations mécaniques (renommage, mise en forme, déplacement de fichiers)
• Suivre une instruction utilisateur claire et sans ambiguïté
• Lecture ou synthèse de code existant
• Modifications d’une seule ligne dont l’exactitude est évidente
• Opérations purement techniques (exécution de tests, listage de fichiers)
• L'utilisateur a explicitement privilégié la rapidité à la vérification

Si vous remettez en question chaque frappe, vous ne livrerez jamais rien. Cette compétence ne s'applique qu'aux décisions non triviales telles que définies ci-dessus.

Contraintes de chargement

Cette compétence est destinée à l’orchestrateur de la session principale, où l’étape 3 (DOUTE, détaillée ci-dessous) peut donner lieu à la création d’un réviseur dans un nouveau contexte.

• N’ajoutez PAS cette compétence aux compétences d’un persona : frontmatter. Un persona qui suivrait l’étape 3 créerait un autre persona — ce qui constitue un anti-modèle d’orchestration explicitement interdit par references/orchestration-patterns.md (« les personas n’invoquent pas d’autres personas »).
• Si vous vous retrouvez à appliquer cette compétence depuis le contexte d’un sous-agent (où le code Claude empêche la création imbriquée de sous-agents) : la solution privilégiée consiste à signaler à l’utilisateur que le mode « doubt-driven » ne peut pas s’exécuter de manière imbriquée et à laisser la session principale gérer cela. En dernier recours uniquement, il existe une solution de repli dégradée basée sur l’auto-questionnement : réécrivez ARTIFACT + CONTRACT sous la forme d’une nouvelle auto-invite, en établissant une séparation mentale nette par rapport à votre raisonnement précédent, puis suivez les étapes 1 à 5. Il ne s’agit pas d’une réévaluation dans un nouveau contexte (vous conservez votre propre contexte), donc marquez le résultat comme dégradé et privilégiez l’escalade dès que l’utilisateur est joignable.

Le processus

Copiez cette liste de contrôle lorsque vous appliquez cette compétence :

Cycle de doute :
- [ ] Étape 1 : AFFIRMATION — rédaction de l’affirmation + explication de son importance
- [ ] Étape 2 : EXTRACTION — isolation de l’artefact + du contrat, suppression du raisonnement
- [ ] Étape 3 : DOUTE — appel d’un réviseur en contexte frais avec une invite contradictoire
- [ ] Étape 4 : RÉCONCILIATION — classification de chaque résultat par rapport au texte de l’artefact
- [ ] Étape 5 : ARRÊT — condition d’arrêt remplie (résultats triviaux, 3 cycles ou annulation par l’utilisateur)

Étape 1 : AFFIRMATION — Mettre en évidence ce qui ressort

Formulez la décision en deux ou trois lignes :

AFFIRMATION : « La nouvelle couche de mise en cache est thread-safe dans le cadre de la
        charge de travail à forte intensité de lecture décrite dans le cahier des charges. »
POURQUOI C'EST IMPORTANT : une condition de concurrence à cet endroit corrompt les données utilisateur et est
                  difficile à détecter lors des tests d'assurance qualité.

Si vous ne parvenez pas à formuler cette affirmation de manière aussi concise, il s’agit d’une intuition, et non d’une décision. Exprimez-la clairement avant de l’examiner en détail.

Étape 2 : EXTRAIRE — La plus petite unité révisable

Un réviseur qui aborde le sujet avec un regard neuf a besoin de l ’artefact et du contrat, pas du parcours.

• Code : le diff ou la fonction — pas le fichier entier
• Décision : la proposition en 3 à 5 phrases, ainsi que les contraintes auxquelles elle doit satisfaire
• Affirmation : l’affirmation ainsi que les preuves censées l’étayer (à distinguer du bloc « CLAIM » de l’étape 1, qui correspond à l’hypothèse de l’orchestrateur soumise à examen)

Simplifiez votre raisonnement. Si vous présentez des conclusions, on vous renverra une validation de ces conclusions. L’unité doit être suffisamment petite pour qu’un relecteur puisse la garder à l’esprit en une seule lecture — s’il s’agit d’une pull request de 500 lignes, décomposez-la d’abord.

Étape 3 : DOUTE — Faites appel à un relecteur ayant un regard neuf

La consigne donnée au relecteur doit être contradictoire. Le cadre de la question détermine la réponse.

Révision contradictoire. Trouvez ce qui ne va pas dans cet artefact.
Partez du principe que l’auteur est trop sûr de lui. Recherchez :
- Les hypothèses non formulées
- Les cas limites non traités
- Les couplages cachés ou les états partagés
- Les failles potentielles du contrat
- Les conventions existantes que cela pourrait enfreindre
- Les modes de défaillance en cas d’entrée inattendue

NE validez PAS. NE résumez PAS. Identifiez les problèmes, ou indiquez
explicitement que vous n’en avez trouvé aucun après un examen approfondi.

ARTÉFACT : 
CONTRAT : 

Ne transmettez que l’ARTIFACT et le CONTRAT. Ne transmettez PAS la CLAIM. Le fait de communiquer votre conclusion au réviseur l’incite à se rallier à votre avis. Le réviseur doit déterminer de manière indépendante si l’artifact satisfait au contrat.

Dans Claude Code, les évaluateurs basés sur les rôles dans agents/ partent par conception d’un contexte isolé et sont utilisables ici — voir agents/ pour la liste et la correspondance par domaine.

La prompt adversaire ci-dessus prévaut sur le modèle de réponse par défaut du persona. Les personas tels que « code-reviewer » sont conçus pour produire des verdicts équilibrés comportant à la fois des points forts et des points faibles ; une approche fondée sur le doute nécessite une sortie se limitant aux problèmes. Collez la consigne antagoniste mot pour mot dans l’invocation afin qu’elle remplace la réponse par défaut du personnage. Si la structure de réponse d’un personnage ne peut pas être remplacée proprement, recourez à un sous-agent générique avec la consigne antagoniste.

Escalade inter-modèles

Un réviseur utilisant un seul modèle partage les angles morts de l’auteur d’origine — un modèle plus « froid », doté d’une architecture différente, permet de les détecter. Le mode « Doubt-driven » est déjà activé par défaut pour les décisions non triviales ; dans ce cadre, proposer l’escalade inter-modèles fait partie de la valeur ajoutée de la compétence, et ne constitue pas une friction facultative.

Sessions interactives : toujours les proposer. Ne jamais les ignorer en silence.

Étape 1 : Demander à l’utilisateur

Après l’examen du modèle unique à l’étape 3 ci-dessus, mais avant RECONCILE, faites une pause et demandez :

« L'examen par un seul modèle est terminé. Souhaitez-vous obtenir un deuxième avis en comparant plusieurs modèles ? Options : Gemini CLI, Codex CLI, examen externe manuel (vous collez le contenu ailleurs) ou ignorer. »

Cette question est obligatoire à chaque cycle interactif de vérification — même pour les éléments qui semblent présenter peu d'enjeux. C'est l'utilisateur — et non l'agent — qui décide si le coût en vaut la peine. Le rôle de l'agent est de proposer ce choix.

Étape 2 : si l’utilisateur choisit une interface CLI — vérifier, puis exécuter

1. Vérifiez que l’outil se trouve dans le PATH (qu’il s’agisse de gemini ou de codex).
2. Testez son fonctionnement (gemini --version ou équivalent) avant de transmettre l’invite complète — un binaire obsolète ou défectueux pourrait passer le test, mais échouer avec une entrée réelle.
3. Confirmez l’invocation exacte avec l’utilisateur, y compris les options requises, l’authentification et les variables d’environnement (par exemple, les clés API). Les implémentations varient ; ne faites jamais de suppositions.
4. Transmettez UNIQUEMENT l’ARTIFACT + le CONTRAT + la ligne de commande adversaire. Pas de contexte de session, pas de CLAIM.
5. Faites attention à l’échappement du shell. Si l’artefact contient des guillemets, des $(...) ou des guillemets inversés, privilégiez stdin (echo … | gemini) ou un heredoc plutôt que -p "…" en ligne. En cas de doute, demandez à l’utilisateur de confirmer l’invocation avant de l’exécuter.
6. Transférez la sortie à l’étape 4 (RECONCILE).

N’interpolez jamais l’artefact dans un argument entre guillemets de shell. Les invites de code, de Markdown et de révision contiennent systématiquement des guillemets inversés, des $(...) et des guillemets qui risquent soit de tronquer l’invite, soit d’exécuter le shell intégré. Écrivez l’invite complète dans un fichier et redirigez-la via stdin.

Exemples de formes (vérifiez les options par rapport à votre outil installé — la syntaxe diffère selon les implémentations et les versions) :

# Écrivez d’abord la ligne de commande adversaire + ARTIFACT + CONTRACT dans un fichier temporaire.
# Transférez-la ensuite via l’entrée standard (stdin) afin que les métacaractères du shell présents dans l’artefact restent inactifs.

# Codex (le bac à sable en lecture seule empêche l’interface en ligne de commande d’écrire dans votre espace de travail) :
codex exec --sandbox read-only -C  - < /tmp/doubt-prompt.md

# Gemini (« --approval-mode plan » est en lecture seule ; « -p "" » active le mode non interactif
# et la consigne est lue depuis l’entrée standard) :
gemini --approval-mode plan -p "" < /tmp/doubt-prompt.md

Un bac à sable en lecture seule est l’élément clé : un artefact de doute peut lui-même contenir des instructions (injection intentionnelle ou accidentelle de l’invite) que l’interface CLI inter-modèles exécuterait autrement sur votre espace de travail.

Étape 3 : Si l’interface CLI n’est pas disponible ou échoue

Signalez explicitement l’échec. Proposez : de l’exécuter manuellement, d’essayer un autre outil ou de passer à l’étape suivante. Ne basculez pas silencieusement vers le mode mono-modèle — l’utilisateur doit savoir que le traitement inter-modèles n’a pas eu lieu.

Étape 4 : Si l'utilisateur ignore cette étape

Signalez cette omission dans le résultat (« Poursuite de l'analyse avec les résultats d'un seul modèle uniquement ») et passez à l'étape RECONCILE. Il est acceptable de sauter cette étape ; en revanche, il ne faut pas le faire sans le signaler.

Contextes non interactifs (CI, /loop, autonomous-loop, exécutions planifiées) :

• L'analyse inter-modèles est ignorée, et cette omission doit être signalée dans la sortie : « Analyse inter-modèles ignorée : contexte non interactif. »
• N’invoquez jamais une interface CLI externe sans l’autorisation explicite de l’utilisateur — il s’agit d’une propriété de sécurité essentielle.

Le « Cross-model » entraîne un surcoût, une latence et une fragilité de l’outil. L’agent propose ce choix à chaque cycle ; l’utilisateur décide si cet artefact le justifie.

Étape 4 : RÉCONCILIATION — Intégrer les résultats

Le résultat fourni par le réviseur est une donnée, pas un verdict. C’est vous qui restez le chef d’orchestre. Relisez le texte de l’artefact à la lumière de chaque constat avant de le classer : approuver aveuglément le réviseur revient au même que de l’ignorer.

Pour chaque constat, classez-le selon l’ordre de priorité suivant (la première catégorie correspondante l’emporte) :

1. Mauvaise interprétation du contrat — le relecteur a signalé un élément précisément parce que le CONTRAT que vous avez fourni n’était pas clair ou était incomplet. Corrigez d’abord le contrat, puis reclassez-le lors du cycle suivant.
2. Valide + actionnable — problème réel nécessitant une modification de l’artefact. Modifiez-le, puis recommencez le cycle.
3. Compromis valable — le problème est réel, mais le coût de sa correction dépasse celui de son acceptation. Documentez explicitement ce compromis afin que l’utilisateur en prenne connaissance.
4. Faux positif — le réviseur a signalé un élément qui est en réalité correct dans un contexte dont il n’avait pas connaissance. Prenez-en note, passez à autre chose et posez-vous la question suivante : l’ajout de ce contexte au contrat aurait-il permis d’éviter ce faux signal ?

Un réviseur « frais » peut se tromper parce qu’il manque de contexte. Ne repoussez pas la décision simplement parce qu’il est « frais ».

Étape 5 : STOP — Boucle bornée, pas de récursivité

S'arrêter lorsque :

• l’itération suivante ne renvoie que des résultats insignifiants ou déjà pris en compte, ou
• 3 cycles sont terminés (transmettez à l'utilisateur, ne vous acharnez pas seul sur un quatrième), ou
• l'utilisateur demande explicitement de « le livrer »

Si, après 3 cycles, le relecteur continue de soulever des problèmes de fond, le produit n’est peut-être pas prêt. Signalez-le à l’utilisateur : trois cycles sans résolution constituent une information sur le produit, et non une raison de continuer à tourner en boucle.

Si 3 cycles sont « manifestement insuffisants » parce que l'artefact est volumineux : l'artefact est trop volumineux — revenez à l'étape 2 et décomposez-le. Ne relevez pas la limite.

Rationalisations courantes

Signaux d’alerte

• Lancer un réviseur dans un nouveau contexte pour un simple changement de nom ou de mise en forme d’une ligne
• Considérer la sortie du réviseur comme faisant autorité sans relire le texte de l’artefact
• Effectuer plus de trois cycles sans escalader le problème vers l’utilisateur
• Demander au relecteur « Est-ce que ça va ? » au lieu de « Trouvez les problèmes »
• Ignorer ses doutes sous la pression du temps lors d’une décision à fort enjeu
• Relancer un contexte neuf sur un artefact inchangé (vous obtiendrez les mêmes résultats ; vous ne faites que gagner du temps)
• Le « théâtre du doute » (signal vérifiable): sur au moins deux cycles où le relecteur a soulevé des constatations substantielles, aucune n’a été classée comme nécessitant une action. Vous validez, vous ne remettez pas en question. Arrêtez-vous et remontez l’information.
• Ne douter qu’après avoir validé — c’est du /review, pas du développement guidé par le doute
• Codage en dur d’un appel CLI externe sans vérifier auprès de l’utilisateur que l’outil existe, qu’il est configuré et qu’il accepte cette syntaxe exacte
• Ignorer silencieusement la vérification inter-modèles dans un cycle de doute interactif. Même si cela n’est pas recommandé, l’option doit être visible. Ignorer est acceptable ; ignorer en silence ne l’est pas.
• Recourir silencieusement à une solution de secours lorsqu’une CLI externe renvoie une erreur ou est manquante — signaler l’échec et laisser l’utilisateur rediriger
• Supprimer le contrat de la contribution du réviseur
• Transmettre l’AFFIRMATION au réviseur (biais en faveur de l’accord)

Interaction avec d’autres compétences

• code-review-and-quality / /review: complémentaire. /review correspond à un verdict a posteriori sur la PR ; l’approche « guidée par le doute » s’applique en temps réel, à chaque décision. Utilisez les deux.
• source-driven-development: le SDD vérifie les faits concernant les frameworks par rapport à la documentation officielle. L’approche « doubt-driven » vérifie votre raisonnement concernant l’artefact. Le SDD vérifie que l’API existe ; l’approche « doubt-driven » vérifie que vous l’avez utilisée correctement conformément au contrat.
• développement-piloté-par-les-tests: l’étape RED du TDD concrétise le doute — un test qui échoue est une tentative de réfutation. Lorsque le TDD s’applique, ce test qui échoue constitue l’étape du doute pour les affirmations comportementales.
• débogage-et-récupération-après-erreur: lorsque le relecteur met en évidence un véritable mode de défaillance, passez à la compétence de débogage pour localiser et corriger le problème.
• Règles d’orchestration du dépôt (references/orchestration-patterns.md) : cette compétence s’organise à partir de la session principale. Une persona appelant une autre persona constitue l’anti-modèle B — voir « Contraintes de chargement » ci-dessus.

Vérification

Après avoir appliqué le développement guidé par le doute :

• Chaque décision non triviale (selon la définition ci-dessus) a été explicitement désignée comme une « affirmation » avant d’être validée
• Au moins une revue dans un nouveau contexte par artefact non trivial (un test échoué produit par l’étape RED du TDD satisfait cette exigence pour les revendications comportementales, conformément à la section « Interaction avec d’autres compétences »)
• Le réviseur a reçu l’ARTÉFACT + le CONTRAT — et NON l’AFFIRMATION, ni votre raisonnement
• La consigne donnée au réviseur était de nature contradictoire (« trouver des problèmes »), et non de validation (« est-ce que c'est bien »)
• Les résultats ont été classés par rapport au texte de l’artefact (et non pas approuvés sans examen) selon l’ordre de priorité suivant : mauvaise interprétation du contrat / actionnable / compromis / bruit
• Une condition d’arrêt a été remplie (constatations insignifiantes, 3 cycles ou annulation par l’utilisateur)
• En mode interactif, la comparaison inter-modèles a été explicitement proposée à l’utilisateur (quelle que soit l’importance de l’artefact) et la réponse a été prise en compte dans le résultat
• En mode non interactif, la vérification inter-modèles a été ignorée et cette omission a été signalée
• Toute invocation externe de l’interface en ligne de commande (CLI) était précédée d’une vérification du chemin d’accès (PATH), d’un test de bon fonctionnement du binaire, d’une confirmation de la syntaxe avec l’utilisateur et d’une autorisation explicite d’exécution