Grill With Docs : doter l'IA de mémoire de projet à l'aide du langage de domaine et de l'ADR

Mode d'échec : "L'IA est trop verbeuse"

Le deuxième mode d’échec dans le discours de Matt :

L'IA exprime une chose simple dans un tas de verbiage. C'est comme si vous parliez deux langues.

Cela n'a rien à voir avec la quantité de code, c'est un mauvais placement de vocabulaire. L'IA utilisera par défaut des termes généraux ("élément", "données", "gestionnaire"), et les termes réels du projet dans votre esprit peuvent être "Cours", "Version brouillon", "Leçon fantôme". L'IA ne sait pas que ces mots ont une signification spécifique dans votre projet, elle créera donc un tas de nouveaux mots synonymes autour d'eux. Le résultat est :

• Processus de réflexion interminable (évitez vos mots exclusifs)
• L'implémentation n'est pas alignée avec le design dans votre esprit (car ils ne sont pas dans le même espace sémantique)
• Non réutilisable d'une session à l'autre (le contexte doit être rétabli pour chaque conversation)

Théorie classique : le langage omniprésent de DDD

Matt a cité "Domain-Driven Design" d'Eric Evans. Ce livre a été publié en 2003 et proposait le concept de langage omniprésent :

Utilisez le même ensemble de termes pour connecter les experts du domaine, les développeurs et le code. Un mot dans les discussions sur les produits, les commentaires de code, les noms de variables, la documentation – cela doit signifier la même chose.

L'objectif de DDD est de faire ressembler le code au cerveau d'un expert du domaine. À l'ère de l'IA, il y a un nouveau rôle : Le LLM doit aussi être dans ce langage. Le LLM n'est pas présent à la réunion debout, ne peut pas voir les exigences du produit satisfaites et ne peut pas comprendre l'argot de votre groupe - il ne peut apprendre qu'à partir des documents que vous lui fournissez.

Matt en a fait une compétence : analyser la base de code pour en extraire les termes, générer un fichier de démarque CONTEXT.md, puis l'aligner avec les humains et l'IA.

L'évolution des compétences : du langage omniprésent aux grillades avec des documents

La première compétence s'appelait ubiquitous-language - elle ne faisait qu'une seule chose : analyser la base de code pour générer un glossaire. Mais Matt a découvert plus tard que simplement générer un document ne suffisait pas :

• La documentation sera obsolète : elle est générée aujourd'hui, le code est modifié demain et le glossaire n'a pas suivi.
• Les gens ne prendront pas l'initiative de le regarder : il serait mort si vous le mettiez là

Il l'a refactorisé en grill-with-docs, qui combinait trois choses :

1. Exigences en matière de torture (toutes les capacités héritées de grill-me)
2. Contester le glossaire existant : Le mot que vous avez prononcé est incompatible avec ce qui est écrit dans CONTEXT.md ? Signalez-le immédiatement
3. Mettre à jour les documents simultanément lors de la prise de décision : Les nouvelles conclusions obtenues au cours du processus de torture sont écrites en ligne dans CONTEXT.md ou créent un nouvel ADR.

Il s'agit d'un changement de paradigme, passant de « la génération de documents statiques » à « le dialogue, c'est la maintenance des documents ».

Texte intégral de la compétence

Structure de base de engineering/grill-with-docs/SKILL.md :

---
name: grill-with-docs
description: Grilling session that challenges your plan against the
  existing domain model, sharpens terminology, and updates
  documentation (CONTEXT.md, ADRs) inline as decisions crystallise.
---

<what-to-do>
Interview me relentlessly about every aspect of this plan until we
reach a shared understanding. Walk down each branch of the design
tree, resolving dependencies between decisions one-by-one. For each
question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question
before continuing.

If a question can be answered by exploring the codebase, explore the
codebase instead.
</what-to-do>

<supporting-info>

## Domain awareness

During codebase exploration, also look for existing documentation:

### File structure

Most repos have a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts.

## During the session

### Challenge against the glossary
When the user uses a term that conflicts with the existing language in
CONTEXT.md, call it out immediately.
"Your glossary defines 'cancellation' as X, but you seem to mean Y —
which is it?"

### Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise
canonical term.
"You're saying 'account' — do you mean the Customer or the User?
Those are different things."

### Discuss concrete scenarios
When domain relationships are being discussed, stress-test them with
specific scenarios.

### Cross-reference with code
When the user states how something works, check whether the code
agrees. If you find a contradiction, surface it.

### Update CONTEXT.md inline
When a term is resolved, update CONTEXT.md right there. Don't batch
these up — capture them as they happen.

### Offer ADRs sparingly
Only offer to create an ADR when all three are true:
1. Hard to reverse
2. Surprising without context
3. The result of a real trade-off

</supporting-info>

À quoi ressemble le vrai CONTEXT.md ?

Le propre référentiel course-video-manager de Matt donne un exemple complet de CONTEXT.md. Choisissons quelques termes pour avoir une idée :

Notez quelques choses :

1. Chaque terme est un gérondif ou un nom propre – et non une expression descriptive comme « état de la commande »
2. Chaque définition fait référence à d'autres termes (Cours → Version → Leçon → Vidéo) formant un réseau d'ontologie
3. Le champ code apparaît directement (fsStatus = "ghost") - Mappage 1:1 des documents et du code
4. Inclure des descriptions de décisions (« bloque la publication », « réaction en chaîne ») - pas seulement des noms, mais des règles

