GSD en pratique : les tips et les pièges que le README ne mentionne pas

Guide pratique de GSD pour Claude Code : installation, workflow, configuration et les pièges à éviter.
ai
claude
claude-code
devops
workflow
Author

Sylvain Pham

Published

February 28, 2026

L’article précédent couvre le fonctionnement de GSD : le cycle de vie, l’architecture des agents, les commandes. Celui-ci est le guide pratique : ce qu’il faut savoir avant de lancer son premier projet, les erreurs qui font perdre du temps et les réglages qui changent la donne.

1 Avant de commencer

1.1 Tester avec /gsd:quick d’abord

Le réflexe naturel c’est de lancer /gsd:new-project directement. Le problème : l’initialisation pose une dizaine de questions (vision, stack, contraintes, conventions), lance des recherches, génère une roadmap. Sur un premier usage, on ne sait pas ce qui est important dans ces questions ni comment le workflow va se dérouler ensuite.

Commencer par /gsd:quick sur une tâche isolée : un bugfix, un petit refactor. Ça donne une idée du mécanisme (recherche, plan, exécution, vérification) sans s’engager dans le cycle complet. Le passage au projet structuré sera plus naturel après.

1.2 La question des permissions

--dangerously-skip-permissions est quasi obligatoire pour que les subagents fonctionnent sans friction. Sans ça, chaque agent demande confirmation pour lire un fichier, écrire du code, committer. Sur un projet de 30 tâches, ça devient impraticable.

Sur un projet perso ou un prototype, c’est acceptable. En contexte client, c’est un vrai sujet. Pas de solution idéale pour l’instant.

1.3 Bien répondre aux questions d’initialisation

/gsd:new-project génère un PROJECT.md à partir de vos réponses. Ce fichier est chargé dans le contexte de chaque agent par la suite. C’est la source de vérité sur le “quoi” et le “pourquoi” du projet.

Ce qui compte :

  • Les conventions de code : nommage, structure de dossiers, patterns utilisés. Si c’est flou ici, les executors inventent
  • Les contraintes techniques : versions imposées, dépendances à respecter, ce qu’on n’a pas le droit de toucher
  • La vision : une phrase claire sur l’objectif. “Dashboard de monitoring temps réel” > “améliorer l’observabilité”

Ce qui compte moins : les détails d’implémentation. Les agents de recherche les trouveront.

2 Les pièges de la planification

2.1 Toujours discuss-phase avant plan-phase

C’est la source numéro un de problèmes. Sans /gsd:discuss-phase, Claude fait des hypothèses sur les choix d’implémentation. Le plan a l’air correct à la lecture, mais les executors partent dans la mauvaise direction.

/gsd:discuss-phase produit un CONTEXT.md qui verrouille les préférences : quelle lib utiliser, quel pattern suivre, ce qu’il ne faut pas toucher. Le planner s’y réfère ensuite. 5 minutes de discussion économisent une re-planification complète.

2.2 Vérifier les hypothèses avec /gsd:list-phase-assumptions

Avant de planifier, cette commande affiche ce que Claude compte faire. C’est le meilleur moyen de détecter une incompréhension avant qu’elle devienne du code. Si les hypothèses sont fausses, on corrige dans discuss-phase avant de lancer la planification.

2.3 Le plan checker qui rejette en boucle

Le plan checker vérifie 8 dimensions et peut rejeter jusqu’à 3 fois. Quand il boucle, c’est en général l’un de ces deux problèmes :

  1. Le scope est trop large. La phase couvre trop de choses, le planner n’arrive pas à produire des plans atomiques. Solution : découper la phase en deux.

  2. Le Nyquist layer exige des tests qui n’existent pas encore. Si l’infra de tests n’est pas en place, chaque plan est rejeté parce qu’il n’a pas de commande verify. Solution : désactiver temporairement workflow.nyquist_validation: false dans /gsd:settings, ou créer une phase 0 dédiée au scaffolding de tests.

2.4 2-3 tâches par plan, pas plus

Si l’exécution produit des stubs ou du code incomplet, le plan est trop ambitieux. Un executor a 200k tokens de contexte, mais ça ne suffit pas pour implémenter 8 tâches en séquence avec la même rigueur. GSD recommande 2-3 tâches par plan. C’est contre-intuitif (on veut aller vite), mais le code final est meilleur.

3 Pendant l’exécution

3.1 /clear entre les phases

