Prise en main de gstack : maîtrisez seul tout le flux de conception produit, revue de code, QA et déploiement

Difficulté : Débutant | Durée : 15 minutes | Bénéfice : Maîtriser l'usage de gstack et comprendre la philosophie du workflow de programmation IA

---

Lecteurs cibles

Vous utilisez déjà Claude Code pour coder, mais vous avez le sentiment qu'il manque un "esprit d'équipe" lorsque vous travaillez seul sur un produit — personne pour réviser l'architecture, personne pour lancer la QA, personne pour valider le design. Vous voulez transformer la programmation IA d'une "auto-complétion avancée" en une "véritable équipe d'ingénierie" ?

Cet article est fait pour vous. De l'installation à l'exécution d'un workflow complet /office-hours → /ship, vous découvrirez comment gstack transforme une personne seule en une véritable armée.

Prérequis : Bases de Git et de la ligne de commande, connaissance de l'usage basique de Claude Code.

---

Dépendances et environnement

Adresse du dépôt : https://github.com/garrytan/gstack

Systèmes d'exploitation : macOS, Linux (Git Bash), Windows 11 (WSL ou Git Bash)

---

Structure complète du projet

Après clonage local, la structure du répertoire principal de gstack est la suivante :

gstack/
├── browse/                  # Moteur de navigation headless persistant (Playwright + couche CDP personnalisée)
│   ├── src/                 # CLI + Serveur HTTP + implémentation des commandes
│   └── dist/                # Binaire unique compilé (~58Mo)
├── office-hours/            # Dialogue produit style YC, lance tous les documents de conception
├── plan-ceo-review/         # Revue stratégique produit niveau CEO (périmètre, positionnement, priorités)
├── plan-eng-review/         # Revue d'architecture technique (flux de données, machines à états, plan de test)
├── plan-design-review/      # Revue de design (score UI/UX, détection de "slop")
├── design-consultation/     # Construction d'un système de design de zéro
├── review/                  # Revue de code PR (correction automatique + classification des problèmes)
├── investigate/             # Débogage systématique des causes racines (Loi d'Airain : pas de correction sans enquête)
├── qa/                      # Tests QA + corrections par commits atomiques automatiques
├── qa-only/                # Mode rapport QA uniquement (rapporte sans modifier le code)
├── cso/                    # Mode Chef de la Sécurité (OWASP Top 10 + STRIDE)
├── ship/                   # Workflow de publication (synchro main → test → push → création de PR)
├── land-and-deploy/        # Fusion PR → déploiement → vérification de la santé en production
├── canary/                 # Boucle de monitoring post-mise en ligne (taux d'erreur, régression de performance)
├── benchmark/              # Tests de performance (Core Web Vitals, poids des pages)
├── document-release/       # Mise à jour synchrone de la documentation après publication
├── retro/                  # Réunion de rétrospective (supporte le mode multi-projets global)
├── codex/                  # Deuxième avis via OpenAI Codex (analyse croisée de modèles)
├── browse/                 # Automatisation du navigateur (Chromium persistant, ~100ms/commande)
├── setup-browser-cookies/  # Importation de cookies depuis un navigateur réel (Chrome/Arc/Brave/Edge)
├── setup-deploy/           # Assistant de configuration de déploiement (détection plateforme, URL, commandes)
├── careful/                # Avertissement pour commandes dangereuses (rm -rf / DROP TABLE, etc.)
├── freeze/                 # Verrouillage du périmètre d'édition pour éviter les modifications hors limites
├── guard/                  # Combinaison de careful + freeze, équivalent au mode sécurité maximale
├── unfreeze/               # Annulation du mode freeze
├── autoplan/               # Chaînage automatique : flux complet CEO → Design → Ingénierie
└── bin/                    # Ensemble d'outils CLI (gstack-config / gstack-analytics, etc.)

28 compétences couvrant le cycle de vie complet : Conception → Revue d'architecture → Développement → Sécurité → QA → Déploiement → Rétrospective.

---

Guide pas à pas

Étape 1 — Installation de gstack

Installation globale (recommandée)

Ouvrez Claude Code, collez la commande suivante dans la boîte de dialogue, Claude effectuera automatiquement les étapes restantes :

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

Le script ./setup va :

