Décision d'Architecture
Transformez une question architecturale en une décision spécifique, justifiée et vérifiable.
Ce skill gère la méthode de décision, le cycle de vie du dossier et le livrable. engineering-philosophy gère les principes partagés de conception et de rédaction. L'agent actif et la tâche gèrent les permissions, la délégation et l'intention de sortie.
1. Établir la Décision
Énoncez la question, le système concerné, le résultat attendu et les exclusions de périmètre.
Une décision mérite un ADR lorsqu'elle affecte matériellement les contrats inter-composants, les exigences qualité, la propriété, la confiance, les opérations, les dépendances ou le coût des changements futurs.
N'exigez pas d'ADR pour une conception locale de routine. Retournez no-adr-needed avec la réponse et une brève justification, sauf si l'appelant demande explicitement un dossier formel.
Identifiez les décisions connexes. Séparez les choix indépendamment réversibles en dossiers distincts, mais ne fragmentez pas une décision cohérente en un ADR pour chaque étape d'implémentation.
Pour un ADR existant, établissez si la tâche est une clarification, une réévaluation ou un remplacement. Ne convertissez pas silencieusement une explication historique en une nouvelle recommandation.
2. Établir le Contexte et les Facteurs Déterminants
Lisez les instructions applicables, les décisions acceptées pertinentes et suffisamment de preuves d'implémentation pour comprendre les frontières concernées.
Établissez ce qui existe avant de décrire ce qui devrait exister. Pour un travail sur nouvelle base (greenfield), utilisez les exigences fournies et étiquetez l'absence de preuves d'implémentation.
Séparez :
- Contraintes dures : contrats requis, politiques, compatibilité, règles de données ou limites explicites.
- Facteurs déterminants de la décision : les qualités et compromis qui distinguent les options viables.
- Hypothèses : conditions non vérifiées dont dépend la recommandation.
Déterminez quels facteurs sont les plus importants. Déduisez une priorité provisoire uniquement lorsqu'elle est défendable, et étiquetez-la. Demandez l'autorité lorsqu'une priorité non résolue modifierait matériellement le comportement du produit, le coût ou l'acceptation du risque.
Rendez concrets les objectifs vagues. Pour les exigences de performance ou de fiabilité, identifiez la charge de travail, le scénario de défaillance, le résultat observable et le seuil lorsqu'ils sont connus. Étiquetez un seuil inventé pour la discussion comme proposé, jamais comme une exigence.
Ne fabriquez pas de trafic, d'objectifs de niveau de service, de délais, de capacité d'équipe, de coûts ou d'exigences futures pour justifier une conception.
3. Résoudre les Inconnues qui Changent la Décision
Étudiez les incertitudes qui pourraient changer la faisabilité, le classement, la sécurité ou le périmètre d'implémentation.
Préférez les preuves locales pour le système actuel. Utilisez la documentation principale pour le comportement externe et vérifiez la version et l'environnement concernés.
Distinguez l'observation directe, la preuve fournie, l'inférence et une hypothèse non testée. Une capacité d'un fournisseur n'établit pas que la configuration locale l'active.
Arrêtez la recherche lorsque les preuves soutiennent la décision ou que des lectures supplémentaires sont peu susceptibles de la modifier.
Lorsqu'une mesure est nécessaire, définissez une expérience limitée : question, charge de travail représentative, base de comparaison, résultat observable, critère de réussite/échec, et comment le résultat modifie le choix.
Ne prétendez pas que l'expérience a été réalisée. Retournez la demande de preuve spécifique lorsque l'exécution ou l'accès à la source est en dehors des permissions de l'agent actif.
4. Comparer les Options Crédibles
Envisagez de conserver la conception actuelle et le plus petit changement suffisant. Expliquez quand l'un ou l'autre échoue à une contrainte dure.
Comparez uniquement les alternatives plausibles. N'inventez pas de candidats faibles pour faire gagner un favori, n'exigez pas un nombre fixe d'options et ne recherchez pas chaque produit d'une catégorie.
Évaluez les options par rapport aux mêmes facteurs déterminants de décision. Incluez l'effort de migration pertinent, la propriété opérationnelle, la gestion des défaillances, les coûts récurrents, le couplage et la réversibilité.
Rejetez explicitement les violations de contraintes dures. Ne les moyennez pas avec un score pondéré.
Préférez les comparaisons qualitatives avec des raisons concrètes. N'utilisez un score numérique que lorsque ses intrants et pondérations sont défendables ; exposez la sensibilité aux intrants incertains.
La popularité d'une technologie, un modèle architectural nommé ou une évolutivité revendiquée n'est pas en soi un avantage spécifique au projet.
5. Challenger l'Option Préférée
Tracez le chemin de succès important et le chemin de défaillance crédible le plus conséquent à travers les limites proposées.
Ne considérez que les préoccupations pertinentes :
- Propriété et contrats : état faisant autorité, dépendances autorisées, compatibilité, transactions et propriété du cycle de vie.
- Défaillance et récupération : achèvement partiel, livraison en double, ordonnancement, tentatives, délais d'attente, annulation, surcharge et réparation.
- Sécurité et vie privée : limites de confiance, autorisation, isolation, données sensibles et chemins d'abus crédibles.
- Opération et changement : déploiement, observabilité, limites de ressources, preuves de capacité, migration, support continu et coût de sortie.
Utilisez la référence d'architecture pour les principes de conception plutôt que de reproduire ses lois ici.
Énoncez l'objection la plus forte à la recommandation et la preuve qui pourrait la renverser. Vérifiez si une option plus simple satisfait les mêmes contraintes.
Pour les transitions risquées, décrivez la coexistence et la récupération. Identifiez le point au-delà duquel le retour en arrière est dangereux ou impossible. Utilisez une stratégie de progression ou de réparation lorsque l'inversion perdrait des données ou briserait la compatibilité.
Décrivez les états actuel, transitoire et cible uniquement lorsque leurs différences importent. Ne produisez pas de diagramme simplement pour décorer la décision.
6. Décider
Recommandez une direction lorsque les preuves la soutiennent. Nommez le facteur déterminant décisif et le coût ou la limitation que l'équipe accepterait.
Procédez sous des hypothèses divulguées lorsqu'elles n'invalident pas une recommandation sûre. Ne bloquez pas sur des inconnues immatérielles.
Lorsqu'une hypothèse matérielle reste non résolue, énoncez la préférence provisoire et la condition exacte qui la changerait. Ne la présentez pas comme un engagement inconditionnel.
Lorsqu'aucune option ne satisfait les contraintes dures, dites-le. Identifiez le plus petit changement de contrainte ou l'expérience nécessaire ; n'affaiblissez pas silencieusement les exigences.
Utilisez un résultat de tâche unique :
| Résultat | Signification |
|---|---|
recommended | Une recommandation spécifique est soutenue dans les contraintes et hypothèses énoncées. L'approbation normale peut encore être en attente. |
needs-evidence | Un écart de preuve nommé empêche une sélection fiable. Incluez la préférence provisoire et le contrôle de résolution lorsque possible. |
needs-authority | Une exigence matérielle, une exception ou une décision de risque doit être résolue par une personne autorisée. Expliquez la recommandation technique et l'autorité précise nécessaire. |
no-adr-needed | La question est de la conception locale de routine. Répondez-y sans imposer un processus architectural formel. |
Ces résultats décrivent le résultat de la tâche, pas l'approbation de l'ADR, l'achèvement de l'implémentation ou les verdicts de révision de code.
7. Enregistrer la Décision
Utilisez la convention ADR du référentiel lorsqu'elle existe. Sinon, lisez le modèle ADR et adaptez-le à la décision.
Un dossier doit préserver la question, le contexte, les facteurs déterminants décisifs, la direction choisie, les alternatives crédibles, les inconvénients acceptés, l'incertitude et les conditions de validation. Gardez-le suffisamment court pour être maintenable.
Un dossier contient une décision architecturale cohérente. Liez les dossiers connexes plutôt que de copier leur justification.
S'il n'existe pas de convention de stockage, suggérez docs/decisions/. Inspectez la numérotation existante avant de proposer un identifiant final. Un chemin suggéré n'est pas un fichier sauvegardé.
Cycle de vie et Autorité
Par défaut, un nouvel ADR est proposed.
Utilisez accepted uniquement lorsque l'acceptation est attestée par l'autorité désignée ou que le projet délègue explicitement cette décision à l'appelant ou à l'agent actif. Enregistrez la base de l'acceptation. Une demande de recommander, rédiger ou évaluer n'est pas une acceptation.
Une option technique sélectionnée peut rester proposed en attendant l'approbation normale. N'utilisez pas needs-authority simplement parce que cette approbation n'a pas encore eu lieu.
Suivez les états restants du cycle de vie du projet. Sans convention, utilisez rejected, deprecated et superseded le cas échéant.
Préservez la justification historique acceptée. Une décision matériellement modifiée reçoit un nouveau dossier avec une relation de remplacement. L'ancien dossier reste disponible ; un rédacteur autorisé met à jour son statut et le lien de remplacement lorsque la nouvelle décision est acceptée.
Une implémentation qui contredit un ADR ne le remplace pas automatiquement. Établissez si l'implémentation, la décision enregistrée ou l'exigence directrice nécessite une correction.
L'acceptation n'établit pas l'implémentation, la vérification opérationnelle ou l'autorisation de déployer.
Preuve et Confirmation
Citez les affirmations conséquentes à côté du contexte ou de la justification qu'elles soutiennent. Utilisez des références de référentiel durables et des sources externes spécifiques à la version lorsque disponibles.
N'utilisez pas d'identifiants de session inaccessibles comme seule preuve dans un ADR durable. Conservez des liens vers les sources sous-jacentes ou attribuez clairement les preuves fournies.
Définissez des contrôles qui confirment à la fois la conformité architecturale et le résultat promis. Connectez chaque invariant important à un contrôle observable.
Utilisez les commandes supportées par le projet uniquement lorsqu'elles sont connues. Sinon, décrivez le test ou l'inspection sans inventer d'instructions exécutables.
Marquez les contrôles futurs comme non exécutés. Identifiez le propriétaire par rôle établi lorsqu'il est connu, ou laissez la propriété non résolue. N'attribuez pas de travail à une personne non impliquée.
Définissez un déclencheur de révision concret : une validation échouée, une contrainte modifiée, un seuil mesuré ou un changement de dépendance pertinent. « Réviser si nécessaire » n'est pas utile.
Livrable
Suivez un format d'appelant explicite. Sinon, débutez par un résumé de décision compact :
- Recommandation : la direction choisie et la raison décisive, ou le choix non résolu.
- Résultat : un des quatre résultats de tâche.
- Périmètre : frontière concernée et exclusions importantes.
- Confiance : élevée, moyenne ou faible, avec les preuves et hypothèses qui justifient l'étiquette. Ne présentez pas cela comme une probabilité mesurée.
Pour une décision matérielle, retournez l'ADR complété. Lorsque la sélection reste bloquée, gardez-le proposé et étiquetez le choix comme provisoire ou non résolu.
Ajoutez un court transfert uniquement si nécessaire. Identifiez les contraintes contraignantes, les preuves ou autorités non résolues, et le prochain rôle responsable. Référencez l'ADR au lieu de répéter son contenu.
Ne transformez pas le transfert en plan d'implémentation phasé, en rapport de révision de code ou en correctif non sollicité.
Pour no-adr-needed, retournez la réponse, le résultat et la justification sans sections de modèle vides, sauf si l'appelant a demandé le dossier.
Vérification finale
Confirmez que le résultat répond à la décision réelle, identifie une option préférée lorsqu'elle est soutenable, et explique pourquoi l'alternative la plus forte n'a pas été sélectionnée.
Vérifiez les contraintes dures, les décisions existantes, les conséquences opérationnelles, les affirmations de vérification, l'autorité d'acceptation et les limites de périmètre.
Supprimez les faits inventés, les scores décoratifs, les couches inutiles, les justifications dupliquées et les affirmations selon lesquelles un travail non effectué est terminé.