Enregistrement des décisions
Aperçu
Les décisions sont une infrastructure durable ; la mémoire et l'historique de discussion ne le sont pas. Le coût d'un enregistrement est payé une fois ; le coût d'une décision perdue est payé chaque fois que quelqu'un reconstitue l'intention à partir du code.
La forme de l'enregistrement
Chaque décision non triviale produit un enregistrement avec une structure fixe, afin que tout lecteur sache où regarder :
| Section | Contenu |
|---|---|
| Architecture | La forme de la solution et les fichiers clés |
| Modèle de données | Entités, champs, relations |
| Décisions (avec POURQUOI) | Chaque choix accompagné de sa justification — pourquoi est obligatoire |
| Interfaces | Comment les autres codes l'utilisent |
| Contraintes | Ce qui doit rester vrai |
| Pièges | Pièges non évidents pour la personne suivante |
| Alternatives rejetées | Ce qui a été considéré et écarté, et pourquoi — empêche de rouvrir des questions réglées |
Les trois artefacts compagnons
- Un index de toutes les décisions avec un suivi explicite des dépendances (ce qui se base sur quoi) et une section remplacé. Transforme un tas d'enregistrements en un graphe navigable.
- Un document « Considérations futures » — idées différées et préoccupations connues, consulté lors du démarrage de nouveaux travaux pour que rien ne soit silencieusement oublié. Les actions issues d'incidents et les décisions différées avec déclencheur atterrissent ici.
- Une archive — les enregistrements remplacés sont déplacés ici plutôt que supprimés. L'historique est conservé, pas écrasé.
Référence rapide
- Convention d'emplacement des enregistrements :
docs/superpowers/decisions/YYYY-MM-DD-<sujet>.mdavec un frontmatter YAML (title,date,component,status,supersedes,dependencies). - Les Considérations futures se trouvent dans
docs/superpowers/future-considerations.md. Chaque entrée porte un statut (open/triggered/done/dropped) et, le cas échéant, le déclencheur qui devrait la réactiver. Consultez-le lorsque vous démarrez de nouveaux travaux. - Le frontmatter alimente l'index généré automatiquement — tenez-le à jour.
- Le pourquoi et les alternatives rejetées sont les deux sections les plus utiles. Un enregistrement sans elles est une mine.
- Rédigez l'enregistrement à l'étape Enregistrement du pipeline (voir
designing-before-building), après Exécuter.
Outillage fourni
Cette compétence embarque ses propres scripts et modèle, afin qu'ils fonctionnent dans n'importe quel dépôt où la compétence est installée. Ils se trouvent à côté de SKILL.md :
recording-decisions/
scripts/doc-archive.sh trouve les specs/plans sans enregistrement de décision
scripts/index-rebuild.sh régénère l'index à partir du frontmatter des enregistrements
templates/decision-record.md
Pour les localiser — la compétence peut être installée par projet ou globalement :
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
Liste les specs sans enregistrement de décision correspondant et affiche une invite de conversion construite à partir du modèle. Par défaut, utilise docs/superpowers/{specs,plans,decisions,archive}.
index-rebuild.sh [decisions_dir] [output_file]
Réécrit docs/superpowers/index.md à partir du frontmatter de chaque enregistrement — une table Active (component, title, date, dependencies) et une table Remplacé (component, title, superseded by). Régénéré en totalité, donc ne le modifiez jamais à la main.
Les deux sont des scripts bash sans dépendance : un projet utilisant cette compétence n'a pas besoin de yq, jq ni de gestionnaire de tâches. Si les scripts sont manquants, les procédures ci-dessus sont autonomes — faites le travail directement.
Pourquoi cela importe pour le contexte
Les specs et plans sont volontairement verbeux ; ils sont écrits pour un humain qui suit le raisonnement. Cette verbosité est facturée au contexte chaque fois que Claude en ouvre un. Un enregistrement de décision garde ce qui est nécessaire pour avancer — décisions, le pourquoi, interfaces, contraintes, pièges, alternatives rejetées — en environ 30 à 50 lignes, tandis que la spec originale est déplacée dans archive/ où elle reste lisible pour les humains et ne coûte rien tant qu'elle n'est pas ouverte délibérément.
Quand ne PAS l'utiliser
Les changements triviaux et évidents n'ont pas besoin d'enregistrement. Le test : quelqu'un se demanderait-il plus tard « pourquoi cela a-t-il été fait ainsi ? » Si oui, enregistrez-le.
Raisonnement complet : Article II de la constitution, inclus dans engineering-constitution/references/engineering-constitution.md.