Développer avec ADR

Développer avec des ADR

Première étape obligatoire : vérification des conflits

Avant de demander le domaine, de créer des agents, d'inspecter le code ou d'apporter des modifications, exécutez le script en lecture seule fourni :

python3 <chemin-absolu-du-répertoire-de-la-compétence>/scripts/check_conflicting_skills.py --project <chemin-du-dépôt>

Remplacez les paramètres fictifs par des chemins réels et mettez les chemins entre guillemets si nécessaire. Passez chaque nom du catalogue des compétences disponibles de la session avec un argument --available-skill répété, y compris les noms cloud-only et ceux qualifiés par plugin. Ajoutez les répertoires de compétences non standard avec --root ; ajoutez explicitement les cibles des liens symboliques de répertoires imbriqués pertinents. Le script découvre les fichiers de compétences locaux et les entrées du catalogue sans charger leurs instructions ni modifier les installations.

• Considérez grill-me et spec-first comme des compétences conflictuelles, y compris leurs variantes de casse, espace, underscore et trait d'union, telles que Grill Me ou spec_first.
• Le code de sortie 0 signifie qu'aucun conflit n'a été trouvé dans le périmètre inspecté. Le code 1 signifie que des conflits ont été trouvés, pas un échec du script. Le code 2 signifie que la découverte est incomplète : signalez les erreurs et la limitation de couverture, résolvez-les dans la mesure du possible, puis relancez. Ne prétendez jamais que toutes les compétences ont été vérifiées si la couverture est incomplète.
• Pour toute correspondance, désactivez leur utilisation dans ce flux de travail et avertissez l'utilisateur dans sa langue avant de continuer : nommez les compétences détectées et expliquez qu'elles sont désactivées pour le flux de travail en cours uniquement. N'impliquez pas de désinstallation globale ou de modification des paramètres du compte. Aucune approbation supplémentaire n'est requise pour ces exclusions de flux de travail.
• N'invoquez pas les compétences exclues, ne suivez pas leurs instructions et ne leur déléguez pas de travail. Appliquez l'exclusion au coordinateur, à l'architecte et à l'implémenteur ; transmettez la liste d'exclusion à chaque passage de témoin entre agents. Utilisez les propres étapes de clarification et d'approbation de ce flux de travail.
• Le script détecte les conflits ; l'agent coordinateur applique les exclusions. Excluez également l'une ou l'autre compétence si le catalogue de la session la révèle, même si ses fichiers ne sont pas accessibles. Si le script ne peut pas s'exécuter, signalez cette limitation et appliquez les exclusions connues sans prétendre avoir effectué une analyse réussie.
• Relancez après avoir repris une session ou après des modifications des compétences disponibles. Ne supprimez, ne renommez et ne désactivez jamais globalement des compétences installées dans le cadre de cette vérification.

Entrée et rôles

1. Avant de démarrer le flux de travail, demandez le domaine sur lequel l'architecte doit se concentrer. Acceptez les domaines métier ou technique. Réutilisez un domaine explicitement fourni sans redemander.
2. Créez un agent architecte distinct pour le domaine sélectionné pour toute la session. Fournissez ces règles, le domaine, le chemin du dépôt et le contexte connu. Demandez à l'architecte de demander à l'utilisateur quel problème résoudre ; l'agent principal peut relayer la question et la réponse. Si le problème est déjà fourni, ne demandez que les informations manquantes.
3. L'agent principal coordonne le dialogue, les documents et les passages de contexte. L'architecte investigate, conçoit, maintient les ADR et vérifie indépendamment les résultats. Un agent implémenteur séparé implémente les décisions approuvées et prépare les preuves. Ne combinez pas les rôles d'architecte et d'implémenteur.
4. Utilisez les capacités natives d'agents séparés de l'environnement : sous-agents dans Codex et capacités d'agent/tâche disponibles dans Claude Code. N'inventez pas d'API et ne présentez pas un seul agent changeant de rôle comme une vérification indépendante. Si des agents séparés ne sont pas disponibles, expliquez la limitation et demandez à l'utilisateur de choisir un environnement adapté. L'investigation peut continuer, mais l'implémentation dans le cadre de ce flux de travail ne doit pas commencer.
5. Après une perte de contexte, restaurez l'état à partir des documents et du code. Si un nouvel architecte doit être créé, ne prétendez pas que l'agent d'origine a survécu ; restaurez son domaine et ses responsabilités.

