clanker25/ai

Compétence ADR

Philosophie

Les ADR créés avec cette compétence sont des spécifications exécutables pour les agents de codage. Un humain approuve la décision ; un agent l'implémente. L'ADR doit contenir tout ce dont l'agent a besoin pour écrire du code correct sans poser de questions de suivi.

Cela signifie :

• Les contraintes doivent être explicites et mesurables, pas des impressions
• Les décisions doivent être suffisamment spécifiques pour être exécutées (« utiliser PostgreSQL 16 avec pgvector », pas « utiliser une base de données »)
• Les conséquences doivent correspondre à des tâches de suivi concrètes
• Les non-objectifs doivent être énoncés pour éviter la dérive du périmètre
• L'ADR doit être autonome — pas d'hypothèses de connaissance tacite
• L'ADR doit inclure un plan d'implémentation — quels fichiers modifier, quels modèles suivre, quels tests écrire et comment vérifier que la décision a été correctement implémentée

Quand rédiger un ADR

Rédigez un ADR lorsqu'une décision :

• Modifie la façon dont le système est construit ou exploité (nouvelle dépendance, modèle d'architecture, choix d'infrastructure, conception d'API)
• Est difficile à annuler une fois que le code a été écrit en fonction de celle-ci
• Affecte d'autres personnes ou agents qui travailleront ultérieurement dans cette base de code
• A de vraies alternatives qui ont été envisagées et rejetées

N'écrivez PAS d'ADR pour :

• Les choix d'implémentation de routine dans un modèle établi
• Les corrections de bogues ou les corrections de fautes de frappe
• Les décisions déjà capturées dans un ADR existant (mettez-le à jour à la place)
• Les préférences de style déjà couvertes par des linters ou des formateurs

En cas de doute : si un agent futur travaillant dans cette base de code bénéficierait de savoir pourquoi ce choix a été fait, rédigez l'ADR.

Déclencheurs d'ADR proactifs (pour les agents)

Si vous êtes un agent codant dans un dépôt et que vous rencontrez l'une de ces situations, arrêtez-vous et proposez un ADR avant de continuer :

• Vous êtes sur le point d'introduire une nouvelle dépendance qui n'existe pas déjà dans le projet
• Vous êtes sur le point de créer un nouveau modèle architectural (nouvelle façon de gérer les erreurs, nouvelle couche d'accès aux données, nouvelle convention d'API) que d'autres codes devront suivre
• Vous êtes sur le point de faire un choix entre deux alternatives ou plus réelles et les compromis ne sont pas évidents
• Vous êtes sur le point de modifier quelque chose qui contredit un ADR accepté existant
• Vous réalisez que vous écrivez un long commentaire de code expliquant « pourquoi » — ce raisonnement appartient à un ADR

Comment proposer : Dites à l'humain quelle décision vous avez rencontrée, pourquoi elle est importante, et demandez-lui s'il souhaite la capturer comme un ADR. Si oui, exécutez le flux de travail complet en quatre phases. Si non, notez la décision dans un commentaire de code et continuez.

Création d'un ADR : flux de travail en quatre phases

Chaque ADR passe par quatre phases. Ne sautez pas de phases.

Phase 0 : Analyse de la base de code

Avant de poser des questions, rassemblez le contexte du dépôt :

1. Trouvez les ADR existants. Vérifiez contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ pour les enregistrements existants. Lisez-les. Notez :

   • Les conventions existantes (répertoire, nommage, style de modèle)
   • Les décisions qui concernent ou contraignent la décision actuelle
   • Tout ADR que cette nouvelle décision pourrait remplacer

2. Vérifiez la pile technique. Lisez package.json, go.mod, requirements.txt, Cargo.toml, ou l'équivalent. Notez les dépendances et versions pertinentes.

3. Trouvez les modèles de code associés. Si la décision concerne un domaine spécifique (par exemple, « comment nous gérons l'authentification »), analysez les implémentations existantes. Identifiez les fichiers, répertoires et modèles spécifiques qui seront affectés par la décision.

4. Vérifiez les références ADR dans le code. Recherchez les références ADR dans les commentaires et la documentation (voir « Liaison Code ↔ ADR » ci-dessous). Cela révèle quelles décisions existantes régissent quelles parties de la base de code.

5. Notez ce que vous avez trouvé. Apportez ce contexte dans la Phase 1 — cela affinera vos questions et empêchera l'ADR de contredire les décisions existantes.

Phase 1 : Capture de l'intention (Socratique)

Interviewez l'humain pour comprendre l'espace de décision. Posez les questions une à la fois, en vous appuyant sur les réponses précédentes. Ne déversez pas une liste de questions.

Questions principales (posez-les dans cet ordre approximatif, sautez ce qui est déjà clair d'après le contexte ou la Phase 0) :

1. Que décidez-vous ? — Obtenez un titre court et spécifique. Encouragez une phrase verbale (« Choisir X », « Adopter Y », « Remplacer Z par W »).
2. Pourquoi maintenant ? — Qu'est-ce qui a cassé, qu'est-ce qui change, ou qu'est-ce qui cassera si vous ne faites rien ? C'est le déclencheur.
3. Quelles contraintes existent ? — Pile technique, calendrier, budget, taille de l'équipe, code existant, conformité. Soyez concret. Référencez ce que vous avez trouvé dans la Phase 0 (« Je vois que vous utilisez déjà X — cela contraint-il ceci ? »).
4. À quoi ressemble le succès ? — Résultats mesurables. Allez au-delà de « ça marche » vers des éléments spécifiques (latence, débit, expérience développeur, charge de maintenance).
5. Quelles options avez-vous envisagées ? — Au moins deux. Pour chacune : quel est le compromis principal ? S'ils n'ont qu'une seule option, aidez-les à articuler pourquoi les alternatives ont été rejetées.
6. Quelle est votre tendance actuelle ? — Capturez l'intuition viscérale tôt. Révèle souvent des priorités non exprimées.
7. Qui doit savoir ou approuver ? — Décideurs, experts consultés, parties prenantes informées.
8. De quoi un agent aurait-il besoin pour implémenter cela ? — Quels fichiers/répertoires sont affectés ? Quels modèles existants doit-il suivre ? Que doit-il éviter ? Quels tests prouveraient que cela fonctionne ? Cela alimente directement le Plan d'implémentation.

Suivi adaptatif : En fonction des réponses, creusez plus profondément là où la décision est floue. Suivi courant :

• « Quel est le pire résultat si cette décision est erronée ? »
• « Qu'est-ce qui vous ferait reconsidérer cela dans 6 mois ? »
• « Y a-t-il quelque chose que vous choisissez explicitement de NE PAS faire ? »
• « À quel antécédent ou modèle existant dans la base de code cela se rapporte-t-il ? »
• « J'ai trouvé [ADR/modèle existant] — cette nouvelle décision interagit-elle avec cela ? »

Quand s'arrêter : Vous en avez assez lorsque vous pouvez remplir chaque section de l'ADR — y compris le Plan d'implémentation — sans inventer de choses. Si vous devinez pour une section, posez une autre question.

Porte de résumé de l'intention : Avant de passer à la Phase 2, présentez un résumé structuré de ce que vous avez capturé et demandez à l'humain de le confirmer ou de le corriger :

Voici ce que je capture pour l'ADR :

• Titre : {titre}
• Déclencheur : {pourquoi maintenant}
• Contraintes : {liste}
• Options : {option 1} vs {option 2} [vs ...]
• Tendance : {quelle option et pourquoi}
• Non-objectifs : {ce qui est explicitement hors de portée}
• ADR/code associés : {ce qui existe et avec lequel cela interagit}
• Fichiers/zones affectés : {où dans la base de code cela atterrit}
• Vérification : {comment nous saurons que cela a été correctement implémenté}

Cela capture-t-il votre intention ? Quelque chose à ajouter ou à corriger ?

N'avancez PAS à la Phase 2 tant que l'humain n'a pas confirmé le résumé.

Phase 2 : Rédaction de l'ADR

1. Choisissez le répertoire ADR.

   • S'il en existe un (trouvé dans la Phase 0), utilisez-le.
   • S'il n'en existe pas, créez contributing/decisions/ (si contributing/ existe), docs/decisions/ (valeur par défaut MADR), ou adr/ (dépôts plus simples).

2. Choisissez une stratégie de nom de fichier.

   • Si les ADR existants utilisent des préfixes de date (YYYY-MM-DD-...), continuez cela.
   • Sinon, utilisez des noms de fichier uniquement avec slug (choisir-base-de-donnees.md).

3. Choisissez un modèle.

   • Utilisez assets/templates/adr-simple.md pour les décisions simples (un gagnant clair, compromis minimes).
   • Utilisez assets/templates/adr-madr.md lorsque vous devez documenter plusieurs options avec des avantages/inconvénients/conducteurs structurés.
   • Voir references/template-variants.md pour des conseils.

4. Remplissez chaque section à partir du résumé d'intention confirmé. Ne laissez pas de texte factice. Chaque section doit contenir du contenu réel ou être supprimée (sections facultatives uniquement).

5. Rédigez le Plan d'implémentation. C'est la section la plus importante pour les ADR axés sur les agents. Elle indique exactement à l'agent suivant quoi faire. Voir le modèle pour la structure.

6. Rédigez les critères de vérification sous forme de cases à cocher. Ceux-ci doivent être suffisamment spécifiques pour qu'un agent puisse vérifier chacun d'eux par programmation ou manuellement.

7. Générez le fichier.

   • Préféré : exécutez scripts/new_adr.js (gère le répertoire, le nommage et les mises à jour d'index facultatives).
   • Si vous ne pouvez pas exécuter de scripts, copiez un modèle depuis assets/templates/ et remplissez-le manuellement.

Phase 3 : Révision par rapport à la liste de vérification

Après la rédaction, examinez l'ADR par rapport à la liste de vérification de préparation agent dans references/review-checklist.md.

Présentez la révision comme un résumé, pas un vidage brut de la liste de vérification. Format :

Révision ADR

✅ Réussit : {listez ce qui est solide — par exemple, « le contexte est autonome, le plan d'implémentation couvre les fichiers affectés, les critères de vérification sont vérifiables »}

⚠️ Lacunes trouvées :

• {lacune spécifique 1 — par exemple, « Le plan d'implémentation ne mentionne pas les fichiers de test — quelle suite de tests devrait couvrir cela ? »}
• {lacune spécifique 2}

Recommandation : {Validez-le / Corrigez d'abord les lacunes / Nécessite plus de travail en Phase 1}

Ne mentionnez que les échecs et les points forts notables — ne récitez pas chaque case cochée.

S'il y a des lacunes, proposez des correctifs spécifiques. Ne vous contentez pas de signaler les problèmes — proposez des solutions et demandez à l'humain de les approuver.

Ne finalisez pas tant que l'ADR ne passe pas la liste de vérification ou que l'humain n'accepte pas explicitement les lacunes.

Consultation des ADR (flux de travail de lecture)

Les agents doivent lire les ADR existants avant d'implémenter des modifications dans une base de code qui en contient. Cela ne fait pas partie du flux de travail de création d'ADR — c'est une opération autonome que tout agent doit effectuer.

Quand consulter les ADR

• Avant de commencer à travailler sur une fonctionnalité qui touche à l'architecture (authentification, couche de données, conception d'API, infrastructure)
• Lorsque vous rencontrez un modèle dans le code et vous demandez « pourquoi est-ce fait ainsi ? »
• Avant de proposer une modification qui pourrait contredire une décision existante
• Lorsqu'un humain dit « vérifie les ADR » ou « il y a une décision à ce sujet »
• Lorsque vous trouvez une référence ADR dans un commentaire de code

Comment consulter les ADR

1. Trouvez le répertoire ADR. Vérifiez contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/. Vérifiez également la présence d'un fichier d'index (README.md ou index.md).

2. Analysez les titres et les statuts. Lisez l'index ou listez les noms de fichier. Concentrez-vous sur les ADR accepted — ce sont des décisions actives.

3. Lisez les ADR pertinents en entier. Ne vous contentez pas de lire le titre — lisez le contexte, la décision, les conséquences, les non-objectifs ET le Plan d'implémentation. Le Plan d'implémentation vous indique les modèles à suivre et les fichiers régis par cette décision.

4. Respectez les décisions. Si un ADR accepté dit « utiliser PostgreSQL », ne proposez pas de passer à MongoDB sans créer un nouvel ADR qui le remplace. Si vous trouvez un conflit entre ce que le code fait et ce que l'ADR dit, signalez-le à l'humain.

5. Suivez le Plan d'implémentation. Lors de l'implémentation de code dans une zone régie par un ADR, suivez les modèles spécifiés dans son Plan d'implémentation. Si le plan dit « toutes les nouvelles requêtes passent par la couche d'accès aux données dans src/db/ », faites cela.

6. Référencez les ADR dans votre travail. Ajoutez des références ADR dans les commentaires de code et les descriptions de PR (voir « Liaison Code ↔ ADR » ci-dessous).

Liaison Code ↔ ADR

Les ADR doivent être liés de manière bidirectionnelle au code qu'ils régissent.

ADR → Code (dans le Plan d'implémentation)

La section Plan d'implémentation nomme les fichiers, répertoires et modèles spécifiques :

## Plan d'implémentation

- **Chemins affectés** : `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Modèle** : toutes les requêtes de base de données passent par `src/db/client.ts`

Code → ADR (dans les commentaires)

Lors de l'implémentation de code guidé par un ADR, ajoutez un commentaire le référençant :

// ADR : Utilisation de better-sqlite3 pour la base de données de test
// Voir : docs/decisions/2025-06-15-utiliser-sqlite-pour-base-de-donnees-test.md
import Database from 'better-sqlite3';

Gardez ces éléments légers — un commentaire au point d'entrée, pas sur chaque ligne. L'objectif est la découvrabilité : lorsqu'un agent futur lira ce code, il pourra trouver le raisonnement.

Pourquoi cela est important

• Un agent travaillant dans src/db/ peut trouver quels ADR régissent ce domaine
• Un agent lisant un ADR peut trouver le code qui l'implémente
• Lorsqu'un ADR est remplacé, les références de code facilitent la recherche de tout le code nécessitant une mise à jour

Autres opérations

Mettre à jour un ADR existant

1. Identifiez l'intention :

   • Accepter / rejeter : modifiez le statut, ajoutez tout contexte final.
   • Déprécier : statut → deprecated, expliquez le chemin de remplacement.
   • Remplacer : créez un nouvel ADR, liez les deux sens (ancien → nouveau, nouveau → ancien).
   • Ajouter des apprentissages : ajoutez à ## Plus d'informations avec un horodatage. Ne réécrivez pas l'historique.

2. Utilisez scripts/set_adr_status.js pour les changements de statut (prend en charge le front matter YAML, le statut en puce et le statut de section).

Cycle de vie post-acceptation

Après qu'un ADR a été accepté :

1. Créez des tâches d'implémentation. Chaque élément du Plan d'implémentation et chaque suivi dans les Conséquences doit devenir une tâche traçable (problème, ticket ou TODOs).
2. Référencez l'ADR dans les PR. Liez l'ADR dans les descriptions de PR, par exemple « Implémente contributing/decisions/2025-06-15-utiliser-sqlite-pour-base-de-donnees-test.md. »
3. Ajoutez des références de code. Ajoutez des commentaires de chemin ADR aux points d'implémentation clés.
4. Vérifiez les critères de vérification. Une fois l'implémentation terminée, parcourez les cases à cocher de Vérification. Mettez à jour l'ADR avec les résultats dans ## Plus d'informations.
5. Revisitez lorsque les déclencheurs se produisent. Si l'ADR a spécifié des conditions de réexamen (« si X se produit, reconsidérez »), surveillez ces conditions.

Index

Si le dépôt a un fichier d'index/de journal ADR (souvent README.md ou index.md dans le répertoire ADR), maintenez-le à jour.

Préféré : laissez scripts/new_adr.js --update-index le faire. Sinon :

• Ajoutez une entrée en puce pour le nouvel ADR.
• Maintenez l'ordre cohérent (numérique si numéroté ; date ou alpha si slugs).

Initialisation

Lors de l'introduction des ADR dans un dépôt qui n'en a aucun :

node /path/to/adr-skill/scripts/bootstrap_adr.js

Cela crée le répertoire, un fichier d'index et un premier ADR rempli (« Adopter les enregistrements de décisions d'architecture ») avec un contenu réel expliquant pourquoi l'équipe utilise les ADR. Utilisez --json pour une sortie lisible par machine. Utilisez --dir pour remplacer le nom du répertoire.

Catégories (grands projets)

Pour les dépôts avec de nombreux ADR, organisez par sous-répertoire :

docs/decisions/
  backend/
    2025-06-15-utiliser-
  frontend/
    2025-06-10-adopter-
  infracouches/
    2025-05-20-choisir-