Modélisation du Domaine
Construisez et affûtez activement le modèle domaine du projet pendant que vous concevez. Il s'agit d'une discipline active — challenger les termes, inventer des scénarios aux limites, et écrire le glossaire et les décisions au moment où ils se cristallisent. (Le simple fait de lire CONTEXT.md pour le vocabulaire n'est pas cette compétence — c'est une habitude qu'une ligne de code peut accomplir. Cette compétence est pour quand vous modifiez le modèle, pas seulement quand vous le consommez.)
Structure des fichiers
La plupart des dépôts ont un seul contexte :
/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
Si un fichier CONTEXT-MAP.md existe à la racine, le dépôt a plusieurs contextes. La carte indique où se trouve chacun d'eux :
/
├── CONTEXT-MAP.md
├── docs/
│ └── adr/ ← décisions à l'échelle du système
├── src/
│ ├── ordering/
│ │ ├── CONTEXT.md
│ │ └── docs/adr/ ← décisions spécifiques au contexte
│ └── billing/
│ ├── CONTEXT.md
│ └── docs/adr/
Créez les fichiers de manière paresseuse — seulement lorsque vous avez quelque chose à écrire. Si aucun CONTEXT.md n'existe, créez-en un dès que le premier terme est résolu. Si aucun docs/adr/ n'existe, créez-le dès qu'une première ADR est nécessaire.
Pendant la session
Challenger le glossaire
Lorsque l'utilisateur utilise un terme qui entre en conflit avec le langage existant dans CONTEXT.md, signalez-le immédiatement. "Votre glossaire définit 'annulation' comme X, mais vous semblez vouloir dire Y — lequel est-ce ?"
Affiner le langage flou
Lorsque l'utilisateur utilise des termes vagues ou surchargés, proposez un terme canonique précis. "Vous dites 'compte' — voulez-vous dire le Client ou l'Utilisateur ? Ce sont des choses différentes."
Discuter de scénarios concrets
Lorsque les relations du domaine sont discutées, testez-les avec des scénarios spécifiques. Inventez des scénarios qui sondent les cas limites et forcent l'utilisateur à être précis sur les frontières entre les concepts.
Recouper avec le code
Lorsque l'utilisateur énonce comment quelque chose fonctionne, vérifiez si le code est d'accord. Si vous trouvez une contradiction, signalez-la : "Votre code annule des commandes entières, mais vous venez de dire qu'une annulation partielle est possible — lequel est correct ?"
Mettre à jour CONTEXT.md en ligne
Lorsqu'un terme est résolu, mettez à jour CONTEXT.md immédiatement. Ne les regroupez pas — capturez-les au fur et à mesure. Utilisez le format dans CONTEXT-FORMAT.md.
CONTEXT.md doit être totalement dépourvu de détails d'implémentation. Ne traitez pas CONTEXT.md comme un cahier des charges, un bloc-notes ou un dépôt pour les décisions d'implémentation. C'est un glossaire et rien d'autre.
Proposer des ADR avec parcimonie
Proposez de créer une ADR uniquement lorsque les trois conditions suivantes sont remplies :
- Difficile à annuler — le coût d'un changement d'avis ultérieur est important
- Surprenant sans contexte — un futur lecteur se demandera "pourquoi ont-ils fait comme ça ?"
- Résultat d'un véritable compromis — il y avait de véritables alternatives et vous en avez choisi une pour des raisons spécifiques
Si l'une des trois conditions manque, ne créez pas d'ADR. Utilisez le format dans ADR-FORMAT.md.