Investigation et décision

• L'architecte lit les instructions du projet, le code, les ADR connexes et les preuves, puis clarifie le problème et les contraintes. Ne créez pas d'ADR avant d'avoir investigué le code et clarifié le problème. S'il n'existe pas encore de code, enregistrez ce fait et investigatez les documents disponibles.
• Identifiez les conflits avec les décisions actuelles. Présentez d'abord le conflit à l'utilisateur et demandez une décision ; ce n'est qu'après la réponse que vous préparez un nouvel ADR. L'autorisation de préparer un remplacement n'est pas une approbation pour l'implémenter.
• Rédigez un ADR dans docs/adr/ en utilisant les modèles. Incluez un bref énoncé du problème, la solution proposée, la justification et des critères d'acceptation vérifiables avec des identifiants stables. Définissez le statut initial sur accepted-for-discussion.
• Séparez les décisions indépendantes dans des ADR distincts et enregistrez explicitement les dépendances. N'introduisez pas de cycles de dépendance ou de remplacement.
• Présentez l'ADR spécifique ou un ensemble énuméré d'ADR pour une approbation explicite de l'utilisateur avant de les implémenter. N'inférez pas l'approbation à partir du silence, d'une demande générale de construire quelque chose ou d'une autorisation à investiguer.
• Enregistrez la réponse de l'utilisateur, la date et la version approuvée du document. Ne passez à accepted-for-work qu'après approbation explicite. Permettez l'approbation explicite d'un ensemble énuméré d'ADR.

Implémentation

• Commencez à implémenter un ADR uniquement après que tous les ADR dont il dépend sont terminés, même si l'ensemble entier est déjà approuvé.
• Donnez à l'implémenteur l'ADR, les critères, les dépendances et les contraintes. Exigez que l'implémentation reste dans le périmètre de la décision approuvée.
• Si l'implémentation est impossible ou si la décision ou les critères doivent changer, arrêtez le travail concerné et renvoyez le problème à l'architecte. Les travaux approuvés indépendants peuvent continuer.
• Ne modifiez jamais la description de la solution ou les critères d'acceptation après approbation. Enregistrez les modifications dans un nouvel ADR avec une approbation séparée.
• L'implémenteur prépare les preuves dans docs/evidence/ : résultats pour chaque critère, commandes et instructions de reproduction, et le commit vérifié ou la version exacte du code. Ne substituez pas un commit futur à la version testée. Pour les modifications non commitées, incluez un diff sauvegardé et les identifiants ou hachages des fichiers vérifiés.

Vérification indépendante et achèvement

• L'architecte exécute personnellement les vérifications et compare les résultats réels à chaque critère d'acceptation. Le rapport de l'implémenteur et l'inspection du code ne remplacent pas l'exécution.
• Conservez les commandes, l'environnement, les résultats, les liens vers les journaux et la version vérifiée dans la preuve. Marquez honnêtement les vérifications qui n'ont pas été exécutées, qui ont été bloquées ou qui ont échoué. Ne terminez pas un ADR avec des critères non vérifiés ou non satisfaits.
• Si l'implémentation échoue à la vérification mais que l'ADR reste valide, présentez d'abord les résultats et le périmètre concret de correction à l'utilisateur et demandez l'autorisation. Ne déléguez pas et n'effectuez pas de corrections avant la réponse. Après autorisation, l'implémenteur corrige le problème et l'architecte vérifie à nouveau. Un autre échec de vérification nécessite une nouvelle autorisation pour le cycle de correction suivant.
• Si l'échec nécessite une nouvelle décision d'architecture, revenez à l'investigation et à la procédure de nouvel ADR.
• Seul l'architecte peut définir le statut completed après vérification indépendante réussie de chaque critère. Un lien vers le document de preuve est requis. Aucune approbation supplémentaire de l'utilisateur n'est nécessaire pour terminer l'ADR.