Lors de l'écriture du code, lorsque l'IA verra ce document, elle utilisera "Leçon fantôme" au lieu de "leçon sans fichier". Le code, les conversations et les messages de validation sont tous unifiés.

ADR : une fois créé

Il existe une contrainte importante dans la compétence :

Only offer to create an ADR when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives

La culture de l'ADR (Architecture Decision Record) est née du blog de Michael Nygard en 2011, mais de nombreuses équipes l'utilisent pour rédiger des ADR pour toutes les décisions : 18 ADR sur 20 gèrent des comptes. Matt Cette triangulation est un excellent outil : L'ADR n'est utile que si trois conditions sont remplies simultanément. Sinon, laissez-le être digéré dans CONTEXT.md et digéré dans le code.

Comment installer et utiliser

Conditions préalables : Exécutez d'abord /setup-matt-pocock-skills (il vous demandera où placer CONTEXT.md et où placer le répertoire ADR).

Appeler : /grill-with-docs

Processus typique :

1. Décrivez ce que vous voulez faire
2. /grill-with-docs
3. Claude scanne CONTEXT.md et docs/adr/ en premier, en chargeant les termes et décisions existants dans leur contexte
4. Commencez la torture, pendant le processus :

• Le mot que vous avez utilisé est en conflit avec CONTEXT.md → Signalez-le sur place
• Vous avez utilisé des mots vagues (par exemple, "Compte" peut être soit Client, soit Utilisateur) → Laissez-vous choisir l'un des deux et déposez-le dans le document
• Le comportement que vous avez mentionné est incompatible avec le code existant → signalez le conflit

5. Mettre à jour CONTEXT.md de manière synchrone lorsque la décision est prise (pas de retard, pas de traitement par lots)
6. Décisions clés irréversibles → Demander s'il faut générer un ADR

S'il n'y a pas encore de CONTEXT.md et de docs/adr/ dans le projet, il sera créé paresseusement : les fichiers ne seront générés que lorsque le premier terme devra être écrit et que le premier ADR devra être construit. Nous ne vous donnerons pas d’emblée un modèle vierge.

##Projets à contexte multiple (CONTEXT-MAP.md)

Si le projet est trop volumineux pour tenir dans un seul CONTEXT.md (par exemple, la commande et la facturation sont deux contextes délimités indépendants), vous pouvez placer CONTEXT-MAP.md dans le répertoire racine comme répertoire général :

/
├── CONTEXT-MAP.md                    ← 总目录
├── docs/adr/                         ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← 模块级决策
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

/grill-with-docs reconnaîtra automatiquement l'existence de CONTEXT-MAP.md et accédera au sous-répertoire correspondant. Il s'agit d'une implémentation directe du concept de contexte délimité dans DDD - les « ordres » dans chaque contexte peuvent avoir des significations différentes et sont conservés séparément pour éviter toute contamination.

La différence entre ## et grill-moi

Jugement simple et grossier :

• Scripts personnels, rédaction d'articles, cours d'enseignement → /grill-me
• De vrais projets qui nécessitent une maintenance à long terme → /grill-with-docs

Un avantage contre-intuitif : laissez l'IA apprendre à "se taire"

CONTEXT.md n'est pas uniquement destiné à l'IA, il est destiné aux futures sessions d'IA. Chaque fois qu'une nouvelle conversation démarre, Claude peut entrer instantanément dans le contexte du projet en lisant CONTEXT.md, économisant ainsi une longue intégration.

Ce qui est encore plus subtil, c'est que Matt a déclaré dans son discours qu'après avoir ajouté CONTEXT.md, il pouvait voir dans la trace de pensée de l'IA——

"Cela permet à l'IA de penser de manière moins verbeuse."

Pourquoi ? Car sans CONTEXT.md, l'IA doit constamment définir ses propres termes lorsqu'elle réfléchit - "l'utilisateur, j'entends par là la personne qui a commandé l'article, ci-après dénommé...". Avec CONTEXT.md il est dit directement « Client », la chaîne de réflexion est beaucoup plus courte et la réponse est plus rapide.

L'économie symbolique de LLM détermine : raccourcir le chemin de réflexion = production plus rapide, plus précise et moins chère. CONTEXT.md est le levier caché de cette efficacité.

Notes

CONTEXT.md sera considérablement modifié pour la première exécution. S'il existe déjà un CONTEXT.md manuscrit dans le projet, git stash d'abord ou laissez-le s'exécuter à sec avant de l'exécuter (vous pouvez ajouter une phrase dans l'invite "Listez d'abord le contenu à modifier, n'écrivez pas le fichier directement").

La modération ADR est une modération réelle. Ne vous enthousiasmez pas et faites en sorte que chaque décision génère un ADR, vos docs/adr/ seront pleins de déchets dans 6 mois. Les trois critères de Matt doivent être strictement suivis.

CONTEXT.md Ne mettez pas les détails d'implémentation. Il y a un dicton dans Skill : "Ne couplez pas CONTEXT.md aux détails de mise en œuvre. Incluez uniquement des termes significatifs pour les experts du domaine." Écrire "PostgreSQL" dans CONTEXT.md est une erreur - les experts du domaine ne se soucient pas de la sélection de la base de données, c'est une question d'ADR.

Ressources de référence

Article suivant : to-PRD + to-Issues : Du dialogue au ticket exécutable——Après la torture, comment solidifier le dialogue en une unité de travail exécutable.