Documentation (ADR & Runbook)

Ce qu'elle fait

La compétence Documentation fournit des modèles et des conseils pour produire des documents opérationnels : Architecture Decision Records (ADRs) et runbooks. Elle standardise l'endroit où enregistrer les décisions d'architecture (fichiers ADR immuables), la manière de formater les runbooks pour les tâches opérationnelles et la réponse aux incidents, ainsi que les principes qui rendent la documentation utile en pratique (contexte clair, options évaluées, commandes prêtes à être copiées-collées). Cette compétence est intentionnellement légère — elle fournit des modèles markdown ADR et runbook prêts à l'emploi ainsi que des conseils sur leur emplacement et leur cycle de vie.

Quand l'utiliser

Invoquez cette compétence lors de discussions de conception, de sélection de technologies, de planification de dépréciation ou lors de la création de runbooks opérationnels pour des services. Utilisez-la lorsqu'une équipe doit enregistrer formellement une décision, créer une checklist de déploiement/exécution, ou capturer des étapes d'escalade et de dépannage. Elle est également appropriée pour documenter les tâches opérationnelles courantes afin que les ingénieurs d'astreinte puissent agir rapidement.

Ce qui est inclus

• Modèles : modèle markdown ADR et modèle de runbook avec des sections pour le propriétaire, les prérequis, les opérations et l'escalade
• Conseils : principes sur l'immuabilité des ADR, quand créer chaque type de document et emplacements de fichiers recommandés (docs/adr, docs/runbooks)
• Utilisation : exemples et instructions brèves pour le nommage, les champs de statut et la structure du contenu

Agents compatibles

S'intègre dans les flux de travail d'agents de type Claude Code et les configurations multi-agents orientées développeur où l'agent peut créer ou suggérer des fichiers de dépôt. Utile pour les équipes d'ingénierie, les SRE et les pipelines de documentation pour développeurs.