Synthèse automatique
Ce skill aide à documenter les décisions techniques importantes en utilisant des modèles ADR structurés.
Points forts
- Fournit des modèles prêts à l'emploi pour différents niveaux de complexité
- Encadre le processus de révision et d'approbation par les pairs
- Capture le contexte et les alternatives avant la mise en œuvre
- Facilite la maintenance et la traçabilité des décisions
Limites
- Nécessite une discipline d'écriture avant l'implémentation
- Peut être perçu comme une lourdeur bureaucratique pour les petites décisions
- Ne couvre pas les décisions non techniques (ex: budgétaires)
Lors de l'adoption d'une nouvelle technologie, d'un changement d'architecture ou de toute décision technique ayant un impact durable sur le projet.
Pour des mises à jour de routine, des corrections de bugs ou des décisions triviales qui n'affectent pas la structure du système.
Analyse de sécurité
SûrThe skill is a documentation guideline with no executable code or system-altering instructions. It uses only the Read tool to access reference files, posing no execution risk.
Aucun point d'attention détecté
Comment cette analyse est faiteExemples
Create an Architecture Decision Record for choosing PostgreSQL as our primary database. Include context about our need for ACID compliance and JSON support, list 2 alternatives (MySQL and MongoDB), and document the consequences.Review our existing ADRs in the docs/adr/ directory and provide a summary of the key architectural decisions made, highlighting any that are now deprecated or superseded.Draft an ADR template for our team that includes sections for context, decision drivers, options considered, decision, consequences, and mitigations. Use the MADR format.name: architecture-decision-records description: This skill should be used when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. It provides ADR templates and best practices. allowed-tools: Read
Architecture Decision Records
Capture the context and rationale behind significant technical decisions using structured ADR formats.
When to Use This Skill
| Write ADR | Skip ADR | | -------------------------- | ---------------------- | | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes |
Quick Start
- Copy the template:
cp docs/adr/template.md docs/adr/NNNN-your-title.md - Fill in: Context, Decision Drivers, Options, Decision, Consequences
- PR for review (2+ senior engineers)
- Update
docs/adr/README.mdindex after merge
Core Concepts
An Architecture Decision Record captures:
- Context: Why we needed to make a decision
- Decision: What we decided
- Consequences: What happens as a result
ADR Lifecycle
Proposed --> Accepted --> Deprecated --> Superseded
|
Rejected
Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.
Process
1. Choose a Template
Pick the format that fits the decision's complexity:
| Decision Complexity | Template | |---------------------|----------| | Simple tech selection | Y-Statement (one paragraph) | | Medium decision | Lightweight ADR (0.5-1 page) | | Significant architecture change | Standard MADR (1-2 pages) | | Retiring a decision | Deprecation ADR | | Major cross-team proposal | RFC Style (2-4 pages) |
Read reference/adr-templates.md for all template formats ready to copy-paste.
2. Write the ADR
- Start with context -- explain the problem before the solution
- List 2-3 real alternatives with honest pros/cons
- State the decision clearly
- Document both positive and negative consequences with specifics
3. Review and Approve
- Submit as PR with 2+ senior engineer reviewers
- Consult affected teams
- Assess security, cost, and reversibility implications
4. Maintain
- Update ADR index after acceptance
- Create implementation tickets
- Never edit accepted ADRs -- write new ones to supersede
Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).
Minimal Template (Copy-Paste Starter)
# ADR-NNNN: [Title]
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
## Context
[Why do we need to decide this? What's the problem?]
## Decision
We will [decision].
## Consequences
- **Good**: [benefits]
- **Bad**: [drawbacks]
- **Mitigations**: [how we'll address the bad]
Common Mistakes
| Mistake | Fix | |---------|-----| | Writing ADR after implementation | Write during design phase | | Listing only one option | Always include 2-3 real alternatives | | Vague consequences | Be specific: "Adds ~200ms latency to checkout" | | Editing accepted ADRs | Write new ADR that supersedes | | No decision drivers | List explicit criteria with priorities | | Missing rejected ADRs | Document rejected options too |
Directory Structure
docs/adr/
README.md # Index of all ADRs
template.md # Team's ADR template
0001-use-postgresql.md
0002-caching-strategy.md
Reference Files
| File | Contents |
|------|----------|
| reference/adr-templates.md | All formats: MADR, lightweight, Y-statement, deprecation, RFC |
| reference/adr-examples.md | Complete worked examples for each format |
| reference/adr-lifecycle.md | Status transitions, review checklists, automation with adr-tools |
Resources
Error Handling
Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.
Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.
Du fichier au premier essai
Le téléchargement contient exactement le contenu affiché sur cette fiche. Cette copie peut différer de la dernière version du dépôt source.
Consulter la source et ses fichiers annexesCe téléchargement contient uniquement SKILL.md. Les scripts, références, modèles et dépendances éventuels ne sont pas inclus. Récupérez les fichiers nécessaires depuis la source en conservant leur arborescence avant de poursuivre.
1. Télécharger le fichier
Télécharger SKILL.mdDepuis la racine d’un projet de test, enregistrez le fichier sous .skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md, ou utilisez la commande suivante. Ce dossier sert à examiner la skill avant son installation.
Commande pour macOS/Linux ou WSL : un shell POSIX et curl sont nécessaires. Sous Windows sans WSL, utilisez le bouton de téléchargement et créez le dossier manuellement.
mkdir -p '.skill-downloads/architecture-decision-records-adr-mmbiziz9' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/architecture-decision-records-adr-mmbiziz9/download' --output '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md.part' && mv '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md.part' '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md'2. Vérifier les prérequis
Lisez SKILL.md avant de l’utiliser. Si le fichier cite des scripts ou services externes, examinez-les et préparez les accès nécessaires dans votre environnement de test.
Outils déclarés par l’auteur (à vérifier dans votre agent) : Read
Aucune section de prérequis reconnue dans ce fichier. Cela ne signifie pas qu’il est autonome : les bibliothèques, outils et accès peuvent être cités ailleurs dans le contenu ou dans le dépôt source.
Les plateformes de la fiche sont des indications du catalogue. Les chemins ci-dessous suivent la documentation des outils ; ils ne prouvent pas que cette skill y a été exécutée. Aucune version minimale de ces outils n’est attestée pour cette fiche.
3. Charger la skill
Après vérification, copiez le dossier complet dans le projet avec l’une des commandes ci-dessous, puis ouvrez une nouvelle session de l’outil. La commande s’arrête si un dossier du même nom existe déjà : comparez les fichiers avant de le remplacer.
Claude Code
test -f '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md' && test -s '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/architecture-decision-records' && cp -R '.skill-downloads/architecture-decision-records-adr-mmbiziz9' '.claude/skills/architecture-decision-records'Cursor
test -f '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md' && test -s '.skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md' && mkdir -p '.cursor/skills' && test ! -e '.cursor/skills/architecture-decision-records' && cp -R '.skill-downloads/architecture-decision-records-adr-mmbiziz9' '.cursor/skills/architecture-decision-records'OpenSkills
OpenSkills doit déjà être installé. La procédure locale install/read est contrôlée avec OpenSkills 1.5.0, qui exige Node.js ≥ 20.6.0. Aucun slug du catalogue n’est résolu automatiquement.
Installation officielle d’OpenSkillsopenskills install './.skill-downloads/architecture-decision-records-adr-mmbiziz9'openskills read 'architecture-decision-records-adr-mmbiziz9'La lecture doit afficher le contenu du fichier installé et son dossier de base. Elle ne lance ni la skill ni ses dépendances.
Pour un agent qui lit AGENTS.md, synchronisez ensuite l’index. Cette commande modifie AGENTS.md : relisez le diff avant de l’utiliser.
openskills syncMode manuel ou autre outil : joignez SKILL.md à une conversation, ou ouvrez-le dans un agent capable de lire les fichiers. Ajoutez les ressources annexes nécessaires. Il n’existe pas de dossier universel reconnu par tous les outils.
4. Faire un premier essai
Utilisez une entrée courte et fictive : un endpoint d’API, un petit document ou un brief d’interface. Dans une nouvelle conversation, joignez le fichier ou donnez son chemin à l’agent, puis adaptez cette demande :
Lis .skill-downloads/architecture-decision-records-adr-mmbiziz9/SKILL.md et applique ses instructions à cet exemple : [décrire une entrée de test]. Indique les fichiers, dépendances ou accès qui manquent. Produis le résultat demandé par la skill sans inventer de données ni exécuter de script non examiné.Résultat attendu : une sortie correspondant aux instructions de la skill, ou une liste précise des prérequis manquants. Une simple confirmation de lecture ne valide pas le premier usage. Si une ressource externe est indisponible, ce parcours reste à tester.
Rédaction de docs Supabase
Documentation
Rédigez, éditez et révisez le contenu de la documentation Supabase : guides, tutoriels, références et partiels. Suivez les guides de style et les règles de validation MDX/TOML.
Créer un enregistrement de décision d'architecture
Documentation
Créer un nouveau ADR avec numérotation séquentielle, l'enregistrer dans le graphe AgentDB et le lier aux ADR associés.
Mise à jour de plan avec recherche approfondie
Documentation
Met à jour un document de plan en lançant des sous-agents en parallèle pour analyser un sujet sur tous les passes du compilateur, puis consolide les résultats.