1. Détecter l'environnement système (Bun / Node / Git)
2. Compiler le binaire browse/dist/browse (bun build --compile, environ 10 secondes)
3. Enregistrer les 28 compétences dans Claude Code

Une fois l'installation terminée, vous devez informer Claude Code de la configuration de gstack. Ajoutez le contenu suivant au fichier CLAUDE.md à la racine de votre projet :

## gstack
Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.
Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
/design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse,
/qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro,
/investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard,
/unfreeze, /gstack-upgrade.

Installation au niveau du projet (pour l'équipe)

Si vous souhaitez que les membres de l'équipe bénéficient de gstack après un git clone :

cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup

Vérifier l'installation

# Vérifier si le binaire existe
ls ~/.claude/skills/gstack/browse/dist/browse

# Vérifier si les compétences sont enregistrées, tapez dans Claude Code :
/help
# Vous devriez voir les compétences liées à gstack dans la liste des commandes disponibles

---

Étape 2 — Exécuter votre premier workflow complet

C'est l'usage central de gstack : 5 commandes pour couvrir tout le flux, de la conception à la publication. Testons cela sur un projet réel local.

2.1 Définir le produit avec /office-hours

/office-hours

gstack lance le mode YC Office Hours — il vous posera 6 questions obligatoires pour recadrer votre vision produit. L'essentiel est d'exprimer les véritables points de douleur, plutôt que de décrire directement les fonctionnalités.

Exemple de dialogue :

Vous : Je veux une fonction qui génère un briefing chaque matin basé sur mon calendrier.

gstack : Je réexamine votre cadre. Vous parlez d'un "générateur de briefing", mais les douleurs que vous décrivez sont :
1. Plusieurs calendriers Google, informations obsolètes
2. Temps de préparation trop long
3. Résultats insuffisants
En réalité, vous construisez un "Assistant Personnel IA en Chef".

Voulez-vous redéfinir le périmètre ? Ou dites-moi pourquoi le périmètre original est le bon ?

À la fin du dialogue, gstack génère un document de conception qui alimentera automatiquement les compétences de revue suivantes.

2.2 Revoir la stratégie avec /plan-ceo-review

/plan-ceo-review

gstack lit le document de conception précédent et effectue une analyse en quatre quadrants du point de vue CEO/Fondateur :

• Expansion : Où étendre le périmètre ?
• Expansion sélective : Garder le cœur, que supprimer ?
• Maintenir le périmètre : La taille actuelle est idéale
• Réduction : Se concentrer sur le point d'entrée le plus étroit

Il propose également 3 pistes d'implémentation, avec une comparaison de temps Homme-jour vs IA :

2.3 Revue de code avec /review

Une fois le code écrit, lancez sur votre branche :

/review

gstack va :

• Corriger automatiquement les problèmes évidents (ex: cas limites non gérés)
• Utiliser AskUserQuestion pour les problèmes complexes afin de solliciter votre avis
• Générer un rapport classé : [AUTO-FIXED] / [ASK] / [WARN]

Exemple de sortie :

[/review] Analyse terminée :

[AUTO-FIXED] 2 points
  - src/api/calendar.ts:67 — Manque gestion du rejet de Promise
  - src/utils/date.ts:12 — Décalage horaire codé en dur

[ASK] Race condition in refresh loop — Solution recommandée :
A) Ajouter un verrou mutex (plus sûr, +15 lignes)
B) Ajouter un debounce (plus simple, +5 lignes)
Recommandation A, pour traiter tous les cas de concurrence.

2.4 Tester votre application avec /qa

# Remplacez par votre URL de staging
/qa https://staging.myapp.com

Le /qa de gstack lance un navigateur Chromium persistant (réutilisant les cookies et sessions) pour automatiquement :

1. Ouvrir la page, prendre des captures d'écran
2. Cliquer sur les parcours critiques (Connexion → Cœur de métier → Cas limites)
3. Découvrir les bugs → Corriger via commits atomiques → Valider à nouveau
4. Générer des tests de régression pour chaque correction

Différence avec les tests automatisés classiques : Les tests classiques vérifient vos assertions. /qa cherche activement les scénarios sans assertions — états vides, états d'erreur, limites de concurrence.

2.5 Publier avec /ship

/ship

/ship exécute le pipeline complet de publication :

