203 lines
5.6 KiB
Markdown
203 lines
5.6 KiB
Markdown
# Multi-instance — Guide pratique
|
|
|
|
> Comment lancer plusieurs instances Claude Code simultanément sans conflit.
|
|
|
|
---
|
|
|
|
## Ce que "simultané" veut dire
|
|
|
|
Chaque instance est une **fenêtre Claude Code indépendante**, ouverte en même temps.
|
|
Elles partagent le même repo git — mais le protocole BSI garantit qu'elles ne s'écrasent pas.
|
|
|
|
```
|
|
Fenêtre 1 (coach/discussion) → lit, propose, décide
|
|
Fenêtre 2 (travail terrain) → écrit du code dans superoauth/
|
|
Fenêtre 3 (brain maintenance) → met à jour agents/, wiki/
|
|
|
|
Les 3 tournent en même temps. Zéro conflit si le protocole est respecté.
|
|
```
|
|
|
|
---
|
|
|
|
## Protocole de lancement d'une nouvelle instance
|
|
|
|
### 1. Ouvrir le claim (avant d'écrire quoi que ce soit)
|
|
|
|
```yaml
|
|
# claims/sess-YYYYMMDD-HHMM-<slug>.yml
|
|
sess_id: sess-20260317-1000-superoauth-auth
|
|
type: satellite
|
|
scope: superoauth/src/auth/ ← périmètre exclusif de cette instance
|
|
agent: satellite-boot
|
|
status: open
|
|
opened_at: "2026-03-17T10:00"
|
|
story_angle: "Refacto module auth — JWT + session"
|
|
satellite_type: code
|
|
satellite_level: leaf
|
|
parent_satellite: <sess-id-du-pilote>
|
|
on_done: notify → pilote
|
|
on_fail: signal → BLOCKED_ON pilote
|
|
```
|
|
|
|
Commiter + pusher immédiatement :
|
|
```bash
|
|
git add claims/sess-*.yml
|
|
bash scripts/brain-index-regen.sh
|
|
git add BRAIN-INDEX.md
|
|
git commit -m "bsi: open satellite sess-20260317-1000-superoauth-auth"
|
|
git push
|
|
```
|
|
|
|
→ Les autres instances voient le claim dans `brain-status.sh` et `BRAIN-INDEX.md`.
|
|
|
|
---
|
|
|
|
### 2. Avant chaque écriture — pre-flight
|
|
|
|
```bash
|
|
bash scripts/preflight-check.sh check "$SESS_ID" "<filepath>"
|
|
```
|
|
|
|
Les 6 checks (automatiques) :
|
|
| # | Check | Bloque si… |
|
|
|---|-------|------------|
|
|
| 1 | Claim open | claim fermé, en pause, ou gate:human actif |
|
|
| 1b | Parent ok | pilote parent en pause ou failed |
|
|
| 2 | Scope | fichier hors scope déclaré |
|
|
| 3 | Zone:kernel | instance non-kernel tente d'écrire agents/scripts/etc. |
|
|
| 4 | Lock | autre instance a un lock actif sur ce fichier |
|
|
| 5 | Circuit breaker | trop d'échecs consécutifs (défaut : 3) |
|
|
| 6 | Branch | mauvaise branche git vs theme_branch déclaré |
|
|
|
|
---
|
|
|
|
### 3. Mutex pour les fichiers partagés (mode rendering / multi-instances)
|
|
|
|
Si deux instances peuvent vouloir écrire le même fichier :
|
|
|
|
```bash
|
|
# Avant d'écrire
|
|
bash scripts/file-lock.sh acquire "<filepath>" "$SESS_ID" 30
|
|
# → exit 1 = déjà locké → attendre ou signal BLOCKED_ON
|
|
|
|
# [écriture]
|
|
|
|
# Après avoir écrit
|
|
bash scripts/file-lock.sh release "<filepath>" "$SESS_ID"
|
|
|
|
# Enregistrer le résultat pour le circuit breaker
|
|
bash scripts/preflight-check.sh reset "$SESS_ID" # succès
|
|
bash scripts/preflight-check.sh fail "$SESS_ID" # échec
|
|
```
|
|
|
|
---
|
|
|
|
### 4. Voir ce que font les autres instances
|
|
|
|
```bash
|
|
bash scripts/brain-status.sh # vue complète
|
|
bash scripts/brain-status.sh claims # qui travaille où
|
|
bash scripts/brain-status.sh locks # fichiers verrouillés
|
|
bash scripts/brain-status.sh signals # signaux en attente
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Pause d'urgence (arrêter tout)
|
|
|
|
```bash
|
|
# Depuis n'importe quelle instance ou le pilote
|
|
bash scripts/human-gate-ack.sh pause "<sess-pilote>" "raison"
|
|
# → tous les satellites enfants sont stoppés en cascade
|
|
# → pre-flight bloquera toute écriture
|
|
|
|
# Reprendre
|
|
bash scripts/human-gate-ack.sh resume "<sess-pilote>"
|
|
```
|
|
|
|
---
|
|
|
|
### 6. Close propre
|
|
|
|
```bash
|
|
# Ajouter result: dans le claim
|
|
# Puis :
|
|
bash scripts/brain-index-regen.sh
|
|
git add BRAIN-INDEX.md claims/<sess-id>.yml
|
|
git commit -m "bsi: close satellite <sess-id>"
|
|
git push
|
|
```
|
|
|
|
---
|
|
|
|
## Règles de non-collision
|
|
|
|
| Règle | Mécanisme |
|
|
|-------|-----------|
|
|
| Deux instances ne partagent pas le même scope | BRAIN-INDEX + pre-flight CHECK 2 |
|
|
| Pas d'écriture kernel sans mandat kernel | pre-flight CHECK 3 (soft lock) |
|
|
| Pas d'écriture simultanée sur le même fichier | file-lock.sh (BSI-v3-7) |
|
|
| Un satellite mort ne bloque pas les autres | TTL sur les locks (défaut 60min) |
|
|
| Un pilote paused stoppe ses enfants | cascade human-gate-ack.sh (BSI-v3-5) |
|
|
| 3 échecs consécutifs = arrêt forcé | circuit breaker pre-flight CHECK 5 |
|
|
|
|
---
|
|
|
|
## Cas d'usage typiques
|
|
|
|
### Coach + travail terrain simultanés
|
|
|
|
```
|
|
Instance 1 : scope brain/ → discussion, décisions, lecture
|
|
Instance 2 : scope superoauth/ → code, tests, deploy
|
|
```
|
|
Pas de conflit possible : scopes disjoints.
|
|
|
|
### Deux satellites sur le même projet
|
|
|
|
```
|
|
Instance A : scope superoauth/src/auth/ → JWT refacto
|
|
Instance B : scope superoauth/src/api/ → endpoints REST
|
|
```
|
|
Scopes disjoints → pas de lock nécessaire.
|
|
Si un fichier est partagé (ex: types.ts) → file-lock.sh obligatoire.
|
|
|
|
### Mode rendering (instance autonome projet)
|
|
|
|
```yaml
|
|
mode: rendering
|
|
scope: superoauth/ ← seul périmètre autorisé
|
|
```
|
|
- zone:kernel → BLOCKED_ON immédiat (pre-flight CHECK 3)
|
|
- circuit_breaker : 3 fails → arrêt + signal pilote
|
|
- mutex sur chaque fichier écrit (file-lock.sh)
|
|
|
|
### BaaS — client vs owner
|
|
|
|
```
|
|
kerneluser: true → owner — accès complet, peut forger le kernel
|
|
kerneluser: false → client — rendering mode, zone:project uniquement
|
|
```
|
|
|
|
---
|
|
|
|
## Référence rapide
|
|
|
|
```bash
|
|
# Voir l'état global
|
|
bash scripts/brain-status.sh
|
|
|
|
# Lancer le pre-flight avant d'écrire
|
|
bash scripts/preflight-check.sh check "$SESS_ID" "$FILE"
|
|
|
|
# Locker un fichier
|
|
bash scripts/file-lock.sh acquire "$FILE" "$SESS_ID" 30
|
|
|
|
# Pause d'urgence
|
|
bash scripts/human-gate-ack.sh pause "$SESS_PILOTE" "raison"
|
|
|
|
# Gate:human planifié
|
|
bash scripts/human-gate-ack.sh gate "$SESS_ID" "deploy ok ?"
|
|
bash scripts/human-gate-ack.sh approve "$SESS_ID"
|
|
```
|