Le /clear entre les phases est facile à oublier. Il est pourtant important. Les sous-agents ont déjà leur propre contexte frais, mais la session principale (l’orchestrateur) accumule du contexte au fil des commandes. Si l’orchestrateur est saturé, les instructions qu’il passe aux sous-agents se dégradent. /clear puis /gsd:progress pour repartir propre.

3.2 Quand un subagent “échoue” mais le travail est fait

Bug connu de classification dans Claude Code. GSD vérifie la sortie réelle avant de reporter un échec, mais le message dans le terminal peut être trompeur. Avant de re-lancer une tâche, vérifier git log pour confirmer que le commit n’a pas déjà été fait.

3.3 Reprendre le lendemain

/gsd:pause-work       # En fin de session : sauvegarde le contexte
# ... le lendemain ...
/gsd:resume-work      # Restaure le contexte et reprend

/gsd:progress est l’alternative rapide : il affiche le statut sans restaurer le contexte complet. Utile pour vérifier où on en est avant de décider quoi faire.

4 Configuration : ce qui compte vraiment

4.1 Le profil de modèles

Le profil balanced (par défaut) met Opus sur le planner et Sonnet partout ailleurs. C’est le bon compromis dans la plupart des cas. Le planner est l’agent qui prend les décisions d’architecture ; c’est là que la qualité du modèle compte le plus.

budget passe chercheurs et vérificateurs sur Haiku. Utile quand le domaine est familier et qu’on n’a pas besoin de recherche approfondie. Pas recommandé sur un nouveau stack.

/gsd:set-profile budget    # Switch rapide

4.2 Les toggles qui changent le coût

Chaque agent désactivé fait gagner des tokens. Sur un domaine qu’on maîtrise, couper research et plan_check divise le coût par deux sans impact visible sur la qualité.

Réglage Quand le désactiver
workflow.research Domaine familier, pas besoin d’investigation
workflow.plan_check Tâches simples où le plan est évident
workflow.verifier Prototypage rapide, feedback visuel suffisant
workflow.nyquist_validation Phases exploratoires sans infra de tests

4.3 Stratégie Git

Stratégie Usage
none Dev solo, projets simples
phase Review par phase, rollback granulaire
milestone Une PR par version

phase est le bon défaut dès qu’on travaille en équipe ou qu’on veut pouvoir revenir en arrière proprement.

5 Brownfield : intégrer un projet existant

Sur une codebase existante, ne pas lancer /gsd:new-project directement. Les questions seront génériques et les agents de recherche vont re-découvrir ce qu’on sait déjà.

/gsd:map-codebase           # 4 agents analysent en parallèle
/gsd:new-project            # Les questions ciblent ce qu'on ajoute

Le mapping produit 4 fichiers dans .planning/codebase/ : STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md. Les agents de planification et d’exécution y ont accès, ce qui évite de réinventer les conventions en place.

6 Quand utiliser GSD, quand s’en passer

GSD apporte un vrai gain :

  • Projet de plus de 20 tâches avec Claude Code
  • Feature multi-phases avec des dépendances entre composants
  • Projet en équipe où la traçabilité (commits atomiques, plans, vérifications) compte
  • Codebase existante à enrichir (workflow brownfield)

GSD est surdimensionné :

  • Un bugfix rapide (utiliser /gsd:quick ou Claude Code directement)
  • Un petit script ou un outil interne en une session
  • Un projet où on veut garder le contrôle ligne par ligne

Le premier cycle demande un temps d’adaptation. Le réflexe de coder directement est fort, et la discipline discuss, plan, execute, verify ne vient pas naturellement. Mais sur les projets structurés, la différence de qualité sur les tâches 30+ est nette.

7 Troubleshooting rapide

Problème Cause probable Solution
“Project already initialized” .planning/PROJECT.md existe Supprimer .planning/
Qualité qui se dégrade Contexte orchestrateur saturé /clear puis /gsd:resume-work
Plans mal alignés Pas de discuss-phase Lancer /gsd:discuss-phase puis re-planifier
Stubs en sortie Plan trop ambitieux 2-3 tâches max par plan
Plan checker en boucle Scope trop large ou Nyquist bloquant Découper la phase ou désactiver nyquist_validation
Coûts trop élevés Trop d’agents actifs /gsd:set-profile budget + couper research/verifier
Subagent “échoue” Bug de classification Claude Code Vérifier git log

8 Liens

Testé en février 2026. GSD évolue vite (v1.17+ au moment de l’écriture) ; vérifier les versions actuelles avant installation.