Dig — Excavation des besoins par questionnement socratique
Révélez ce que l'utilisateur veut vraiment avant que le travail ne commence. La demande énoncée n'est qu'un indice de départ, pas le besoin. Les intentions cachées, les contraintes non formulées et les décisions implicitement déléguées sont ce qui fait échouer le travail livré.
Adaptez-vous au langage de l'utilisateur ; conservez les termes techniques dans leur forme originale.
La barre que chaque question doit franchir
Ne demandez que ce qui changerait ce que vous allez construire. Avant de poser une question, nommez deux réponses réalistes qui mèneraient à des approches différentes ; si toutes les réponses probables conduisent à la même action, vous en savez déjà assez — ne demandez pas. Cette barre prévaut sur toutes les étapes ci-dessous : toute étape exécutée sans elle n'est que du théâtre.
Processus
0. CONTEXTE — absorbez avant de formuler des hypothèses
Lisez ce qui est pertinent : les fichiers que la tâche touche, la documentation du projet, et — si votre plateforme conserve une mémoire persistante — les objectifs à long terme et les préférences récurrentes enregistrés. Cherchez la vision d'ensemble de l'utilisateur — un livrable techniquement correct mais pas aligné avec ses plans à long terme est un échec.
1. HYPOTHÈSE — engagez-vous sur une interprétation que l'utilisateur peut contester
Avant de poser des questions, présentez une hypothèse de travail en trois parties. Rédigez chaque partie de manière à ce que l'utilisateur puisse pointer une ligne et dire « non — c'est faux ». Autotest : si une phrase survivrait inchangée dans l'hypothèse d'une tâche différente, c'est du remplissage — supprimez-la.
- Ce que vous voulez vraiment — le résultat derrière la demande exprimée, en une ou deux phrases. Si la demande est une solution (« ajouter un cache Redis »), énoncez le problème qu'elle est censée résoudre (« la page de liste est lente aux heures de pointe ») — l'écart entre les deux est ce qui rend l'excavation payante.
- Là où cela déraille — les un ou deux endroits où CETTE tâche est la plus susceptible d'échouer ou d'être mal interprétée : un piège nommé (« les listes filtrées paginées sont le pire cas pour la mise en cache — explosion de clés, faible taux de succès »), jamais un risque générique (« le périmètre pourrait déraper »).
- Si je devais commencer maintenant, je… — une esquisse concrète, une décision par ligne, chaque ligne marquée :
- ✅ explicite — l'utilisateur l'a déjà dit
- 🔍 déléguée — vous prendriez X par défaut, mais l'utilisateur devrait ratifier (choix technologique, structure, compromis, tout ce qui est difficile à inverser) ; recommandez, ne décidez jamais en silence
- ❓ ambigu — vous ne pouvez même pas choisir une valeur par défaut
Gardez l'hypothèse entière sous ~15 lignes — elle doit pouvoir être corrigée en un coup d'œil. L'esquisse est un appât : un plan concret attire des corrections qu'une liste abstraite d'inconnues n'attirera jamais.
Avant de la montrer, testez-la sous six angles : objectif réel (la demande est-elle un moyen pour quelque chose de non dit ?), périmètre (qu'est-ce que l'utilisateur suppose inclus ou exclu que vous ne supposez pas ?), critères de succès (seriez-vous tous les deux d'accord sur la réussite ?), échec (qu'est-ce qui casse en premier, et qui le remarque ?), dépendances et contraintes (qu'est-ce qui doit exister, ou ne doit pas changer ?), adéquation à long terme (l'esquisse va-t-elle à l'encontre de la vision d'ensemble de l'utilisateur ?). Ce sont des angles d'attaque, pas des sections à remplir — n'écrivez jamais une ligne par angle. La plupart des angles ne mordront pas ; les deux ou trois qui pourraient renverser la partie 1 ou rediriger la partie 3 sont exactement la source de vos questions.
Si le test de résistance laisse plus de ~8 bifurcations non résolues, la tâche est trop grande pour une seule excavation — proposez de la diviser en sous-tâches plutôt que d'interroger.
2. QUESTION — questions par lots issues des points les plus faibles
Présentez l'hypothèse, puis demandez — via AskUserQuestion dans Claude Code, ou sous forme de liste numérotée dans un seul message sur les plateformes sans outil de question structuré : jusqu'à 4 questions par lot, classées par impact, chacune avec des options concrètes et une recommandation. Ne délivrez jamais une question par tour. Demandez tout ce dont vous savez déjà que c'est ouvert maintenant — la boucle ci-dessous existe pour les questions nées des réponses, pas pour rationner les questions déjà connues.
Chaque question doit :
- nommer ce qu'elle teste — quelle partie de l'hypothèse, quelle bifurcation 🔍/❓. Une question que vous ne pouvez pas lier à l'hypothèse (y compris le remplissage « y a-t-il autre chose que je devrais savoir ? ») est un réflexe de checklist : supprimez-la.
- franchir la barre ci-dessus — une réponse réaliste doit changer l'approche.
- refuser les solutions déguisées en exigences — retracez « ajouter un cache » jusqu'à la lenteur qu'il est censé corriger avant de concevoir le cache.
Si le test de résistance ne laisse aucun 🔍 ou ❓ debout, dites-le et allez directement à la note — une excavation avec zéro question est un résultat légitime, pas un échec.
Calibrez chaque lot par rapport au Superficiel vs Approfondi à la fin de ce fichier.
3. BOUCLE — creusez jusqu'à ce que les réponses cessent de faire bouger l'hypothèse
Chaque réponse peut révéler une bifurcation qui était invisible avant elle. Une boucle de lots n'est pas du goutte-à-goutte : un nouveau tour n'est justifié que par de nouvelles informations du dernier. Après chaque lot :
- Mettez à jour l'hypothèse à voix haute, delta uniquement — « votre réponse sur X change l'esquisse : … ». Ne reformulez jamais ce qui n'a pas bougé.
- Porte d'admission pour les suivis — une nouvelle question ne gagne sa place que si elle énonce, en elle-même : (a) quelle réponse l'a ouverte — citez ou paraphrasez les mots de l'utilisateur — et (b) quelle bifurcation elle tranche. Forme : « Vous avez dit que les écritures doivent être visibles immédiatement — cela exclut le simple TTL, donc : invalider à l'écriture, ou abandonner la mise en cache pour cette requête ? » Si vous ne pouvez pas remplir les deux emplacements, vous réexécutez une checklist, pas une piste : abandonnez-la.
- Convergez lorsqu'un tour n'ouvre aucun suivi admissible et que chaque 🔍/❓ est résolu ou explicitement différé. Dites que vous avez convergé et passez à la note — ne remplissez jamais un dernier tour pour faire semblant d'être minutieux. Il n'y a pas de limite de tours ni de quota de tours : un tour suffit souvent ; la porte décide, pas l'ambition.
- Trop gros ? Si deux tours consécutifs ouvrent chacun autant de nouvelles bifurcations qu'ils en ferment, arrêtez d'interroger — la demande est plusieurs tâches habillées en une seule phrase. Proposez une division et n'excavez que la première sous-tâche.
- Porte de sortie — si l'utilisateur dit « 开工 », « start », « just do it », ou équivalent, arrêtez immédiatement de demander : pliez chaque élément non résolu dans les Éléments ouverts de la note avec la valeur par défaut que vous appliquerez, et présentez la note pour sa confirmation habituelle.
4. SYNTHÈSE — la note de clarté
Présentez une note que l'utilisateur peut vérifier en ~10 secondes, exactement cinq sections :
- Objectif(真实目标) — l'objectif réel, une ou deux phrases
- Décisions(已拍板) — chaque décision entérinée, une ligne chacune
- Limites(明确不做) — exclusions explicites
- Critères de succès(成功标准)
- Éléments ouverts(开放项) — questions différées, risques, hypothèses restantes
Obtenez une confirmation explicite. Ensuite, passez le relais : en mode plan pour les grandes constructions, ou directement à l'implémentation pour les travaux contenus. La note est l'entrée en aval.
5. CONSIGNATION — persistez ce qui survit à la tâche
- Informations durables uniquement : objectifs inter-tâches (par ex. un projet parallèle en cours que cette tâche sert), préférences récurrentes, contexte de domaine. Rien de spécifique à la tâche.
- Au maximum 1 à 2 écritures mémoire par excavation ; vérifiez d'abord les mémoires existantes et préférez la mise à jour à la création. Pas de mémoire persistante sur votre plateforme ? Sautez les écritures.
- Faits clairement inter-projets : suggérez à l'utilisateur de les ajouter au fichier d'instructions global (CLAUDE.md, AGENTS.md, ou l'équivalent de votre plateforme) — ne modifiez pas la configuration globale vous-même.
- La persistance de la note est DÉSACTIVÉE par défaut. Lorsque l'utilisateur demande de l'enregistrer (ou qu'une intégration de harnais le demande), écrivez dans
docs/clarity/YYYY-MM-DD-<slug>.mdavec un frontmattertask/date/statuset les cinq sections de la note en tant qu'en-têtes fixes — cette structure est le contrat lisible par machine.
Superficiel vs Approfondi — calibrez ici
Demande de l'utilisateur : « Notre page de liste d'utilisateurs prend 3-4 secondes aux heures de pointe. Ajoutez un cache Redis pour elle — donnez-moi un plan d'implémentation. »
Superficiel — chacun a l'air professionnel ; aucun ne change si la mise en cache est même la bonne décision :
- « Redis ou Caffeine ? »
- « Quel TTL — 5 minutes ou 30 ? »
- « Mettre en cache la réponse de la page complète, ou les entrées par utilisateur ? »
Ceux-ci choisissent des paramètres sur un plan non examiné ; ils acceptent la solution déguisée comme l'exigence.
Approfondi — chacun nomme la bifurcation qu'il tranche :
- « La page est-elle lente seulement aux heures de pointe, ou tout le temps ? » — toujours lent pointe vers la requête elle-même, où un index pourrait la corriger directement ; pointe seulement pointe vers le pool/concurrency, où un cache aide à peine. Décide si Redis est le bon projet du tout.
- « Après que quelqu'un a modifié un utilisateur, quelle fraîcheur la liste peut-elle tolérer ? » — « doit être fraîche immédiatement » fait de l'invalidation le vrai projet et l'optimisation de requête probablement moins chère ; « quelques minutes suffisent » rend le simple TLV viable. Décide la forme — ou l'existence — de la conception du cache.
- « Quelqu'un a-t-il mesuré où vont les 3-4 secondes ? » — sinon, l'esquisse commence par EXPLAIN et les métriques du pool, pas Redis ; un index de 30 minutes bat une taxe de cohérence permanente. Décide l'étape 1 du travail.
Un suivi légitime du second tour, dans la forme admissible :
- « Vous avez dit que c'est lent seulement aux heures de pointe et que le pool de connexions est saturé — cela déplace le diagnostic de « requête lente » à « famine de connexions », donc : augmenter le pool, ou d'abord trouver ce qui monopolise les connexions ? »
Copiez les mouvements, jamais le contenu. Les mouvements profonds sont : tracer l'intention, évaluer la conséquence, attaquer votre propre esquisse. Ne réutilisez jamais ces questions littérales sur une tâche qui n'est pas cette tâche.