docs(fr): translation of install-bmad channel and config rewrite
Reference commits3d824d4c,91a57499,0f852a38
This commit is contained in:
Emmanuel Atsé
parent
805d646822
commit
050ccff7a8
|
|
@ -1,116 +1,266 @@
|
|||
---
|
||||
title: "Comment installer BMad"
|
||||
description: Guide étape par étape pour installer BMad dans votre projet
|
||||
description: Installer, mettre à jour et épingler BMad pour le développement local, les équipes et CI
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
Utilisez la commande `npx bmad-method install` pour configurer BMad dans votre projet avec votre choix de modules et d'outils d'IA.
|
||||
|
||||
Si vous souhaitez utiliser un installateur non interactif et fournir toutes les options d'installation en ligne de commande, consultez [ce guide](./non-interactive-installation.md).
|
||||
Utilisez `npx bmad-method install` pour configurer BMad dans votre projet. Une seule commande gère les premières installations, les mises à niveau, le changement de canal et les exécutions CI scriptées. Cette page couvre tout cela.
|
||||
|
||||
## Quand l'utiliser
|
||||
|
||||
- Démarrer un nouveau projet avec BMad
|
||||
- Ajouter BMad à une base de code existante
|
||||
- Mettre à jour une installation BMad existante
|
||||
- Ajouter ou retirer des modules sur une installation existante
|
||||
- Basculer un module sur main-HEAD ou l'épingler à une version spécifique
|
||||
- Scripter des installations pour des pipelines CI, des Dockerfiles ou des déploiements en entreprise
|
||||
|
||||
:::note[Prérequis]
|
||||
|
||||
- **Node.js** 20.12+ (requis pour l'installateur)
|
||||
- **Git** (recommandé)
|
||||
- **Outil d'IA** (Claude Code, Cursor, ou similaire)
|
||||
- **Git** (pour cloner les modules externes)
|
||||
- **Un outil d'IA** tel que Claude Code ou Cursor (exécutez `npx bmad-method install --list-tools` pour voir tous les outils supportés)
|
||||
|
||||
:::
|
||||
|
||||
## Étapes
|
||||
|
||||
### 1. Lancer l'installateur
|
||||
## Première installation (méthode rapide)
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
:::tip[Vous voulez la dernière version préliminaire ?]
|
||||
Utilisez le dist-tag `next` :
|
||||
L'assistant interactif vous pose cinq questions :
|
||||
|
||||
1. Le répertoire d'installation (par défaut le répertoire de travail courant)
|
||||
2. Quels modules installer (cases à cocher pour core, bmm, bmb, cis, gds, tea)
|
||||
3. **« Ready to install (all stable)? »** — Oui accepte le dernier tag publié pour chaque module externe
|
||||
4. Quels outils/IDE d'IA intégrer (claude-code, cursor et d'autres)
|
||||
5. La configuration par module (nom, langue, dossier de sortie)
|
||||
|
||||
En acceptant les valeurs par défaut, vous obtenez la dernière version stable de chaque module, configurée pour votre outil choisi.
|
||||
|
||||
:::tip[Vous voulez juste la dernière préversion ?]
|
||||
|
||||
```bash
|
||||
npx bmad-method@next install
|
||||
```
|
||||
|
||||
Cela vous permet d'obtenir les nouvelles modifications plus tôt, avec un risque plus élevé de changements que l'installation par défaut.
|
||||
Exécute l'installateur de préversion, qui fournit un snapshot plus récent de core et bmm. Davantage de changements, avec un délai réduit entre le développement et la publication.
|
||||
:::
|
||||
|
||||
:::tip[Version de développement]
|
||||
Pour installer la dernière version depuis la branche main (peut être instable) :
|
||||
## Choisir une version spécifique
|
||||
|
||||
Deux axes indépendants contrôlent ce qui se retrouve sur le disque.
|
||||
|
||||
### Axe 1 : canaux des modules externes
|
||||
|
||||
Chaque module externe — bmb, cis, gds, tea, et tout module communautaire — s'installe via l'un des trois canaux suivants :
|
||||
|
||||
| Canal | Ce qui est installé | Pour qui |
|
||||
|-------------------|--------------------------------------------------------------------------------------|-----------------------------------------------|
|
||||
| `stable` (défaut) | Le plus haut tag semver publié. Les préversions comme `v2.0.0-alpha.1` sont exclues. | La plupart des utilisateurs |
|
||||
| `next` | Le HEAD de la branche main au moment de l'installation | Contributeurs, early adopters |
|
||||
| `pinned` | Un tag spécifique de votre choix | Installations entreprise, reproductibilité CI |
|
||||
|
||||
Les canaux sont définis module par module. Vous pouvez exécuter bmb sur `next` tout en laissant cis sur `stable` — les options ci-dessous permettent de les combiner librement.
|
||||
|
||||
### Axe 2 : version du binaire de l'installateur
|
||||
|
||||
Le paquet npm `bmad-method` lui-même a deux dist-tags :
|
||||
|
||||
| Commande | Ce que vous obtenez |
|
||||
|---------------------------------------|---------------------------------------------------------------------------------------|
|
||||
| `npx bmad-method install` (`@latest`) | Dernière version stable de l'installateur |
|
||||
| `npx bmad-method@next install` | Dernière préversion de l'installateur, publiée automatiquement à chaque push sur main |
|
||||
|
||||
**Le binaire de l'installateur détermine vos versions de core et bmm.** Ces deux modules sont embarqués dans le paquet de l'installateur plutôt que clonés depuis des dépôts séparés.
|
||||
|
||||
### Pourquoi core et bmm n'ont pas leur propre canal
|
||||
|
||||
Ils sont liés au binaire de l'installateur que vous avez exécuté :
|
||||
|
||||
- `npx bmad-method install` → core et bmm stables les plus récents
|
||||
- `npx bmad-method@next install` → core et bmm en préversion
|
||||
- `node /chemin/vers/checkout-local/tools/installer/bmad-cli.js install` → ce que votre checkout local contient
|
||||
|
||||
`--pin bmm=v6.3.0` et `--next=bmm` n'ont aucun effet sur les modules intégrés (l'installateur vous avertit si vous tentez de les utiliser). Une prochaine version détachera bmm du paquet de l'installateur ; une fois publiée, bmm disposera d'un sélecteur de canal dédié, comme c'est le cas pour bmb aujourd'hui.
|
||||
|
||||
## Mettre à jour une installation existante
|
||||
|
||||
Exécuter `npx bmad-method install` dans un répertoire contenant déjà `_bmad/` affiche un menu :
|
||||
|
||||
| Choix | Ce qu'il fait |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Quick Update** | Réexécute l'installation avec vos paramètres existants. Rafraîchit les fichiers, applique les correctifs et les mises à niveau mineures du canal stable, refuse les mises à niveau majeures. Rapide, non interactif. |
|
||||
| **Modify Install** | Flux interactif complet. Ajoutez ou retirez des modules, reconfigurez les paramètres, examinez et, si besoin, modifiez les canaux des modules existants. |
|
||||
|
||||
### Invites de mise à niveau
|
||||
|
||||
Quand Modify détecte un tag stable plus récent pour un module que vous avez installé sur `stable`, il classe le diff et vous invite en conséquence :
|
||||
|
||||
| Type de mise à niveau | Exemple | Défaut |
|
||||
| --------------------- | --------------- | ------ |
|
||||
| Patch | v1.7.0 → v1.7.1 | O |
|
||||
| Mineure | v1.7.0 → v1.8.0 | O |
|
||||
| Majeure | v1.7.0 → v2.0.0 | **N** |
|
||||
|
||||
Les mises à niveau majeures sont refusées par défaut (N) car les changements cassants se manifestent souvent comme une « instabilité » quand ils ne sont pas attendus. L'invite inclut une URL vers les notes de version GitHub pour que vous puissiez lire ce qui a changé avant d'accepter.
|
||||
|
||||
Avec `--yes`, les mises à niveau patch et mineure s'appliquent automatiquement. Les majeures restent bloquées — utilisez `--pin <code>=<nouveau-tag>` pour les accepter de manière non interactive.
|
||||
|
||||
### Changer le canal d'un module
|
||||
|
||||
**En mode interactif :** choisissez Modify → répondez **Oui** à « Review channel assignments? » → chaque module externe offre Conserver, Basculer vers stable, Basculer vers next, ou Épingler à un tag.
|
||||
|
||||
**En ligne de commande :** les recettes dans la section suivante couvrent les cas courants.
|
||||
|
||||
## Installations CI sans interaction
|
||||
|
||||
### Référence des options
|
||||
|
||||
| Option | Objectif |
|
||||
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `--yes`, `-y` | Ignorer toutes les invites ; accepter les valeurs des options + les défauts |
|
||||
| `--directory <chemin>` | Installer dans ce répertoire (défaut : répertoire de travail courant) |
|
||||
| `--modules <a,b,c>` | Ensemble exact de modules. Core est ajouté automatiquement. Ce n'est pas un delta — listez tout ce que vous voulez conserver. |
|
||||
| `--tools <a,b>` | Sélection d'IDE/outil. Requis pour les nouvelles installations `--yes`. Exécutez `--list-tools` pour les IDs valides. |
|
||||
| `--list-tools` | Afficher tous les IDs d'outils/IDE supportés (avec les répertoires cibles) et quitter. |
|
||||
| `--action <type>` | `install`, `update` ou `quick-update`. La valeur par défaut dépend de l'état de l'installation. |
|
||||
| `--custom-source <urls>` | Installer des modules personnalisés depuis des URLs Git ou des chemins locaux |
|
||||
| `--channel <stable\|next>` | Appliquer à tous les externes (alias `--all-stable` / `--all-next`) |
|
||||
| `--all-stable` | Alias pour `--channel=stable` |
|
||||
| `--all-next` | Alias pour `--channel=next` |
|
||||
| `--next=<code>` | Mettre un module sur next. Répétable. |
|
||||
| `--pin <code>=<tag>` | Épingler un module à un tag spécifique. Répétable. |
|
||||
| `--set <module>.<clé>=<valeur>` | Définir toute option de config de module de manière non interactive (recommandé — voir [Substitutions de config de module](#substitutions-de-config-de-module)). Répétable. |
|
||||
| `--list-options [module]` | Afficher chaque clé `--set` pour les modules intégrés et officiels en cache local, puis quitter. Passez un code de module pour limiter à un seul module. |
|
||||
| `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder` | Raccourcis historiques équivalents à `--set core.<clé>=<valeur>` (toujours supportés) |
|
||||
|
||||
Priorité en cas de chevauchement des options : `--pin` bat `--next=` bat `--channel` / `--all-*` bat le défaut du registre (`stable`).
|
||||
|
||||
:::note[Exemple de résolution]
|
||||
`--all-next --pin cis=v0.2.0` met bmb, gds et tea sur next tout en épinglant cis à v0.2.0.
|
||||
:::
|
||||
|
||||
### Recettes
|
||||
|
||||
**Installation par défaut — dernière version stable pour tout :**
|
||||
|
||||
```bash
|
||||
npx github:bmad-code-org/BMAD-METHOD install
|
||||
npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code
|
||||
```
|
||||
|
||||
**Installation entreprise verrouillée — reproductible à l'octet près :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
--modules bmm,bmb,cis \
|
||||
--pin bmb=v1.7.0 --pin cis=v0.2.0 \
|
||||
--tools claude-code
|
||||
```
|
||||
|
||||
**Bleeding edge — externes sur le HEAD de main :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code
|
||||
```
|
||||
|
||||
**Ajouter un module à une installation existante** (conserver tout le reste) :
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --action update \
|
||||
--modules bmm,bmb,gds
|
||||
```
|
||||
|
||||
`--tools` est omis intentionnellement — `--action update` réutilise les outils configurés lors de la première installation.
|
||||
|
||||
**Mixer les canaux — bmb sur next, gds sur stable :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --action update \
|
||||
--modules bmm,bmb,cis,gds \
|
||||
--next=bmb
|
||||
```
|
||||
|
||||
### Substitutions de config de module
|
||||
|
||||
`--set <module>.<clé>=<valeur>` vous permet de définir toute option de config de module de manière non interactive. Cette option est répétable et s'adapte à chaque module — présent et futur. L'option est appliquée comme un correctif post-installation : l'installateur exécute d'abord son flux normal, puis `--set` insère ou met à jour chaque valeur dans `_bmad/config.toml` (portée équipe) ou `_bmad/config.user.toml` (portée utilisateur), et dans `_bmad/<module>/config.yaml` pour que les valeurs déclarées soient conservées à la prochaine installation.
|
||||
|
||||
**Exemple — installer bmm avec des connaissances projet et un niveau de compétence explicites :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
--modules bmm \
|
||||
--tools claude-code \
|
||||
--set bmm.project_knowledge=research \
|
||||
--set bmm.user_skill_level=expert
|
||||
```
|
||||
|
||||
**Découvrir les clés disponibles pour un module :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --list-options bmm
|
||||
```
|
||||
|
||||
`--list-options` (sans argument) liste chaque clé que l'installateur peut trouver localement — modules intégrés (`core`, `bmm`) plus tous les modules officiels actuellement en cache. Le cache est par machine et peut être vidé, donc les modules officiels précédemment installés n'apparaîtront pas sur un nouveau checkout ou un worker CI éphémère tant qu'ils ne sont pas réinstallés. Les modules communautaires et personnalisés ne sont pas énumérés ici ; lisez directement le `module.yaml` du module pour voir les clés qu'il déclare.
|
||||
|
||||
**Comment ça fonctionne :**
|
||||
|
||||
- **Routage.** L'étape de correctif cherche `[modules.<module>] <clé>` (ou `[core] <clé>`) dans `config.user.toml` en premier ; si elle y est trouvée, elle met à jour ce fichier. Sinon elle écrit dans le `config.toml` de portée équipe. Ainsi, les clés de portée utilisateur (ex. `core.user_name`, `bmm.user_skill_level`) finissent dans `config.user.toml` et les clés de portée équipe dans `config.toml`, correspondant à la partition utilisée par l'installateur.
|
||||
- **Valeurs littérales.** La valeur est écrite exactement comme vous l'avez fournie — aucun rendu de template `result:`. Pour obtenir la valeur résolue (ex. `{project-root}/research`), passez-la explicitement : `--set bmm.project_knowledge='{project-root}/research'`.
|
||||
- **Persistance, clés déclarées.** Les valeurs pour les clés déclarées dans `module.yaml` sont conservées entre les installations car elles sont aussi écrites dans `_bmad/<module>/config.yaml`, que l'installateur lit comme valeur par défaut de l'invite lors de la prochaine exécution.
|
||||
- **Persistance, clés non déclarées.** Une valeur pour une clé que le schéma du module ne déclare pas est enregistrée dans `config.toml` pour l'installation courante mais ne sera pas réécrite à la prochaine installation (le partitionneur strict au schéma du manifeste ignore les clés inconnues). Repassez `--set` pour qu'elle soit persistante, ou éditez `_bmad/config.toml` directement.
|
||||
- **Pas de validation.** Les valeurs `single-select` ne sont pas vérifiées contre les choix autorisés, et les clés inconnues ne sont pas rejetées — la valeur fournie est écrite telle quelle.
|
||||
- **Modules non présents dans `--modules`.** Définir une valeur pour un module que vous n'avez pas inclus affiche un avertissement et la valeur est ignorée (aucun fichier n'est créé pour un module non installé).
|
||||
|
||||
Les raccourcis historiques de core (`--user-name`, `--output-folder`, etc.) fonctionnent toujours et restent documentés pour la rétrocompatibilité, mais `--set core.user_name=...` est équivalent.
|
||||
|
||||
:::note[Fonctionne avec quick-update]
|
||||
`--set` est un correctif post-installation, il s'applique donc de la même manière quel que soit le type d'action. Avec `bmad install --action quick-update` (ou `--yes` sur une installation existante, où quick-update est le défaut), `--set` met à jour les fichiers de configuration centraux à la fin comme une installation normale.
|
||||
:::
|
||||
|
||||
### 2. Choisir l'emplacement d'installation
|
||||
:::caution[Limitation de débit sur les IPs partagées]
|
||||
Les appels anonymes à l'API GitHub sont limités à 60/heure par IP. Une seule installation fait un appel API par module externe pour résoudre le tag stable. Les bureaux derrière NAT, les pools de runners CI et les VPN peuvent collectivement épuiser cette limite.
|
||||
|
||||
L'installateur vous demandera où installer les fichiers BMad :
|
||||
|
||||
- Répertoire courant (recommandé pour les nouveaux projets si vous avez créé le répertoire vous-même et l'exécutez depuis ce répertoire)
|
||||
- Chemin personnalisé
|
||||
|
||||
### 3. Sélectionner vos outils d'IA
|
||||
|
||||
Choisissez les outils d'IA que vous utilisez :
|
||||
|
||||
- Claude Code
|
||||
- Cursor
|
||||
- Autres
|
||||
|
||||
Chaque outil a sa propre façon d'intégrer les skills. L'installateur crée de petits fichiers de prompt pour activer les workflows et les agents — il les place simplement là où votre outil s'attend à les trouver.
|
||||
|
||||
:::note[Activer les skills]
|
||||
Certaines plateformes nécessitent que les skills soient explicitement activés dans les paramètres avant d'apparaître. Si vous installez BMad et ne voyez pas les skills, vérifiez les paramètres de votre plateforme ou demandez à votre assistant IA comment activer les skills.
|
||||
Définissez `GITHUB_TOKEN=<personal access token>` dans l'environnement pour augmenter la limite à 5000/heure par compte. Tout PAT avec accès en lecture aux dépôts publics fonctionne ; aucune portée spécifique n'est requise.
|
||||
:::
|
||||
|
||||
### 4. Choisir les modules
|
||||
## Ce qui a été installé
|
||||
|
||||
L'installateur affiche les modules disponibles. Sélectionnez ceux dont vous avez besoin — la plupart des utilisateurs veulent simplement **méthode BMad** (le module de développement logiciel).
|
||||
Après toute installation, `_bmad/_config/manifest.yaml` enregistre exactement ce qui est sur le disque :
|
||||
|
||||
### 5. Suivre les instructions
|
||||
|
||||
L'installateur vous guide pour le reste — paramètres, intégrations d'outils, etc.
|
||||
|
||||
## Ce que vous obtenez
|
||||
|
||||
```text
|
||||
votre-projet/
|
||||
├── _bmad/
|
||||
│ ├── bmm/ # Vos modules sélectionnés
|
||||
│ │ └── config.yaml # Paramètres du module (si vous devez les modifier)
|
||||
│ ├── core/ # Module core requis
|
||||
│ └── ...
|
||||
├── _bmad-output/ # Artefacts générés
|
||||
├── .claude/ # Skills Claude Code (si vous utilisez Claude Code)
|
||||
│ └── skills/
|
||||
│ ├── bmad-help/
|
||||
│ ├── bmad-persona/
|
||||
│ └── ...
|
||||
└── .cursor/ # Skills Cursor (si vous utilisez Cursor)
|
||||
└── skills/
|
||||
└── ...
|
||||
```yaml
|
||||
modules:
|
||||
- name: bmb
|
||||
version: v1.7.0 # le tag, ou "main" pour next
|
||||
channel: stable # stable | next | pinned
|
||||
sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
|
||||
source: external
|
||||
repoUrl: https://github.com/bmad-code-org/bmad-builder
|
||||
```
|
||||
|
||||
## Vérifier l'installation
|
||||
Le champ `sha` est écrit pour les modules basés sur git (externes, communautaires et personnalisés par URL). Les modules intégrés (core, bmm) et les modules personnalisés par chemin local n'en ont pas — leur code voyage avec le binaire de l'installateur ou votre système de fichiers, pas un ref clonable.
|
||||
|
||||
Exécutez `bmad-help` pour vérifier que tout fonctionne et voir quoi faire ensuite.
|
||||
Pour la reproductibilité inter-machines, ne comptez pas sur la réexécution de la même commande `--modules`. Les installations sur canal stable résolvent vers le plus haut tag publié **au moment de l'installation**, donc une réexécution ultérieure obtiendra les versions publiées entre-temps. Convertissez les tags enregistrés de `manifest.yaml` en options `--pin` explicites sur la machine cible, par ex. :
|
||||
|
||||
**BMad-Help est votre guide intelligent** qui va :
|
||||
- Confirmer que votre installation fonctionne
|
||||
- Afficher ce qui est disponible en fonction de vos modules installés
|
||||
- Recommander votre première étape
|
||||
|
||||
Vous pouvez aussi lui poser des questions :
|
||||
```
|
||||
bmad-help Je viens d'installer, que dois-je faire en premier ?
|
||||
bmad-help Quelles sont mes options pour un projet SaaS ?
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmb,cis \
|
||||
--pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code
|
||||
```
|
||||
|
||||
## Résolution de problèmes
|
||||
|
||||
**L'installateur affiche une erreur** — Copiez-collez la sortie dans votre assistant IA et laissez-le résoudre le problème.
|
||||
### « Could not resolve stable tag » ou « API rate limit exceeded »
|
||||
|
||||
**L'installateur a fonctionné mais quelque chose ne fonctionne pas plus tard** — Votre IA a besoin du contexte BMad pour vous aider. Consultez [Comment obtenir des réponses à propos de BMad](./get-answers-about-bmad.md) pour savoir comment diriger votre IA vers les bonnes sources.
|
||||
Vous avez atteint la limite anonyme de 60/heure de GitHub. Définissez `GITHUB_TOKEN` et réessayez. Si vous avez déjà un token défini, il peut être expiré ou limité sur son propre budget — essayez un token différent ou attendez la réinitialisation horaire.
|
||||
|
||||
### « Tag 'vX.Y.Z' not found »
|
||||
|
||||
Le tag que vous avez passé à `--pin` n'existe pas dans le dépôt du module. Consultez la page des releases du dépôt sur GitHub pour les tags valides.
|
||||
|
||||
### Une installation épinglée continue de se mettre à niveau
|
||||
|
||||
Les installations épinglées ne se mettent pas à niveau. Quick-update applique les correctifs et les mises à niveau mineures uniquement sur le canal stable ; il ne touche pas `pinned` ou `next`. Si une installation épinglée a changé, ouvrez `_bmad/_config/manifest.yaml` — `channel: pinned` plus un `version` et `sha` fixes doivent rester stables d'une exécution à l'autre, sauf écrasement explicite via les options.
|
||||
|
||||
### `--pin bmm=X` n'a rien fait
|
||||
|
||||
bmm est un module intégré — `--pin` et `--next=` ne s'appliquent pas. Utilisez `npx bmad-method@next install` pour un core/bmm en préversion, ou clonez le dépôt bmad-bmm et exécutez l'installateur localement pour obtenir les modifications non publiées.
|
||||
|
|
|
|||
Loading…
Reference in New Issue