# Équivalent manuel :
git checkout main && git pull
git merge your-branch
pnpm test           # ou votre commande de test
pnpm build
git push
gh pr create        # Ouvre automatiquement la PR avec un résumé des changements

Chaque étape a une checklist ; on ne continue que si elle passe. En cas de problème, il s'arrête pour attendre votre décision.

---

Étape 3 — Approfondir les compétences par phase

3.1 Phase de conception : office-hours et série plan

L'objectif est de transformer une "idée" en "document de conception" lisible par toutes les étapes suivantes.

/office-hours — Ce n'est pas un brainstorming, c'est un recadrage produit. gstack va :

• Identifier les besoins réels non exprimés (déduction via les douleurs)
• Challenger vos hypothèses par défaut
• Générer un parcours d'implémentation avec des jalons concrets

/plan-ceo-review — Analyse le document selon la taille du marché, la concurrence et les priorités.

/plan-eng-review — Verrouille l'architecture technique :

• Schémas de flux de données ASCII
• Conception de machines à états
• Analyse des chemins d'échec
• Matrice de test (au moins un test par branche)

3.2 Phase de développement : review et investigate

La logique de /review est de "trouver les bugs qui passent l'IC mais font exploser la production". Il ne remplace pas le linter, il fait de l'analyse sémantique :

• Erreurs logiques (conditions manquantes, branches déséquilibrées)
• Problèmes de concurrence (race condition, pattern de deadlock)
• Risques de sécurité (injection, contournement d'authentification)

/investigate est dédié au débogage. Lorsqu'un bug réapparaît, lancez :

/investigate

gstack va :

1. Émettre des hypothèses
2. Les vérifier une par une (sans corriger, juste enquêter)
3. S'arrêter une fois la cause identifiée (Loi d'Airain : pas de correction sans enquête)

3.3 Phase de publication : ship, land-and-deploy, canary

/ship          # Après validation de revue → Ouvrir PR
/land-and-deploy  # Fusion PR → Déploiement → Vérification santé prod
/canary        # Surveillance continue pendant 30 min après déploiement

/canary surveille trois indicateurs :

• Taux d'erreur console : Hausse des exceptions JavaScript
• Régression de performance : Dégradation des Core Web Vitals
• Taux d'échec des pages : Pages critiques renvoyant des erreurs 500

Si un indicateur est anormal, une alerte automatique est lancée et peut déclencher un rollback.

---

Étape 4 — Automatisation du navigateur en pratique

/browse est la capacité la plus unique de gstack : il fait tourner un processus Chromium résident qui reçoit des commandes via une API HTTP locale, répondant en ~100ms avec une réutilisation réelle de session.

4.1 Utilisation de base

# Aller sur une page
$B goto https://example.com

# Voir les éléments interactifs (numérotés @e1, @e2 ...)
$B snapshot -i

# Cliquer sur le 3ème élément
$B click @e3

# Remplir un formulaire
$B fill @e1 "[email protected]"
$B fill @e2 "password123"

# Capture d'écran
$B screenshot /tmp/result.png

4.2 Vérifier les changements UI

# Capture de référence
$B snapshot -i

# Effectuer l'action
$B click @e5

# Comparaison (affiche uniquement ce qui a changé)
$B snapshot -D

Le flag -D affiche un diff unifié montrant quels éléments sont apparus, ont disparu ou ont changé de contenu.

4.3 Tester avec une session réelle

Importer les cookies depuis votre navigateur :

# Sélecteur interactif (macOS supporte Chrome / Arc / Brave / Edge)
$B cookie-import-browser

# Spécifier un domaine directement
$B cookie-import-browser chrome --domain .github.com

4.4 Tests responsifs

# Génère simultanément des captures Mobile / Tablette / Bureau
$B goto https://yourapp.com
$B responsive /tmp/layout
# Sortie : layout-mobile.png, layout-tablet.png, layout-desktop.png

---

Étape 5 — Collaboration d'équipe et expert

5.1 Installation Vendored en détail

L'installation globale est idéale pour l'usage personnel, l'installation Vendored permet le partage en équipe :

# À la racine du projet
git clone https://github.com/garrytan/gstack.git .claude/skills/gstack
cd .claude/skills/gstack
./setup

Points clés :

• Il s'agit d'un instantané (snapshot), pas d'un sous-module
• Le dossier .git est supprimé pour ne pas polluer votre historique
• Mise à jour : chaque membre tire les derniers changements puis relance ./setup