Statuts et préservation de l'historique

Utilisez exactement quatre valeurs status canoniques. Les étiquettes russes ci-dessous identifient leurs significations originales ; préservez l'historique existant du projet sans réécrire silencieusement les documents obsolètes.

Statut	Étiquette originale	Condition
accepted-for-discussion	принято к обсуждению	Proposition investiguée en attente de discussion ou d'approbation
accepted-for-work	принято к работе	L'utilisateur a explicitement approuvé l'ADR spécifique
completed	завершен	L'architecte a vérifié indépendamment tous les critères ; la preuve est liée
rejected	отклонено	Un nouvel ADR approuvé et une justification/preuve de rejet existent

• Ne supprimez jamais les ADR ou les documents de preuve et ne réutilisez pas leurs identifiants. Avant l'approbation, autorisez l'affinement des brouillons tout en enregistrant les modifications substantielles.
• Après approbation, conservez le corps de la solution et les critères immuables. Autorisez les mises à jour du statut et des liens avec des entrées d'historique ajoutées. Préservez les entrées antérieures, les preuves et les résultats de vérification. N'écrasez pas un échec de vérification par un résultat réussi.
• Rejetez l'ancien ADR au moment où l'utilisateur approuve explicitement son remplacement pour le travail, y compris lorsque l'ancien ADR était completed. Liez immédiatement l'ancien ADR à son remplacement et à un document de justification de rejet séparé. Cela prouve pourquoi l'ancienne décision a été rejetée ; cela ne prouve pas que la nouvelle implémentation fonctionne.
• Préservez l'achèvement précédent, sa date, sa version et ses preuves. Enregistrez explicitement que le remplacement peut ne pas encore être implémenté. Rejeter un document ne supprime pas en lui-même le code fonctionnel.
• Ne rejetez pas un ADR sans une nouvelle décision. Si l'utilisateur n'a pas choisi de remplacement, conservez le statut actuel et ajoutez une entrée de discussion. N'inventez pas un remplacement simplement pour permettre une transition de statut.
• Si une dépendance est rejetée ou remplacée, suspendez le travail concerné et demandez à l'architecte d'évaluer l'impact. Ne réaffectez pas silencieusement les décisions approuvées.

Graphe de documents

• Lisez les modèles avant de créer des documents et les directives de portabilité lorsque vous utilisez un nouvel environnement.
• Stockez les ADR sous docs/adr/ADR-0001-court-slug.md et les preuves sous docs/evidence/EVID-0001-court-slug.md. Choisissez le prochain numéro inutilisé en tenant compte de l'historique existant ; ne renumérotez pas les anciens documents.
• Utilisez des liens Markdown relatifs explicites et des types de relations : replaces / replaced_by, depends_on / required_by, extends / extended_by, et evidence / proves. Maintenez les backlinks et identifiez si une preuve atteste de l'implémentation ou de la raison du rejet.
• Considérez les ADR et les preuves comme les documents du graphe ; une base de données de graphe séparée n'est pas nécessaire. Lors des passages de témoin, vérifiez les cibles des liens, les backlinks, l'absence de cycles de dépendance et les conditions de statut.
• À la fin de chaque étape, rapportez le statut de l'ADR, le résultat, les liens vers les documents et la décision spécifique nécessaire si vous attendez l'utilisateur. Ne décrivez pas un travail simplement approuvé ou implémenté mais non vérifié comme completed.