Grill Me — Compréhension partagée par interrogation systématique
Philosophie
Le but du grillage est de construire une compréhension partagée entre l'agent et l'utilisateur. Chaque plan contient des hypothèses implicites, des contraintes non énoncées et des décisions ambiguës. Le grillage parcourt chaque branche de l'arbre de décision, une par une, jusqu'à ce que les deux parties soient parfaitement alignées.
L'objectif est zéro hypothèse non examinée avant le début de l'implémentation.
Directives principales
- Utilisez AskUserQuestion pour chaque question. Toutes les questions d'interrogation doivent passer par l'outil
AskUserQuestion. Ne produisez jamais une question sous forme de texte brut. - Regroupez par domaine. Regroupez jusqu'à 4 questions connexes dans le même domaine d'interrogation en un seul appel
AskUserQuestion. Ne mélangez jamais des questions de domaines différents dans un même appel. - Commencez par votre recommandation. Votre réponse recommandée est toujours la première option, avec
(Recommandé)ajouté au libellé. - Explorez avant de demander. Si une question peut être répondue en lisant la base de code, en lisant la documentation ou en vérifiant les motifs existants — faites-le plutôt que de demander. Ne posez à l'utilisateur que des questions qui nécessitent son jugement.
- Résolvez les dépendances dans l'ordre. Certaines décisions dépendent d'autres. Identifiez la chaîne de dépendances et résolvez d'abord les décisions en amont.
- Suivez tout avec des enregistrements structurés. Tenez un journal des décisions sous forme de tableau structuré. Pour chaque question résolue, enregistrez : domaine, sujet (en-tête), libellé de l'option choisie, et tout texte personnalisé si 'Autre' a été choisi. Présentez le journal dans le contexte de la conversation — pas d'E/S de fichier.
- Aucune hypothèse ne survit. Si quelque chose est implicite mais non dit, mettez-le en surface. Si quelque chose semble évident, confirmez-le. Une compréhension partagée signifie un accord explicite, pas un silence confortable.
- Restez concret. Formulez les questions autour de comportements spécifiques, de flux de données et de résultats visibles par l'utilisateur — pas de concepts abstraits.
Configuration pré-interrogation
Avant de poser des questions, construisez le contexte en silence :
- Lisez le plan ou le document de conception que l'utilisateur souhaite voir griller
- Explorez la base de code pour les motifs existants, les contraintes et le code pertinent
- Vérifiez l'historique git récent pour le contexte du travail en cours
- Lisez project.md et CLAUDE.md pour les conventions du projet
Présentez ensuite un bref résumé de ce que vous comprenez jusqu'à présent, organisé par domaines d'interrogation. Cela donne à l'utilisateur la possibilité de corriger les malentendus majeurs avant de plonger dans le questionnement branche par branche.
Domaines d'interrogation
Travaillez à travers les domaines définis dans references/interrogation-domains.md. Adaptez l'ordre au plan — commencez par le domaine le plus central à ce qui est construit et élargissez-vous. Sautez les domaines clairement non pertinents.
Processus d'interrogation
1. Lisez et résumez votre compréhension du plan
2. L'utilisateur confirme ou corrige le résumé
3. Pour chaque domaine d'interrogation (classé par pertinence) :
a. Identifiez tous les points de décision et hypothèses dans ce domaine
b. Regroupez les points de décision connexes en lots de 4 questions maximum
c. Pour chaque lot, invoquez un seul appel AskUserQuestion
(recommandation en premier pour chaque question). Enregistrez toutes les options choisies.
d. Après avoir résolu tous les points d'un domaine, résumez les décisions prises
Présentez les décisions du domaine sous forme de lignes dans le format de tableau structuré.
4. Après avoir couvert tous les domaines :
- Présentez le journal complet des décisions sous forme de tableau structuré :
| # | Domaine | Sujet | Décision | Notes |
|---|---------|-------|----------|-------|
| 1 | Intention | Objectif | Autre | Tableau de bord interne pour l'équipe Ops, pas orienté client |
- Signalez tout élément non résolu ou différé
- Demandez si un domaine doit être revisité
Format des questions
Chaque question DOIT être posée via l'outil AskUserQuestion. Structurez chaque appel comme suit :
{
"question": "Quand l'API Oura renvoie une 429, comment devons-nous gérer la limitation de débit ?",
"header": "Limites",
"options": [
{
"label": "Backoff exponentiel (Recommandé)",
"description": "Réessayer avec backoff exponentiel (1s, 2s, 4s). Gère les limites transitoires avec élégance et correspond au motif de réessai déjà utilisé dans src/api_client.py."
},
{
"label": "Mettre en file d'attente pour la prochaine exécution",
"description": "Ignorer la demande et l'ajouter à la prochaine exécution planifiée. Plus simple mais retarde les données d'un cycle."
}
],
"multiSelect": false
}
Dépend de : Indiquez toutes les décisions antérieures sur lesquelles cela s'appuie dans le texte de la question, ou mentionnez « Aucune dépendance » si indépendant.
Exemple de questions regroupées
{
"questions": [
{
"question": "Quelle est la cible de déploiement principale ?",
"header": "Déploiement",
"options": [
{
"label": "Docker + ECS (Recommandé)",
"description": "Correspond à l'infrastructure existante. Le pipeline de déploiement existe déjà."
},
{
"label": "Kubernetes",
"description": "Plus flexible mais nécessite une nouvelle configuration d'infrastructure."
},
{
"label": "Serverless",
"description": "Charge opérationnelle plus faible mais latence de démarrage à froid préoccupante."
}
],
"multiSelect": false
},
{
"question": "Quelles approches de surveillance devrions-nous inclure ?",
"header": "Monitoring",
"options": [
{
"label": "Journalisation structurée (Recommandé)",
"description": "Journaux JSON vers CloudWatch. Interrogeables et alertables."
},
{
"label": "Traces APM",
"description": "Traçage distribué pour la visibilité du flux de requêtes."
},
{
"label": "Métriques personnalisées",
"description": "Compteurs et jauges spécifiques à l'activité dans Datadog."
}
],
"multiSelect": true
}
]
}
Utilisation des aperçus
Utilisez le champ preview sur les options lorsque l'utilisateur a besoin de comparer visuellement des artefacts concrets — extraits de code, diagrammes d'architecture, formes de schémas ou exemples de configuration. Le contenu de l'aperçu s'affiche en markdown dans un bloc monospace avec comparaison côte à côte.
Quand utiliser les aperçus :
- Comparer deux motifs de code ou implémentations
- Montrer différentes formes de schémas ou structures de données
- Présenter des alternatives d'architecture avec des diagrammes ASCII
Contrainte : Les aperçus sont à sélection unique uniquement (multiSelect: false). Si vous avez besoin de sélection multiple, omettez les aperçus et utilisez des descriptions à la place.
Exemple avec aperçus :
{
"question": "Quel motif devrions-nous utiliser pour le pipeline de données ?",
"header": "Pipeline",
"options": [
{
"label": "Pipeline générateur (Recommandé)",
"description": "Évaluation paresseuse, économe en mémoire pour les grands ensembles de données.",
"preview": "def pipeline(source):\n for record in source:\n cleaned = clean(record)\n validated = validate(cleaned)\n yield validated"
},
{
"label": "Pipeline par lots",
"description": "Traite tous les enregistrements en une fois. Plus simple mais utilisation mémoire plus élevée.",
"preview": "def pipeline(source):\n records = list(source)\n cleaned = [clean(r) for r in records]\n validated = [validate(r) for r in cleaned]\n return validated"
}
],
"multiSelect": false
}
Règles pour poser des questions
- Utilisez AskUserQuestion pour chaque question. Point final.
- Première option = recommandation. La première option a toujours
(Recommandé)dans le libellé. - Regroupez les questions connexes. Regroupez jusqu'à 4 questions connexes du même domaine en un seul appel AskUserQuestion. Les questions de différents domaines doivent être des appels séparés.
- Respectez les contraintes de l'outil. 2 à 4 options par question. En-têtes de 12 caractères maximum. Utilisez
multiSelect: truelorsque les options ne s'excluent pas mutuellement (par exemple, « Quelles approches de test devrions-nous utiliser ? » ou « Quels domaines nécessitent une couverture ? »). - Filtrez les options. Lorsqu'il existe plus de 4 choix valides, présentez les 3 plus pertinents en fonction du contexte de la base de code. Les utilisateurs sélectionnent « Autre » pour tout ce qui n'est pas listé.
- Soyez spécifique. « Comment devrions-nous gérer les erreurs ? » est trop vague. « Quand l'API Oura renvoie une 429, devrions-nous réessayer avec backoff ou mettre en file d'attente pour la prochaine exécution ? » est spécifique.
- Montrez votre travail. Si votre recommandation est basée sur quelque chose que vous avez trouvé dans la base de code, référencez le fichier et la ligne.
- Acceptez la réponse. Lorsque l'utilisateur décide, enregistrez-la et passez à autre chose. Ne revenez pas sur la décision à moins qu'une décision ultérieure ne crée un conflit avec une précédente.
Solution de repli (AskUserQuestion indisponible)
Si AskUserQuestion n'est pas disponible dans l'environnement d'exécution, utilisez ce format texte :
[En-tête] — [Sujet]
[Énoncé clair de la question]
Recommandé : [Votre recommandation et pourquoi]
Alternatives :
- (A) [Option] — [compromis]
- (B) [Option] — [compromis]
Quand s'arrêter
Le grillage est terminé lorsque :
- Chaque domaine d'interrogation pertinent a été couvert
- Toutes les branches de décision ont été résolues ou explicitement différées
- L'utilisateur confirme la compréhension partagée