5.2 Sprints parallèles et Conductor

La structure de gstack supporte nativement le parallélisme. Un seul Claude Code est une "personne", mais plusieurs instances peuvent exécuter différents sprints en parallèle.

Conductor (recommandé par gstack) permet de lancer plusieurs instances Claude Code simultanément dans des espaces de travail séparés :

• Instance A : /office-hours pour redéfinir le produit
• Instance B : Implémentation d'une fonctionnalité
• Instance C : /review sur une autre branche
• Instance D : /qa sur l'environnement de staging

Toutes les instances partagent le même dépôt Git. Il n'y a pas de conflit — le modèle de branches de Git gère naturellement l'isolation.

5.3 Mode Sécurité

Pour le code de production, activez les garde-fous :

/guard   # = /careful + /freeze

• /careful : Les commandes dangereuses (rm -rf, DROP TABLE, git push --force) demandent confirmation
• /freeze : Limite l'édition de fichiers aux répertoires spécifiés, évitant les modifications accidentelles de prod lors du debug
• /unfreeze : Désactive le gel

---

Dépannage

1. Les compétences ne s'affichent pas

# Aller dans le dossier gstack et lancer setup manuellement
cd ~/.claude/skills/gstack && ./setup

Si la compilation échoue, vérifiez la version de Bun :

bun --version  # v1.0+ requis

Problèmes sur macOS/Linux :

# S'assurer que le répertoire existe
mkdir -p ~/.claude/skills/

# S'assurer des droits d'exécution
chmod +x ~/.claude/skills/gstack/setup

2. Échec du lancement de /browse

# Reconstruire le binaire manuellement
cd ~/.claude/skills/gstack/browse
bun install
./setup

Si Bun est obsolète :

# Mettre à jour Bun
curl -fsSL https://bun.sh/install | bash

3. Erreur Codex "Skilled loading invalid"

Le cache des descriptions de compétences est expiré. Correction :

# Pour une installation globale Codex
cd ~/.codex/skills/gstack && git pull && ./setup --host codex

# Pour une installation Vendored Codex
cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex

4. Compatibilité Windows

Sur Windows, gstack dépend de WSL ou Git Bash (pas PowerShell). Vérifiez :

# Dans Git Bash ou WSL
which bun   # Doit retourner un chemin
which node  # Doit retourner un chemin

Sur Windows, Playwright a un bug connu (bun#4253), gstack bascule automatiquement sur Node.js.

5. Échec de l'import de Cookies

L'import de cookies n'est supporté que sur macOS (via Keychain). Linux et Windows ne sont pas supportés pour le moment.

Si vous testez sur Linux une page nécessitant une session, exportez les cookies manuellement en JSON :

[
  {"name": "session_token", "value": "...", "domain": ".example.com", "path": "/"}
]

Puis utilisez :

$B cookie-import /chemin/vers/cookies.json

6. Mise à jour de version

# Option 1 : Utiliser la compétence de mise à jour
/gstack-upgrade

# Option 2 : Tirer manuellement le code
cd ~/.claude/skills/gstack && git pull && ./setup

gstack-upgrade détectera s'il s'agit d'une installation globale ou vendored et agira en conséquence.

---

Lectures complémentaires / Directions avancées

ETHOS.md — Le document de philosophie centrale. Principe "Boil the Lake" : l'IA réduit le coût marginal d'une implémentation parfaite à presque zéro, ne vous contentez pas du "juste assez". Également "Search Before Building" : un système de connaissance à trois niveaux.

Autoplan — Une commande unique pour enchaîner les revues CEO → Design → Ingénierie. Si vous ne voulez pas appeler chaque compétence une par une, /autoplan gère l'ordre et vous sollicite pour les décisions clés.

Conductor — L'outil de gestion multi-sessions officiel de gstack. Organisez plusieurs instances de Claude Code comme une véritable équipe d'ingénierie IA.

Parcours de lecture du code source :

1. browse/src/commands.ts — Registre de toutes les commandes de navigation
2. browse/src/snapshot.ts — Cœur du système de référence (Arbre ARIA → Playwright Locator)
3. scripts/gen-skill-docs.ts — Pipeline de génération auto de SKILL.md
4. ARCHITECTURE.md — Document d'architecture complet

---