1089 lines
59 KiB
Markdown
1089 lines
59 KiB
Markdown
# claude-config — Guide d'utilisation et cas d'usage
|
|
|
|
Ce fichier complète le README. Il documente les bonnes pratiques, les workflows typiques, et des exemples concrets pour plusieurs types de projets.
|
|
|
|
---
|
|
|
|
## Principes fondamentaux
|
|
|
|
**Tu décris, le pipeline exécute.** Le système prend en charge : l'architecture, le scaffolding, la décomposition en tâches, l'implémentation TDD, le code review, et la synchronisation du README. Tu n'interviens qu'aux deux gates de validation.
|
|
|
|
**Prompt détaillé = moins de friction.** L'interviewer (STEP 1) skip les questions si ton prompt contient déjà : nom, purpose, stack, features v1, conventions. Un prompt de 10 lignes structuré évite toute interruption.
|
|
|
|
**Plugin-check avant tout.** Soit via `/plugin-check "description"` (explicite), soit via STEP 0 de `/init-project` ou `/ship-feature` (automatique). Les plugins mal configurés dégradent silencieusement la qualité du résultat.
|
|
|
|
---
|
|
|
|
## Quel skill utiliser ?
|
|
|
|
Arbre de décision rapide face à une situation donnée :
|
|
|
|
```
|
|
Tu veux...
|
|
│
|
|
├─ Créer un nouveau projet from scratch ?
|
|
│ → /init-project "description"
|
|
│
|
|
├─ Intégrer un projet existant dans claude-config ?
|
|
│ → /onboard
|
|
│
|
|
├─ Ajouter une feature à un projet existant ?
|
|
│ ├─ Feature complète (multi-fichiers, orchestration) ?
|
|
│ │ → /ship-feature "description"
|
|
│ └─ Petite feature (1-5 fichiers, rapide) ?
|
|
│ → /feat "description"
|
|
│
|
|
├─ Corriger un bug ?
|
|
│ ├─ Bug superficiel (typo, CSS, config, max 2 fichiers) ?
|
|
│ │ → /hotfix "description"
|
|
│ └─ Bug complexe (investigation root cause nécessaire) ?
|
|
│ → /bugfix "description"
|
|
│
|
|
├─ Reprendre après une pause / orienter la session ?
|
|
│ → /status
|
|
│
|
|
├─ Comprendre du code avant de le modifier ?
|
|
│ → /analyze src/fichier.py
|
|
│ → (mode DEBUG si tu passes une erreur/stack trace)
|
|
│
|
|
├─ Améliorer la qualité sans changer le comportement ?
|
|
│ ├─ Refactoring ciblé (un fichier/module) ?
|
|
│ │ → /refactor src/module.py
|
|
│ │ ⚠️ Pour un refactoring profond (module entier) :
|
|
│ │ /analyze src/module/ ← rapport de violations d'abord
|
|
│ │ /refactor src/module/ ← corrections sur rapport
|
|
│ │ /analyze src/module/ ← vérification après (cycle complet)
|
|
│ └─ Dead code, violations de style (codebase-wide) ?
|
|
│ → /code-clean
|
|
│
|
|
├─ Docs périmées / vérifier la sync code↔docs ?
|
|
│ → /doc ← audit complet tous les fichiers .md
|
|
│
|
|
├─ Optimiser le SEO/GEO ?
|
|
│ ├─ Audit complet SEO + GEO ?
|
|
│ │ → /seo
|
|
│ └─ GEO uniquement (visibilité IA) ?
|
|
│ → /geo
|
|
│
|
|
├─ Vérifier si les plugins sont bien configurés ?
|
|
│ → /plugin-check "description du projet"
|
|
│ → (aussi fait automatiquement en STEP 0 de /init-project et /ship-feature)
|
|
│
|
|
├─ Session GSD v2 active/interrompue ?
|
|
│ → dans le terminal: gsd → /gsd auto (reprend depuis .gsd/)
|
|
│ → modifier le plan en cours: /gsd steer ou /gsd discuss
|
|
│ → voir la progression: /gsd status
|
|
│ → un step a échoué: /gsd forensics (debug autonome)
|
|
│
|
|
├─ Auditer les changements depuis le dernier audit ?
|
|
│ → /audit-delta ← conformité / bugs / dead code / sécurité (scope = delta)
|
|
│
|
|
├─ Gérer la mémoire de session ?
|
|
│ → /capitalize ← flush contexte + réconcilie TODO avant /clear ou /compact
|
|
│ → /prune-memory ← curer / compresser les registres .claude/memory/
|
|
│
|
|
└─ Quelque chose ne marche pas ?
|
|
→ make doctor ← diagnostic d'installation (symlinks, plugins, permissions, hooks, token budget)
|
|
```
|
|
|
|
### Règle de décision simplifiée
|
|
|
|
| Situation | Skill recommandé |
|
|
|---|---|
|
|
| Tout nouveau | `/init-project` |
|
|
| Code existant sans config | `/onboard` |
|
|
| Feature complète | `/ship-feature` |
|
|
| Petite feature (1-5 fichiers) | `/feat` |
|
|
| Bug superficiel (typo, CSS) | `/hotfix` |
|
|
| Bug complexe (root cause) | `/bugfix` |
|
|
| Reprise de session | `/status` |
|
|
| Debug / comprendre | `/analyze` |
|
|
| Nettoyage code ciblé | `/refactor` |
|
|
| Dead code / style codebase | `/code-clean` |
|
|
| Docs périmées | `/doc` |
|
|
| SEO/GEO audit | `/seo` (GEO seul → `/geo`) |
|
|
| Commit structuré | `/commit-change` |
|
|
| Branches gitflow (start/finish) | `/gitflow` |
|
|
| Couper une release (develop→main) | `/release-candidate` |
|
|
| Déployer via runbook | `/deploy` |
|
|
| Navigation codebase large | `/graphify` |
|
|
| Lister ses skills | `/skills-perso` |
|
|
| Plugins OK ? | `/plugin-check` |
|
|
| Audit du delta (depuis dernier run) | `/audit-delta` |
|
|
| Flush mémoire + TODO avant /clear | `/capitalize` |
|
|
| Curer la mémoire | `/prune-memory` |
|
|
| État réel du travail ouvert | `/reconcile` |
|
|
| Fin de session (= /capitalize --ritual) | `/close` |
|
|
| Audit web (TLS, CSP, headers) | `/harden` |
|
|
| Validité HTML/CSS + conformité WCAG | `/web-validate` |
|
|
| Accessibilité de base (clavier, alt, labels) puis corriger | `/a11y` |
|
|
| Visibilité IA (GEO seul) | `/geo` |
|
|
| Livraison client finale | `/client-handover` |
|
|
| Traduire un PDF | `/pdf-translate` |
|
|
| Comprendre un changement pas suivi | `/explain-diff` |
|
|
| Auditer garde-fous (RLS, consentement, fonctions, mots de passe, injection SQL, fuites navigateur) puis corriger | `/guardrails` |
|
|
| Sonder le projet en direct (lecture seule, cible à toi) | `/guardrails --live <url>` |
|
|
| Changer le profil de packs du projet (`set`), ou l'état effectif (`current`) | `/profile` |
|
|
| Audit/polish design (anti-slop) | `/impeccable` |
|
|
| Sweep groupé tous axes (nettoyage + sécu + reconcile + doc) | `/tour` |
|
|
| Rien ne marche | `make doctor` (terminal) |
|
|
|
|
---
|
|
|
|
## Les commandes et quand les utiliser
|
|
|
|
| Commande | Quand | Notes |
|
|
|---|---|---|
|
|
| `/init-project` | Nouveau projet from scratch | 11-12 steps, deux gates obligatoires |
|
|
| `/ship-feature` | Feature sur projet existant | Pipeline 9 steps, une gate |
|
|
| `/feat` | Petite feature (1-5 fichiers) | Léger, pas d'orchestration lourde |
|
|
| `/bugfix` | Bug avec investigation root cause | Hypothèses, diagnostic, fix minimal |
|
|
| `/hotfix` | Bug superficiel (typo, CSS, config) | Max 2 fichiers, cause évidente |
|
|
| `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings ; `/onboard split` découpe un CLAUDE.md existant en règles `.claude/rules/` |
|
|
| `/plugin-check` | Avant de démarrer tout travail | Aussi embarqué en STEP 0 des orchestrateurs |
|
|
| `/analyze` | Comprendre du code avant de le modifier | Read-only, aucune solution proposée |
|
|
| `/analyze` + erreur | Diagnostiquer un test/build qui échoue | Mode DEBUG : hypothèses ordonnées |
|
|
| `/refactor` | Améliorer un fichier sans changer le comportement | Rapport de violations d'abord, modif ensuite |
|
|
| `/code-clean` | Dead code, violations de style | Audit + rapport, fixes après approbation |
|
|
| `/doc` | Docs périmées après des changements | Audit drift code↔docs, patch chirurgical |
|
|
| `/seo` | Audit SEO/GEO complet | Détecte framework, audite meta/OG/sitemap ; en FULL, choix du compte Google puis données réelles Search Console + CrUX (terrain) si connecté via `make seo-connect`, sinon repli PageSpeed anonyme. Gestion des comptes sans audit : `/seo connect [label]`, `/seo accounts`, `/seo forget <label>\|--all` |
|
|
| `/geo` | Audit GEO uniquement (IA) | Visibilité ChatGPT, Perplexity, Claude, Gemini… |
|
|
| `/commit-change` | Commits bien structurés | Groupe les changements par unité logique |
|
|
| `/gitflow` | Opérations de branches gitflow | Bootstrap main+develop, branche typée, merge dirigé |
|
|
| `/release-candidate` | Couper une release versionnée (develop en avance sur main) | Finalise version.txt + CHANGELOG, merge develop→main, tag, push (mode auto-push, tag sur ton feu vert ; mode push manuel : une commande `! git push --atomic` que tu lances) |
|
|
| `/deploy` | Déployer via le runbook du projet | Instancie le delta depuis le dernier deploy, reprend à froid ; tu exécutes la checklist, Claude ne déploie jamais |
|
|
| `/graphify` | Navigation codebase large-scope | Knowledge graph, pour tâches multi-fichiers |
|
|
| `/skills-perso` | Lister ses skills personnels | Skills créés dans ~/.claude/skills/ |
|
|
| `/health` | Tableau de bord qualité du code (gstack) | Le diagnostic d'installation est `make doctor` |
|
|
| `/status` | Reprendre après une pause | Snapshot : plugins, git, GSD milestone |
|
|
| `/audit-delta` | Audit récurrent du delta depuis le dernier run | Axes : conformité / bugs / dead code / sécurité |
|
|
| `/capitalize` | Avant /clear ou /compact | Flush contexte non capitalisé + réconcilie .claude/tasks/TODO.md |
|
|
| `/prune-memory` | Registres trop longs / bruyants | Curation : merge, superseded, compression |
|
|
| `/reconcile` | Connaître l'état réel du travail ouvert (TODO/registres douteux) | Confronte statut déclaré vs git/fs réel |
|
|
| `/close` | Fin de session | Alias de /capitalize --ritual — dedup + TODO + réflexion 3 questions |
|
|
| `/harden` | Audit sécurité web (SSL, CSP, HSTS) | Projet web avec config HTTP |
|
|
| `/web-validate` | Audit W3C + conformité WCAG | Avant livraison projet web ; bases clavier/alt/labels → /a11y |
|
|
| `/a11y` | Vérifier clavier, focus visible, alt, labels puis corriger | Scanner déterministe, parcours Tab sur `--live`, rapport `.claude/audits/A11Y.md`, propositions à valider (textes d'alt et de label = ton choix), re-passe qui prouve chaque correction |
|
|
| `/client-handover` | Livraison client | Audits finaux + livrable brandé |
|
|
| `/pdf-translate` | Traduire un PDF vers une autre langue | Sortie HTML fidèle (images, layout, style préservés) |
|
|
| `/explain-diff` | Comprendre un commit, une branche ou une PR qu'on n'a pas suivis | Page HTML autonome hors du repo : contexte, intuition, code, quiz de 5 questions |
|
|
| `/guardrails` | Vérifier hébergement, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe, injection SQL, exposition navigateur | Scanner déterministe, jugement, rapport `.claude/audits/GUARDRAILS.md`, propositions de correction à valider, re-passe qui prouve chaque correction ; `--live <url à toi>` sonde en lecture seule ; sonde `exposure` sur un build de production (source maps, corps d'erreur, clés sensibles) |
|
|
| `/impeccable` | Audit/polish design + détecteur anti-slop déterministe | 23 verbes ; `npx impeccable detect` (exit 0/2) |
|
|
| `/tour` | Sweep groupé sur un ou plusieurs projets | Sécu + nettoyage + reconcile + doc, boucle jusqu'à un pass propre |
|
|
| `/route` | Voir ou fixer la route du mod model-router | show / clear / off / on / reload / pending / ask on\|off / ask-tier on\|off / <phase> / model=… effort=… / switch on\|off / classify on\|off (classifieur de prompt) / verbose on\|off (transitions seules) ; `clear`, `off` et `/clear` réarment le garde d'écriture (voir ci-dessous) |
|
|
| `/profile` | Changer le profil de packs du projet (`set`), ou l'état effectif (`current`) | Profils dans `lib/profiles/*.json`, packs dans `skills/pack-*/` |
|
|
|
|
> Cette table couvre les skills personnels principaux. `/seo` et `/geo` (pack-seo)
|
|
> et `/web-validate` (pack-web-validate) vivent dans des packs : un profil qui laisse
|
|
> le pack éteint les masque (`/profile current`). Les plugins (gstack,
|
|
> pr-review-toolkit…) et marketplaces externes en ajoutent beaucoup d'autres ;
|
|
> `/skills-perso` liste tes skills personnels.
|
|
|
|
---
|
|
|
|
### Niveau d'effort
|
|
|
|
Chaque commande a une ligne de phase dans `mods/model-router/routing.json`,
|
|
le fichier suivi du mod model-router (actif dans chaque session), qui fixe son niveau de
|
|
réflexion : low pour la tenue de registre (`/status`, `/close`,
|
|
`/commit-change`), medium pour le courant (`/gitflow`, `/prune-memory`),
|
|
high pour un fix ou un refactor (`/feat`, `/hotfix`, `/bugfix`,
|
|
`/refactor`, audits avec fix), xhigh pour l'architecture et l'audit avant
|
|
validation (`/ship-feature`, `/onboard`, `/analyze`). Le frontmatter
|
|
(`model:`, `effort:`) garde les mêmes valeurs et sert de plancher quand le
|
|
mod est coupé. Les orchestrateurs déclarent ensuite chaque phase via
|
|
l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills
|
|
externes vendorés (pile design, superpowers, agent-skills, skills scroll
|
|
MengTo, 21st) ont aussi leur ligne.
|
|
|
|
Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model <nom>` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par une ligne de skill, l'outil `route`, un `/route` tapé ou un choix à la main (`/model`, sélecteur). Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Opus pour Fable), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run <phase>`), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget <nom|all|projects>` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`.
|
|
|
|
Garde d'écriture : un Edit, Write ou NotebookEdit d'un fichier de code par la boucle principale est redirigé avec « model-router: code is written inside a skill run… » tant qu'aucun skill n'a tourné sur la boucle principale dans la session (tapé ou chargé par le modèle), qu'aucune phase n'a été déclarée ce tour, et qu'aucun `/route` tapé ne tient. Chemins libres : `.md`, `.txt`, le `.claude/` du projet sauf `worktrees/`, et `docs/`. Les sous-agents écrivent librement. `/route clear`, `/route off` et `/clear` réarment le garde ; `/route off` le coupe aussi, et `"enabled": false` dans `~/.claude/model-router.json` coupe le routeur et le garde. Un choix à la main avec `/model` ne l'ouvre pas, et un rechargement de `register.ts` le remet à zéro.
|
|
|
|
La config par machine, optionnelle, vit dans `~/.claude/model-router.json` et passe devant `routing.json` ; `"enabled": false` y coupe le mod sur cette machine, `"ask": false` y coupe le dialogue, une ligne à `null` y retire une ligne. Un `.claude/model-router.json` dans un projet n'est jamais lu. Les phases et les lignes se modifient à la main dans `routing.json` ; `/route reload` relit les deux fichiers.
|
|
|
|
### Capture mémoire (mod memory)
|
|
|
|
Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que `/capitalize` parte des faits. Il n'écrit jamais un registre : un brouillon du modèle, ton accord et `lib/memory.sh` restent la seule voie.
|
|
|
|
- Ce qu'il enregistre : un résultat Bash dont le texte commence par `Exit code N` et dont la dernière ligne (première ligne et trailer rtk écartés) est une ligne d'erreur. La dernière ligne doit contenir une lettre et un mot d'erreur (error, fatal, cannot, No such, denied, failed, unexpected, traceback, ou un code shellcheck SC1234), sinon l'échec est abandonné. Elle est stockée expurgée : `NOM=valeur` (TOKEN, API_KEY, SECRET, PASSWORD, PASSWD, chiffres admis), clés Stripe/AWS/GitHub/Slack/SendGrid/Supabase, bloc de clé privée, JWT, `Bearer`, `user:pass@` dans une URL, `-u`/`--user user:pass`, `--password`, `Authorization: Basic|Bearer|token`, préfixes Anthropic/OpenAI/GitLab/Google/npm et `github_pat_`, drapeaux `--token`/`--api-key`/`--secret`, en-têtes de clé d'API (`X-Api-Key`, `api-key`, `apikey`, tout nom finissant par `api-key` ou `api_key`), en-têtes `PRIVATE-TOKEN`, `Cookie` et `Set-Cookie` (jusqu'à la fin de la ligne), valeurs de `--cookie` et cookies passés à `curl -b`, paires JSON ou `clé: valeur` password/token/secret/api-key dont la clé peut porter un préfixe ou un suffixe (`access_token`, `db_password`), jeton de 40 hexadécimaux comme utilisateur d'URL. Résiduel : `user:p@ss@host` devient `<redacted>@ss@host`, donc la fin du mot de passe après son propre `@` reste. Refus de permission, redirections de garde et erreurs de tool_use ne sont jamais captés. Un échec de sous-agent est marqué `(sub-agent)`.
|
|
- Jalons : un commit `feat` ou `fix` réussi (`-m` simple ou heredoc), un `gitflow.sh finish` (pas `finish chore`), une commande `make test ...` rouge puis verte. Les jalons ne sont notés que sur la boucle principale : commits et finish de sous-agents ignorés.
|
|
- Stockage : le `$.store` du plugin, par racine de projet : 3 sessions les plus récentes par projet, 50 échecs par session, 2 Kio par entrée, 1 Mio pour tout le store. Il survit à `/clear`. Le store est le fichier JSON du plugin sous le dossier de configuration de Claude (observé ici en `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, disposition du moteur, non fixée par ce dépôt) ; le supprimer efface les captures.
|
|
- La note : une ligne de contexte, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, au premier prompt tapé après un jalon. Jamais à chaque tour, jamais au Stop, jamais dans un sous-agent.
|
|
- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre et n'appelle pas `lib/memory.sh`.
|
|
- Interrupteur : `{"enabled": false}` dans `~/.claude/memory.json`, lu au premier événement d'une session : effet à la session suivante ou après `/reload-plugins`. Coupé, l'outil répond `memory capture is off (~/.claude/memory.json)`. Un fichier illisible, ou dont `enabled` n'est pas un booléen, laisse la capture active et journalise une ligne.
|
|
- Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. `-b` ne vaut drapeau de cookies de curl que si `curl` ouvre son segment de commande, après d'éventuelles affectations de variables, `sudo`, `rtk` ou `$(` : `time curl -b …` garde ses cookies. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Un jeton de 40 hexadécimaux nu est gardé à dessein : il ressemble à un SHA de commit (expurgé seulement comme utilisateur d'URL). Une racine de session qui bouge avec `/cd` ou un changement de worktree cache à /capitalize les captures précédentes du même dépôt. Un `gitflow.sh finish` nu sur une branche chore compte comme un jalon. Bruit mesuré à 83 % avant le filtre de forme d'erreur sur 14 jours de transcripts de ce dépôt ; le filtre garde tous les échantillons utiles et réduit les captures des deux tiers (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
|
|
|
|
## Les plugins — décision rapide
|
|
|
|
```
|
|
Toujours actifs (0 token) : security-guidance, rtk
|
|
|
|
Design élaboré/system → ui-ux-pro-max ON
|
|
Deploy + QA browser → gstack ON
|
|
Next.js/React/Prisma → context7 ON (WARN si absent, pas BLOCK)
|
|
Multi-session (>1 jour) → gsd v2 CLI (gsd dans terminal)
|
|
|
|
Backend/CLI seulement → tout OFF (skills superpowers vendorisés, toujours actifs, 0 t passif)
|
|
Hotfix/quick fix → tout OFF (skills superpowers vendorisés, toujours actifs, 0 t passif)
|
|
```
|
|
|
|
**GSD v2** n'est pas un plugin Claude Code — c'est un CLI externe. Il ne consomme pas de tokens passifs. Tu le lances dans un terminal séparé avec `gsd`, puis `/gsd auto` pour le mode autonome.
|
|
|
|
**Profils et packs.** Un profil se règle par projet (`/profile set web` puis `/reload-plugins`) ou par conversation (`cc <nom> web`, la conversation est figée: relance-la pour changer). Neuf profils: `full`, `max`, `minimal`, `dev`, `design`, `web`, `seo`, `qa`, `audit`. Sans profil, c'est `full`. Un `--settings` édité en cours de session reste sans effet. `cc x web` sur un projet en `dev` garde les connecteurs higgsfield refusés (union); `set web` dans le projet les rend. `cc` est une fonction de `lib/cc.sh`, à sourcer depuis `~/.bashrc` (`[ -f "$HOME/.claude/lib/cc.sh" ] && . "$HOME/.claude/lib/cc.sh"`) ; `make doctor` le signale tant qu'elle manque.
|
|
|
|
---
|
|
|
|
## Patterns de workflow
|
|
|
|
> **Budget Pro (~11k tokens/5h) :** un `/init-project` complet consomme 3000-5000t — laissant 6000-8000t pour les steps suivants. Adapter le choix de plugins actifs en conséquence. Les tokens sont indiqués à titre indicatif — varient selon la taille du projet et les plugins actifs.
|
|
|
|
### Pattern A — Nouveau projet court (≤1 session) · ~3000-5000t
|
|
|
|
```
|
|
# 1. Configurer les plugins
|
|
/plugin-check "description de ton projet"
|
|
# → Activer les plugins recommandés, puis :
|
|
|
|
# 2. Créer le projet
|
|
/init-project "description complète"
|
|
# → STEP 0 : vérifie les plugins automatiquement
|
|
# → STEP 1 : interview (skip si prompt complet)
|
|
# → STEP 4 : ★ GATE — valider l'architecture
|
|
# → STEP 7 : ★ GATE — valider le plan d'implémentation
|
|
# → STEP 8-10 : implémentation TDD + gates verify/sécurité + review
|
|
# → STEP 10b-c: capitalize mémoire + sync docs publiques (avant finish)
|
|
# → STEP 11 : finish, `gitflow finish` vers develop sur ton feu vert explicite
|
|
|
|
# 3. Features suivantes
|
|
/ship-feature "description de la feature"
|
|
```
|
|
|
|
### Pattern B — Projet long (multi-session, plusieurs jours) · ~1500-2500t/session CC
|
|
|
|
```
|
|
# Même départ que Pattern A. GSD v2 n'est PAS bootstrappé à la création
|
|
# (init-project ne propose plus gsd) — on l'initialise À LA DEMANDE, dans un
|
|
# terminal, quand on décide de passer en multi-session.
|
|
|
|
# À chaque reprise de session (dans Claude Code) :
|
|
/status # snapshot : plugins + git + milestone GSD en cours
|
|
|
|
# Dans un terminal (depuis le dossier projet) :
|
|
gsd # démarrer une session
|
|
/gsd init # initialise .gsd/ + milestones (une fois, à la demande)
|
|
/gsd auto # mode autonome, walk away
|
|
|
|
# Pour suivre :
|
|
/gsd status # dashboard progression + coût
|
|
|
|
# Pour orienter en cours de route :
|
|
/gsd discuss # décisions d'architecture
|
|
/gsd steer # modifier le plan en cours d'exécution
|
|
|
|
# Crash/interruption → reprendre :
|
|
gsd # relancer
|
|
/gsd auto # reprend depuis l'état sauvegardé dans .gsd/
|
|
```
|
|
|
|
### Pattern C — Projet existant (onboarding + audit complet) · ~3000-8000t (onboard full pipeline)
|
|
|
|
`/onboard` est un **orchestrateur** qui fait bien plus que générer une config :
|
|
|
|
```
|
|
cd mon-projet-existant/
|
|
|
|
# Dans Claude Code :
|
|
/onboard
|
|
```
|
|
|
|
**Pipeline exécuté par /onboard** (STEP 0 → STEP 9) :
|
|
|
|
| STEP | Action | Livrable |
|
|
|---|---|---|
|
|
| 0 | plugin-advisor — détection signaux + activation plugins | recommandations plugins |
|
|
| 1 | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto |
|
|
| 1b | Gate monorepo (A/B/C si détecté) | mode choisi |
|
|
| 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ + .claude/rules/ (docker, testing, ci si un glob matche) |
|
|
| 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée |
|
|
| 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ |
|
|
| 3 | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi |
|
|
| 3.5| ctx7 doc audit — fast-libs détectées, cache pré-fetché si besoin | .ctx7-cache/ |
|
|
| 4 | Graphify (proposé dès 200 fichiers code, l'utilisateur décide) | graphify-out/GRAPH_REPORT.md |
|
|
| 4.5| Espace d'audit + contexte archétype | .onboard-audit/archetype-context.md |
|
|
| 5 | Analyze read-only (analyzer agent) | .onboard-audit/analyze.md |
|
|
| 6 | Audits parallèles selon archétype : | .onboard-audit/*.md (9 fichiers max) |
|
|
| | — dette tech (general-purpose, audit read-only) |
|
|
| | — sécurité (cso si gstack ON, sinon OWASP fallback) |
|
|
| | — docs drift (doc-syncer) |
|
|
| | — SEO + GEO (si public) |
|
|
| | — design UI/UX (si frontend) |
|
|
| | — performance (Lighthouse ou static bundle audit) |
|
|
| | — accessibilité (axe ou static a11y audit) |
|
|
| 7 | Synthèse structurée dans .claude/audits/ | ONBOARD_REPORT, AUDIT_GOOD, AUDIT_ISSUES, AUDIT_PROPOSALS |
|
|
| 7b | Challenge adversarial des propositions avant la gate | AUDIT_PROPOSALS.md challengé |
|
|
| 8 | Validation gate utilisateur | choix A/B/C/D/E |
|
|
| 9 | Backlog .claude/tasks/TODO.md séquencé avec /skill recommandé par tâche | .claude/tasks/TODO.md |
|
|
|
|
**Hints optionnels :**
|
|
```
|
|
/onboard "Python FastAPI" # hint stack
|
|
/onboard force-archetype:wordpress # override detection
|
|
/onboard split # CLAUDE.md existant → règles .claude/rules/ (sections liées à un chemin)
|
|
```
|
|
|
|
**Après /onboard :**
|
|
```
|
|
# Ouvrir le rapport exécutif
|
|
cat .claude/audits/ONBOARD_REPORT.md
|
|
|
|
# Démarrer la première tâche P0 avec le skill recommandé
|
|
# (indiqué dans .claude/tasks/TODO.md)
|
|
/hotfix "<titre P0>" # ou /feat, /ship-feature, /bugfix selon le cas
|
|
|
|
# Multi-session (GSD) : gsd init à la main — voir docs gsd-pi
|
|
```
|
|
|
|
**Archétypes supportés** : astro-static, cli-tool, data-notebook, desktop-electron, docker-compose-infra, dotfiles-meta, drupal, firmware-embedded, game-engine-native, ghost, library, mobile-expo, mobile-flutter, nextjs-app-router, react-spa, rest-api-node, rest-api-python, shopify, static-html, strapi, terraform-infra, web-game, woocommerce, wordpress.
|
|
Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voir `_TEMPLATE.md`).
|
|
|
|
### Pattern D — Hotfix / bugfix · ~200-800t
|
|
|
|
```
|
|
# Bug superficiel (typo, CSS, config, max 2 fichiers, cause évidente) :
|
|
/hotfix "le bouton submit est invisible sur mobile" # ~200t
|
|
|
|
# Bug complexe (investigation root cause nécessaire) :
|
|
/bugfix "les notifications ne partent plus depuis mardi" # ~500-800t
|
|
```
|
|
|
|
### Pattern E — Debug d'erreur de build/test · ~600-900t
|
|
|
|
```
|
|
# Copier le message d'erreur complet, puis :
|
|
/analyze "FAILED tests/test_api.py::test_create — AssertionError: 422 != 201"
|
|
# → Mode DEBUG automatique
|
|
# → Hypothèses ordonnées par probabilité
|
|
# → Fichiers à vérifier
|
|
# → Ce qu'il ne faut pas toucher
|
|
|
|
# Puis si fix nécessaire :
|
|
/ship-feature "corriger le test_create_order — cause: champ quantity manquant"
|
|
```
|
|
|
|
### Pattern F — Petite feature (1-5 fichiers) · ~300-600t
|
|
|
|
```
|
|
# Feature simple, pas d'orchestration lourde
|
|
/feat "ajouter un endpoint GET /api/v1/users/:id/stats"
|
|
# → plan + challenge, exécuteur `feater`, gates fraîches verifier + sécurité
|
|
# Pas de brainstorming superpowers, pas de gate de validation
|
|
```
|
|
|
|
**Choisir entre /ship-feature et /feat :**
|
|
|
|
| Critère | `/ship-feature` | `/feat` |
|
|
|---|---|---|
|
|
| Scope | Feature complète, multi-fichiers | 1-5 fichiers max |
|
|
| Orchestration | Pipeline superpowers complet | Planning léger, direct |
|
|
| Gate de validation | Oui | Non |
|
|
| Code review auto | Oui (superpowers) | Gates verifier + security-auditor |
|
|
| Tokens estimés | ~1500-3000t | ~300-600t |
|
|
|
|
---
|
|
|
|
## Exemples complets
|
|
|
|
---
|
|
|
|
### Exemple 1 — Application mobile liste de courses (Expo/React Native)
|
|
|
|
**Contexte :** app mobile, offline-first, SQLite local, notifications push, iOS + Android.
|
|
|
|
**Setup plugins :**
|
|
```
|
|
/plugin-check "App mobile React Native Expo liste de courses, offline-first, SQLite, notifications push"
|
|
|
|
→ SIGNALS: frontend (mobile), fast-libs (Expo SDK)
|
|
→ WARN: context7 si Expo SDK 51+ utilisé (fast-libs)
|
|
→ OFF: gstack (mobile, pas de browser QA), ui-ux-pro-max (optionnel)
|
|
→ BLOCKING: none
|
|
```
|
|
|
|
**Prompt init (prompt complet → pas de questions) :**
|
|
```
|
|
/init-project "Application mobile 'KartApp' — liste de courses offline-first.
|
|
|
|
Stack: React Native 0.74 + Expo SDK 51 + TypeScript. SQLite via expo-sqlite. Notifications push via expo-notifications. Expo Router pour la navigation. Zustand pour le state. iOS + Android.
|
|
|
|
Features v1:
|
|
1. Création/édition/suppression de listes
|
|
2. Ajout d'articles (nom, quantité, unité, catégorie)
|
|
3. Cocher/décocher des articles
|
|
4. Partage de liste par lien (Expo Sharing)
|
|
5. Historique des 10 dernières courses
|
|
|
|
Out of scope: sync backend, collaboration, paiement.
|
|
|
|
Tests: Jest + @testing-library/react-native. Coverage >70%.
|
|
Convention: composants PascalCase, hooks use*, stores en Zustand slices."
|
|
```
|
|
|
|
**Ce que le scaffolder génère (STEP 5) :**
|
|
```
|
|
app/
|
|
(tabs)/
|
|
index.tsx — liste des listes (vide)
|
|
history.tsx — historique (vide)
|
|
list/[id].tsx — détail liste (vide)
|
|
_layout.tsx — root layout Expo Router
|
|
components/
|
|
ListCard.tsx — vide
|
|
ItemRow.tsx — vide
|
|
CategoryBadge.tsx — vide
|
|
stores/
|
|
listsStore.ts — Zustand slice (vide)
|
|
itemsStore.ts — Zustand slice (vide)
|
|
db/
|
|
schema.ts — types SQLite (vide)
|
|
migrations/
|
|
001_initial.ts — vide
|
|
hooks/
|
|
useLists.ts — vide
|
|
useItems.ts — vide
|
|
constants/
|
|
Colors.ts — tokens couleurs
|
|
app.json — Expo config
|
|
package.json — scripts: start/android/ios/test/lint
|
|
tsconfig.json
|
|
.env.example
|
|
|
|
Install : npx expo install ✅
|
|
Verify : npx expo export --platform web --output-dir /tmp/expo-check --clear ✅
|
|
```
|
|
|
|
**Si le projet devient long (plusieurs features sur semaines) :**
|
|
```
|
|
# Pour passer en multi-session, initialise GSD à la demande dans un terminal :
|
|
gsd
|
|
/gsd init
|
|
/gsd auto
|
|
# → GSD gère deck-building, sharing backend, etc. milestone par milestone
|
|
```
|
|
|
|
---
|
|
|
|
### Exemple 2 — Site vitrine graphisme élégant (Next.js)
|
|
|
|
**Contexte :** studio photographique, design premium, galerie masonry, dark mode, SEO, Vercel.
|
|
|
|
**Setup plugins :**
|
|
```
|
|
/plugin-check "Site vitrine Next.js 14 studio photo, design élaboré, animations Framer Motion, galerie, dark mode, SEO"
|
|
|
|
→ SIGNALS: frontend, design-system, fast-libs(Next.js)
|
|
→ ENABLE: ui-ux-pro-max (~400t) — "design élaboré" signal fort
|
|
→ WARN: context7 non configuré → taper "force" pour continuer (ou configurer avant)
|
|
→ OFF: gstack (vitrine statique, pas de deploy complexe)
|
|
→ COST: ~1600t passif (comfortable)
|
|
```
|
|
|
|
**Prompt init :**
|
|
```
|
|
/init-project "Site vitrine 'Lumière Studio' pour photographe professionnel.
|
|
|
|
Stack: Next.js 14 App Router + TypeScript + Tailwind CSS + Framer Motion. Hébergement: Vercel. Pas de base de données.
|
|
|
|
Features v1:
|
|
1. Page d'accueil — hero animé, teaser galerie
|
|
2. Galerie masonry (>50 photos, lightbox, lazy loading)
|
|
3. Page À propos (biographie, parcours)
|
|
4. Page Contact (formulaire → Resend pour email)
|
|
5. Dark mode (system preference + toggle)
|
|
6. SEO (OpenGraph, sitemap, metadata par page)
|
|
|
|
Out of scope: blog, e-commerce, espace client, CMS.
|
|
|
|
Tests: Playwright (home, contact form, dark mode toggle). Jest/RTL pour composants.
|
|
Convention: composants dans components/, pages dans app/, assets dans public/images/."
|
|
```
|
|
|
|
**Ce que ui-ux-pro-max apporte en STEP 3 (brainstorm) :**
|
|
Avec ui-ux-pro-max actif, le brainstorming propose un système de design complet :
|
|
```
|
|
Palette : zinc-950 (fond dark) / zinc-50 (texte) / amber-400 (accent)
|
|
Typo : Cormorant Garant (titres serif) + Inter (corps)
|
|
Espacement : multiples de 8px, max-width 1440px
|
|
Animations : entrées scroll (Framer Motion viewport), 200ms ease-out
|
|
Masonry : CSS columns responsive (1→2→3 colonnes), gap 16px
|
|
```
|
|
Sans ui-ux-pro-max : "Tailwind avec palette neutre, Inter". La différence est visible pour un projet où le design est le produit.
|
|
|
|
**Ajouter une feature après init :**
|
|
```
|
|
/ship-feature "Page Tarifs — 3 formules (Reportage, Portrait, Mariage) avec comparateur visuel et CTA de contact par formule"
|
|
```
|
|
|
|
---
|
|
|
|
### Exemple 3 — Jeu de puzzle avec API, auth et cartes collectibles
|
|
|
|
**Contexte :** le projet le plus complexe — React + FastAPI + PostgreSQL + Docker, auth JWT, gameplay, collection.
|
|
|
|
**Setup plugins :**
|
|
```
|
|
/plugin-check "Jeu de puzzle web React + FastAPI + PostgreSQL. Auth JWT, collection de cartes, boutique in-app, leaderboard. Multi-session, dev sur plusieurs semaines."
|
|
|
|
→ SIGNALS: frontend, fast-libs(React), deploy, multi-session
|
|
→ ENABLE: context7
|
|
→ ENABLE: ui-ux-pro-max (cartes visuelles, cohérence design)
|
|
→ CLI: gsd v2 RECOMMANDÉ (multi-session détecté)
|
|
→ OPTIONAL: gstack si deploy CI + browser QA prévus
|
|
→ COST: ~1800t passif (avec context7)
|
|
```
|
|
|
|
**Prompt init :**
|
|
```
|
|
/init-project "Jeu de puzzle web 'CardForge'.
|
|
|
|
Stack: React 18 + TypeScript + Vite (frontend), FastAPI + Python 3.12 (backend), PostgreSQL 16, Redis 7, Docker Compose.
|
|
|
|
Features v1:
|
|
1. Inscription/connexion (JWT + refresh tokens)
|
|
2. Gameplay puzzle grille 4x4 (pièces = cartes)
|
|
3. Collection personnelle (50 cartes de base)
|
|
4. 3 niveaux de difficulté
|
|
5. Sauvegarde de partie en cours
|
|
6. Profil + statistiques (parties, win rate)
|
|
|
|
Out of scope: boutique, PvP, cartes premium, leaderboard.
|
|
|
|
Tests: pytest backend (>80% coverage), Vitest + Testing Library frontend.
|
|
Docker: dev + prod (nginx pour frontend, uvicorn pour backend).
|
|
Convention: snake_case Python, camelCase TypeScript."
|
|
```
|
|
|
|
**Workflow long avec GSD v2 :**
|
|
```
|
|
# Après /init-project, on initialise GSD à la demande (plus auto-bootstrappé).
|
|
# Les roadmaps de milestone (`.gsd/milestones/<ID>/<ID>-ROADMAP.md`) contiendront :
|
|
# Milestone 1: Boutique in-app + Stripe
|
|
# Milestone 2: PvP + matchmaking
|
|
# Milestone 3: Leaderboard + saisons
|
|
|
|
# Dans un terminal :
|
|
cd cardforge/
|
|
gsd # démarre session GSD
|
|
/gsd init # crée .gsd/ + milestones (à la demande — plus auto à l'init)
|
|
/gsd auto # GSD travaille sur Milestone 1 de façon autonome
|
|
# → research Stripe API + docs
|
|
# → plan décomposé en tâches
|
|
# → exécute chaque tâche dans fresh context window
|
|
# → commits propres avec messages clairs
|
|
# → revient quand Milestone 1 est complet ou si décision requise
|
|
```
|
|
|
|
**Quand le projet est lancé, ajouter des features ponctuelles :**
|
|
```
|
|
# Petite feature rapide (1h) → rester dans CC
|
|
/ship-feature "Ajouter un compteur de combo sur la grille de jeu"
|
|
|
|
# Feature longue (2 jours) → GSD v2
|
|
gsd
|
|
/gsd quick "Implémenter la boutique in-app avec Stripe"
|
|
# ou
|
|
/gsd auto # si la roadmap du milestone est à jour
|
|
```
|
|
|
|
---
|
|
|
|
### Exemple 4 — Onboarding d'un projet existant (CLI Rust)
|
|
|
|
**Contexte :** outil CLI Rust existant sur GitHub, sans CLAUDE.md ni settings.
|
|
|
|
**Workflow :**
|
|
```bash
|
|
git clone git@github.com:user/my-rust-cli.git
|
|
cd my-rust-cli/
|
|
```
|
|
|
|
Dans Claude Code :
|
|
```
|
|
/onboard "Rust CLI"
|
|
|
|
→ PHASE 1 — Discovery:
|
|
Cargo.toml trouvé : name="mycli", edition=2021, version=0.3.1
|
|
Structure: src/main.rs, src/commands/, src/utils/, tests/
|
|
Makefile: targets build, test, release, lint (clippy)
|
|
Pas de Dockerfile (CLI pur)
|
|
|
|
→ PHASE 2 — Interview (manquant):
|
|
Purpose ? → répondre: "CLI de gestion de projets locaux"
|
|
|
|
→ PHASE 3-5 — Génère:
|
|
CLAUDE.md avec stack Rust 1.77, commandes exactes du Makefile
|
|
.claude/settings.json — blocs cargo uniquement
|
|
.claudeignore — target/, *.rlib
|
|
|
|
→ PHASE 6 — GSD v2 ? → skip (projet stable, pas de multi-session)
|
|
|
|
ONBOARD COMPLETE: mycli
|
|
→ Prêt pour /ship-feature
|
|
```
|
|
|
|
```
|
|
/plugin-check "Rust CLI, pas de frontend, pas de deploy"
|
|
|
|
→ SIGNALS: none (CLI pur)
|
|
→ DISABLE: ui-ux-pro-max, gstack, context7
|
|
→ (skills superpowers vendorisés, toujours actifs, 0 t passif)
|
|
→ COST: ~800t (minimal)
|
|
→ ACTION REQUIRED? NO
|
|
```
|
|
|
|
```
|
|
/ship-feature "Ajouter une commande 'mycli export --format json/csv' pour exporter les projets"
|
|
```
|
|
|
|
---
|
|
|
|
### Exemple 5 — Debug d'une régression (mode /analyze DEBUG)
|
|
|
|
**Contexte :** CI qui échoue après un merge, erreur de type TypeScript.
|
|
|
|
**Workflow :**
|
|
```
|
|
/analyze "src/store/cartStore.ts:47:5 - error TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
|
|
|
|
const product = products.find(p => p.id === productId)
|
|
addToCart(product.id) // <-- erreur ligne 47"
|
|
```
|
|
|
|
**Output attendu (DEBUG MODE) :**
|
|
```
|
|
DEBUG ANALYSIS: TS2345 — 'string | undefined' non assignable à 'string' en ligne 47
|
|
|
|
ERROR:
|
|
src/store/cartStore.ts:47 — product.id passé à addToCart(id: string)
|
|
product peut être undefined car Array.find() retourne T | undefined
|
|
|
|
TRACE:
|
|
addToCart(productId) → products.find(p => p.id === productId) → product.id → TS2345
|
|
|
|
ROOT CAUSE HYPOTHESES:
|
|
1. [HIGH] Guard manquant après find() — product non vérifié avant utilisation
|
|
evidence: find() retourne toujours T | undefined, jamais T seul
|
|
2. [MED] Type de addToCart() trop strict (devrait accepter string | undefined)
|
|
evidence: si product peut légitimement être absent, le type est correct
|
|
3. [LOW] Changement récent dans le type Product (id devenu optional)
|
|
evidence: vérifier git log sur Product type
|
|
|
|
WHAT TO VERIFY NEXT:
|
|
- Ajouter guard: if (!product) return; avant ligne 47
|
|
- Ou utiliser optional chaining: addToCart(product?.id ?? '')
|
|
- Vérifier si product absent est un cas métier valide ou une erreur
|
|
|
|
DO NOT TOUCH:
|
|
src/store/cartStore.ts dans son ensemble — corriger seulement la ligne 47
|
|
```
|
|
---
|
|
|
|
### Exemple 6 — CLI Rust from scratch (workflow minimaliste)
|
|
|
|
**Contexte :** outil en ligne de commande, pas de frontend, pas de serveur, pas de Docker. Le cas le plus simple — illustre que le système fonctionne aussi bien sur les projets petits que complexes.
|
|
|
|
**Setup plugins — zéro token inutile :**
|
|
```
|
|
/plugin-check "CLI Rust, convertisseur de fichiers JSON/CSV/TOML, pas de réseau, pas de frontend"
|
|
|
|
→ SIGNALS: none (CLI pur, pas de deploy, pas de frontend)
|
|
→ (skills superpowers vendorisés, toujours actifs, 0 t passif)
|
|
→ DISABLE: ui-ux-pro-max, gstack, context7
|
|
→ COST: ~800t (base seulement)
|
|
→ ACTION REQUIRED? NO
|
|
```
|
|
|
|
L'intérêt ici est de voir que `/plugin-check` est aussi utile pour confirmer qu'on n'a **rien** à activer, évitant de polluer le contexte avec 3000t de plugins inutiles.
|
|
|
|
**Prompt init (complet, pas de questions) :**
|
|
```
|
|
/init-project "CLI Rust 'jsonconv' — convertisseur de formats de données.
|
|
|
|
Stack: Rust 1.77 + Cargo. Libs: serde + serde_json + csv + toml + clap (CLI args).
|
|
|
|
Features v1:
|
|
1. Conversion JSON → CSV
|
|
2. Conversion CSV → JSON
|
|
3. Conversion JSON → TOML
|
|
4. Conversion TOML → JSON
|
|
5. Lecture stdin ou fichier, écriture stdout ou fichier
|
|
|
|
Usage: jsonconv --from json --to csv input.json -o output.csv
|
|
|
|
Out of scope: XML, YAML, validation de schéma, streaming.
|
|
|
|
Tests: cargo test, unitaires par format, doctests pour les fonctions publiques.
|
|
Convention: snake_case partout, erreurs via thiserror, pas de unwrap() en dehors des tests."
|
|
```
|
|
|
|
**Ce que le scaffolder génère (STEP 5) :**
|
|
```
|
|
Cargo.toml (serde, serde_json, csv, toml, clap pinned)
|
|
src/
|
|
main.rs (empty — clap parse + dispatch)
|
|
lib.rs (empty — re-exports)
|
|
converter/
|
|
mod.rs (empty)
|
|
json_csv.rs (empty)
|
|
csv_json.rs (empty)
|
|
json_toml.rs (empty)
|
|
toml_json.rs (empty)
|
|
error.rs (empty — thiserror types)
|
|
tests/
|
|
integration_test.rs (empty)
|
|
.gitignore (target/, *.log)
|
|
.claudeignore (target/)
|
|
|
|
Install : cargo fetch ✅
|
|
Verify : cargo check ✅ (validates Cargo.toml + Rust syntax sans compiler)
|
|
Docker : N/A (CLI pur)
|
|
```
|
|
|
|
**Gate #1 — architecture :**
|
|
Simple à valider. L'architecture proposée est plate, pas de surprise.
|
|
|
|
**Gate #2 — plan d'implémentation (20-25 tâches) :**
|
|
```
|
|
1. [error.rs] Définir ConversionError avec thiserror
|
|
2. [converter/json_csv.rs] fn json_to_csv() — tests first
|
|
3. [converter/json_csv.rs] fn csv_to_json() — tests first
|
|
...
|
|
20. [main.rs] Intégrer clap, dispatcher vers les converters
|
|
21. [tests/integration_test.rs] Tests end-to-end avec fichiers fixtures
|
|
```
|
|
|
|
**Après init — features complémentaires :**
|
|
```
|
|
/ship-feature "Ajouter conversion YAML ↔ JSON via serde_yaml"
|
|
/ship-feature "Ajouter flag --pretty pour indentation JSON output"
|
|
/refactor src/converter/ # après plusieurs features, si violations de normes
|
|
/analyze src/converter/json_csv.rs # avant une grosse modification
|
|
```
|
|
|
|
**Points clés de cet exemple :**
|
|
- `/plugin-check` confirme "rien à activer" — actif et utile même pour dire non
|
|
- Scaffolder génère un Cargo.toml avec deps pinned — pas de `cargo add` manuel
|
|
- `cargo check` comme verify évite un full compile sur un skeleton vide
|
|
- Pas de GSD v2 : CLI simple, toutes les features tiennent en 1-2 sessions CC
|
|
|
|
---
|
|
|
|
## Bonnes pratiques — résumé
|
|
|
|
**Plugins :** toujours vérifier avant de commencer. Les gates de validation de `/init-project` et `/ship-feature` sont des points de contrôle — ne jamais "force" une gate d'architecture sans l'avoir lue.
|
|
|
|
**Prompts :** plus le prompt initial est précis (stack, features, conventions), moins il y a de questions. Un prompt de 15 lignes structuré élimine l'interview entière.
|
|
|
|
**GSD v2 :** dès qu'une feature ou un projet dépasse une journée de développement. Le signal est : "je vais devoir ouvrir plusieurs sessions pour finir ça". GSD v2 résout la perte de contexte entre sessions.
|
|
|
|
**`/onboard` :** pour tout projet existant. Même si le projet est fonctionnel, CLAUDE.md et `.claude/settings.json` améliorent significativement la qualité des interactions suivantes.
|
|
|
|
**`/analyze` avant `/refactor` :** toujours. Le refactorer attend le rapport d'analyse avant de toucher au code. Le passer en bypass donne de moins bons résultats.
|
|
|
|
**`/doc` régulièrement :** après chaque milestone. Le mode AUDIT compare la documentation à l'état réel du code et liste les divergences — évite la documentation périmée.
|
|
|
|
---
|
|
|
|
### Exemple 7 — Refactoring d'un module Python legacy
|
|
|
|
**Contexte :** module `services/payment_service.py` dans un projet FastAPI existant. Écrit il y a 2 ans, jamais refactorisé. Violations connues : fonctions de 80 lignes, global state, pas de tests unitaires, logique métier mélangée avec appels HTTP.
|
|
|
|
**Setup :** projet déjà onboardé (CLAUDE.md présent), skills superpowers vendorisés (toujours actifs, 0 t passif), plugins inutiles désactivés.
|
|
|
|
#### Étape 1 — Analyse avant toute modification
|
|
|
|
```
|
|
/analyze src/services/payment_service.py
|
|
```
|
|
|
|
**Ce que l'analyzer produit :**
|
|
```
|
|
ANALYSIS: src/services/payment_service.py
|
|
|
|
CONTEXT:
|
|
- Module de 340 lignes gérant les paiements Stripe
|
|
- Pas de tests, 3 variables globales, 2 fonctions > 80 lignes
|
|
|
|
KEY COMPONENTS:
|
|
- process_payment(): 95 lignes — logique métier + appel Stripe + logging entremêlés
|
|
- _build_stripe_payload(): 72 lignes — construction du payload + validation + mapping
|
|
- STRIPE_CLIENT: variable globale initialisée au module load (non mockable)
|
|
- retry_payment(): appelle process_payment() directement (couplage fort)
|
|
|
|
CONSTRAINTS:
|
|
- Aucun test existant — refactoring sans filet
|
|
- retry_payment() appelé par 3 endpoints différents — interface publique à préserver
|
|
|
|
RISKS:
|
|
- Modification de process_payment() peut casser les 3 appelants — probability: high
|
|
- STRIPE_CLIENT global rend les tests unitaires impossibles sans monkeypatch — probability: high
|
|
- _build_stripe_payload() mélange validation et mapping — extraction risquée — probability: medium
|
|
|
|
OPEN QUESTIONS:
|
|
- process_payment() retourne-t-il toujours un dict ou parfois None ?
|
|
- Les appelants de retry_payment() vérifient-ils le code de retour ?
|
|
```
|
|
|
|
#### Étape 2 — Refactoring guidé
|
|
|
|
```
|
|
/refactor src/services/payment_service.py
|
|
```
|
|
|
|
**Ce que le refactorer produit d'abord (rapport avant modification) :**
|
|
```
|
|
VIOLATIONS DETECTED: src/services/payment_service.py
|
|
|
|
- [NORM] process_payment(): 95 lignes → split plan: _validate_payment(), _call_stripe(), _handle_response()
|
|
- [NORM] _build_stripe_payload(): 72 lignes → split plan: _validate_payload(), _map_to_stripe()
|
|
- [NORM] STRIPE_CLIENT: global state → inject via paramètre ou dependency injection
|
|
- [QUALITY] logique métier dans process_payment() mélangée avec appel HTTP Stripe
|
|
- [QUALITY] retry_payment() appelle process_payment() directement (tight coupling)
|
|
|
|
PLAN:
|
|
1. Extraire _validate_payment() depuis process_payment() (lignes 12-28)
|
|
2. Extraire _call_stripe() depuis process_payment() (lignes 45-67)
|
|
3. Extraire _handle_response() depuis process_payment() (lignes 68-95)
|
|
4. Réécrire process_payment() comme coordinateur des 3 sous-fonctions
|
|
5. Extraire _validate_payload() et _map_to_stripe() depuis _build_stripe_payload()
|
|
6. Injecter stripe_client via paramètre (défaut = STRIPE_CLIENT global pour rétro-compat)
|
|
|
|
TESTS PRESENT: non
|
|
→ ⚠️ Aucun test existant. Le refactoring est risqué sans filet.
|
|
Recommandation: créer des tests d'intégration minaux AVANT de toucher au code.
|
|
Procéder malgré tout ? (yes / create tests first)
|
|
```
|
|
|
|
**User répond : "create tests first"**
|
|
|
|
Le refactorer génère d'abord `tests/test_payment_service.py` avec des tests d'intégration basiques qui capturent le comportement actuel (avant refactoring). Puis procède au refactoring fonction par fonction.
|
|
|
|
#### Étape 3 — Vérification finale
|
|
|
|
```
|
|
/analyze src/services/payment_service.py
|
|
```
|
|
|
|
Post-refactoring, l'analyzer confirme :
|
|
```
|
|
VIOLATIONS FIXED:
|
|
- process_payment(): 95 lignes → 18 lignes (coordinateur) ✅
|
|
- STRIPE_CLIENT: injectable, toujours rétro-compatible ✅
|
|
- Interface publique de retry_payment() inchangée ✅
|
|
|
|
REMAINING:
|
|
- _build_stripe_payload() : 48 lignes (sous le seuil de 25 mais proche)
|
|
→ justified: validation + mapping ne peuvent pas être séparés sans risque
|
|
|
|
TESTS: ✅ 8 tests passent (créés avant refactoring)
|
|
```
|
|
|
|
#### Points clés de cet exemple
|
|
|
|
- **`/analyze` d'abord, toujours.** L'analyzer identifie les risques (3 appelants, pas de tests) AVANT que le refactorer ne touche au code. Sans ça, le refactorer aurait pu casser l'interface publique.
|
|
- **Le refactorer s'arrête si pas de tests.** Ce comportement est intentionnel — refactorer sans tests = régression silencieuse garantie. Proposer de créer des tests d'abord est la bonne réponse.
|
|
- **Rapport de violations avant modifications.** Le refactorer produit toujours un rapport + plan, attend confirmation, puis exécute. Jamais aveugle.
|
|
- **`/analyze` après pour confirmer.** Le cycle analyse → refactor → analyse est la boucle de qualité correcte.
|
|
|
|
---
|
|
|
|
### Exemple 8 — Reprise d'une session interrompue avec GSD v2
|
|
|
|
**Contexte :** projet CardForge (React + FastAPI), milestone 2 "Boutique Stripe" en cours. Travail interrompu 4 jours plus tôt. GSD v2 initialisé, 3/7 slices terminées.
|
|
|
|
#### Étape 1 — Orientation rapide
|
|
|
|
```
|
|
/status
|
|
|
|
PROJECT STATUS
|
|
==============
|
|
|
|
CONFIG
|
|
Version : v2.5.0
|
|
Plugins ON: context7 (~200t), skills superpowers vendorisés (toujours actifs, 0 t passif)
|
|
GSD v2 : installed (3.0.0)
|
|
|
|
PROJECT
|
|
CLAUDE.md : found
|
|
Stack : React 18 + FastAPI + PostgreSQL + Docker
|
|
Branch : feature/stripe-integration
|
|
Uncommitted: 1 file (src/components/checkout/CartSummary.tsx)
|
|
|
|
RECENT COMMITS:
|
|
b3c4d5e feat: add cart persistence to localStorage
|
|
f6g7h8i feat: implement card collection display
|
|
j9k0l1m chore: setup Stripe SDK
|
|
|
|
GSD v2
|
|
Status : initialized
|
|
Milestone : Milestone 2 — Boutique in-app
|
|
Progress : 3/7 slices done (43%)
|
|
```
|
|
|
|
En 5 secondes : je sais où j'en suis, ce qui était en cours, et qu'il reste 4 slices à faire.
|
|
|
|
#### Étape 2 — Reprendre GSD v2 (terminal)
|
|
|
|
```bash
|
|
cd cardforge/
|
|
gsd # relance une session GSD
|
|
```
|
|
|
|
GSD v2 lit `.gsd/` et reconstruit le contexte :
|
|
```
|
|
GSD v2 — Resume session
|
|
Current milestone: Milestone 2 — Boutique in-app
|
|
Last completed : Slice 3 — Cart UI
|
|
Next up : Slice 4 — Stripe checkout integration
|
|
|
|
Previous session crash detected? No — clean shutdown.
|
|
State loaded from .gsd/state.db ✓
|
|
|
|
/gsd auto → reprendre en mode autonome
|
|
/gsd → reprendre en step mode (recommandé après longue pause)
|
|
```
|
|
|
|
#### Étape 3 — Reprendre en step mode (recommandé après pause longue)
|
|
|
|
```
|
|
/gsd
|
|
|
|
── Slice 4 — Stripe checkout integration ──
|
|
Tasks:
|
|
[ ] 4.1 — Implement PaymentIntent creation (backend)
|
|
[ ] 4.2 — Add Stripe Elements to CartSummary.tsx
|
|
[ ] 4.3 — Handle payment confirmation + webhook
|
|
[ ] 4.4 — Integration test: checkout flow
|
|
|
|
Research: Stripe docs fetched (context7 active)
|
|
Plan: ready
|
|
|
|
Execute slice 4? (yes / review plan / modify)
|
|
```
|
|
|
|
Le step mode permet de relire le plan avant d'exécuter — critique après une pause où les décisions peuvent avoir changé.
|
|
|
|
#### Étape 4 — Si une décision d'architecture a changé pendant la pause
|
|
|
|
```
|
|
/gsd discuss
|
|
|
|
"Je veux utiliser Stripe Payment Element au lieu de CardElement —
|
|
c'est l'API recommandée depuis 2023"
|
|
|
|
GSD v2 integrates your input into the current plan.
|
|
Updated: Slice 4 plan — Payment Element instead of CardElement
|
|
Continue? (yes)
|
|
```
|
|
|
|
GSD v2 met à jour le plan dans la base GSD (`.gsd/gsd.db`) sans perdre le travail déjà fait.
|
|
|
|
#### Ce que ce workflow démontre
|
|
|
|
- **`/status`** est le point d'entrée naturel après une pause — snapshot complet en 1 commande.
|
|
- **GSD v2 `step mode`** est préférable à `auto` après une longue pause — permet de vérifier que les décisions sont toujours valides.
|
|
- **La base GSD (`.gsd/gsd.db`)** est la source de vérité du progress; `/status` la lit via `gsd headless query`.
|
|
- **`/gsd discuss`** permet de modifier l'architecture en cours de route sans recommencer depuis zéro.
|
|
---
|
|
|
|
### Exemple 9 — Firmware C/C++ embarqué (workflow sans superpowers)
|
|
|
|
**Contexte :** firmware pour microcontrôleur STM32 (C, bare-metal). Pas de réseau, pas de frontend, pas de Docker. L'outillage standard de superpowers (brainstorming Socratique, subagent pipeline) est surdimensionné pour ce contexte.
|
|
|
|
**Setup plugins :**
|
|
```
|
|
/plugin-check "Firmware C STM32, bare-metal, pas de réseau, pas de frontend, pas de Docker"
|
|
|
|
SIGNALS: simple, CLI/embedded
|
|
COST: ~0t (skills superpowers vendorisés, toujours actifs, 0 t passif)
|
|
|
|
RECOMMENDATIONS:
|
|
DISABLE : ui-ux-pro-max, gstack, context7
|
|
NOTE : skills superpowers (brainstorming, writing-plans...) restent
|
|
disponibles par nom bare sans coût passif, même pour un
|
|
firmware minimal.
|
|
```
|
|
|
|
**Workflow minimaliste — modification d'un driver existant :**
|
|
|
|
```
|
|
# Pas de /init-project, pas de GSD ; skills superpowers vendorisés
|
|
# (toujours actifs, 0 t passif) mais non invoqués ici
|
|
|
|
# 1. Comprendre avant de modifier
|
|
/analyze src/drivers/uart.c
|
|
|
|
OUTPUT:
|
|
ANALYSIS: src/drivers/uart.c
|
|
CONTEXT: Driver UART pour STM32F4, DMA en mode circulaire
|
|
KEY COMPONENTS:
|
|
uart_init(): 45 lignes — config registres + DMA
|
|
uart_send(): 12 lignes — écriture dans ring buffer
|
|
UART_IRQHandler(): 28 lignes — ISR, gère overrun
|
|
RISKS:
|
|
- uart_init() dépasse 25 lignes → split candidat
|
|
- Accès non-atomique à ring_buffer_head dans ISR — probability: high
|
|
OPEN QUESTIONS:
|
|
- Quid si DMA transfer pas terminé avant appel uart_send() ?
|
|
```
|
|
|
|
**Modification chirurgicale :**
|
|
```
|
|
/ship-feature "Corriger l'accès non-atomique au ring_buffer_head dans l'ISR"
|
|
|
|
STEP 0b — CLAUDE.md found
|
|
STEP 0 — plugin check: skills superpowers vendorisés (toujours actifs, 0 t passif)
|
|
|
|
STEP 1 — BRAINSTORM (rapide, contexte déjà clair depuis /analyze):
|
|
Design: protéger ring_buffer_head avec __disable_irq()/__enable_irq()
|
|
ou utiliser un flag volatile + memory barrier
|
|
|
|
STEP 3 — VALIDATION GATE:
|
|
TASKS: 2
|
|
1. [src/drivers/uart.c] Ajouter protection atomique dans UART_IRQHandler
|
|
2. [tests/test_uart.c] Ajouter test simulant ISR concurrent
|
|
|
|
STEP 4 — IMPLEMENT (subagents légers, modifications chirurgicales)
|
|
```
|
|
|
|
**Alternative : workflow encore plus minimaliste (sans /ship-feature) :**
|
|
```
|
|
# Pour un hotfix ultra-ciblé, ignorer l'orchestrateur
|
|
/analyze src/drivers/uart.c # comprendre
|
|
# → modifier directement avec Edit tool
|
|
# → vérifier avec make + flash sur hardware
|
|
```
|
|
|
|
**Points clés :**
|
|
- `/plugin-check` confirme qu'aucun plugin inutile n'est actif (skills superpowers vendorisés, toujours actifs, 0 t passif).
|
|
- `/analyze` est particulièrement utile sur du code C bas-niveau : l'analyzer identifie les accès non-atomiques, les race conditions, les violations de normes, **sans proposer de fix**.
|
|
- Pour un firmware, le workflow `analyze → ship-feature` peut se réduire à `analyze → edit direct` si la modification est triviale.
|
|
- GSD v2 n'est jamais pertinent pour du firmware : les sessions sont courtes et les tâches atomiques.
|
|
---
|
|
|
|
## Référence rapide — signaux → plugins
|
|
|
|
```
|
|
Description contient... → Plugin
|
|
─────────────────────────────────────────────────────
|
|
Next.js 13+ / App Router → context7 WARN
|
|
Prisma / Supabase → context7 ON
|
|
"design élaboré" / tokens → ui-ux-pro-max ON
|
|
Docker + QA browser → gstack ON
|
|
"plusieurs semaines" → gsd v2 CLI
|
|
Rust / Python / Go / C → tout OFF (skills superpowers vendorisés, 0t)
|
|
Mobile / Flutter / RN → gstack OFF
|
|
Hotfix / script rapide → tout OFF (skills superpowers vendorisés, 0t)
|
|
```
|