# Guide d'utilisation de Claude Code — Mediknode / Unified > Guide pratique de A à Z pour tirer parti de la config Claude de ce projet. > Public : toi et ton équipe de dev. Aucun prérequis Claude avancé. --- ## Sommaire 1. [C'est quoi, concrètement ?](#1-cest-quoi-concrètement-) 2. [Les 3 briques : Skills, Sub-agents, Commands](#2-les-3-briques) 3. [Démarrage en 30 secondes](#3-démarrage-en-30-secondes) 4. [Le workflow type (à suivre les yeux fermés)](#4-le-workflow-type) 5. [Recettes par situation](#5-recettes-par-situation) 6. [Référence rapide des commandes](#6-référence-rapide-des-commandes) 7. [Référence rapide des agents](#7-référence-rapide-des-agents) 8. [Astuces qui changent tout](#8-astuces-qui-changent-tout) 9. [Pièges à éviter](#9-pièges-à-éviter) 10. [Maintenir et faire évoluer la config](#10-maintenir-et-faire-évoluer-la-config) 11. [FAQ](#11-faq) --- ## 1. C'est quoi, concrètement ? On a appris à Claude **comment marche CE projet** (et pas un Laravel générique) : le routing multi-sous-domaine, le multi-instance par client, le service layer, le pattern Meta, les observers d'audit, et **ta façon d'écrire les tests**. Résultat : tu donnes une intention courte (« corrige le bouton annuler validation »), et Claude suit automatiquement tes conventions au lieu de réinventer un style. Tout est dans le dossier `.claude/` : ``` .claude/ ├── GUIDE.md ← ce fichier ├── README.md ← index court ├── agents/ ← 7 spécialistes ├── commands/ ← 7 raccourcis (slash commands) └── skills/ ← 5 « savoirs » chargés automatiquement ``` --- ## 2. Les 3 briques | Brique | Ce que c'est | Qui le déclenche | Analogie | |--------|--------------|------------------|----------| | **Skill** | Une fiche de connaissance du projet (conventions, routing, tests…) | **Claude tout seul**, quand c'est pertinent | Le manuel posé sur le bureau | | **Sub-agent** | Un spécialiste avec sa mission et ses outils | Claude délègue, ou **toi** : « utilise l'agent X » | Un collègue expert d'un domaine | | **Command** | Un workflow pré-écrit lancé par `/nom` | **Toi**, en tapant `/` | Un bouton « faire la procédure complète » | **La différence clé :** - Tu ne « lances » jamais un skill — il s'active seul. Tu écris juste du code et la bonne fiche se charge. - Tu lances un **agent** quand tu veux déléguer une tâche ciblée à un expert isolé. - Tu lances une **command** (`/`) quand tu veux dérouler une procédure complète, balisée. --- ## 3. Démarrage en 30 secondes 1. Ouvre Claude Code dans le dossier du projet (`c:\codebase\unified`). 2. Tape `/` → tu vois apparaître `new-feature`, `fix-bug`, `add-import`, etc. 3. Choisis-en une et complète l'argument. Exemple : ``` /fix-bug le bouton "annuler la validation" d'un participant ne fait rien ``` 4. Laisse Claude travailler. Il te rend : cause, correctif, test, résultat. C'est tout. Le reste du guide sert à aller plus loin. --- ## 4. Le workflow type Le même schéma marche pour 90 % des tâches du backlog : ``` 1. DÉCRIRE → /new-feature ou /fix-bug ou /add-import … 2. CADRER → Claude pose UNE question si c'est ambigu (instance ? front/back ?) 3. IMPLÉMENTER → l'agent adapté code, en réutilisant les patterns existants 4. TESTER → un test est écrit + lancé automatiquement (php artisan test --filter) 5. VÉRIFIER → /pre-commit (pint + php -l + tests + mini revue sécu) 6. RELIRE → tu lis le diff, tu valides 7. COMMIT → tu demandes explicitement le commit (Claude ne commit jamais sans accord) ``` > 💡 Étapes 4 et 5 sont automatiques dans les commands. Tu n'as à penser qu'à 1, 6 et 7. --- ## 5. Recettes par situation ### A. « J'ai un bug à corriger » (ex. #68, #69, #70) ``` /fix-bug ``` Claude reproduit, trouve la cause, écrit un **test qui échoue d'abord**, corrige, revérifie. 👉 Plus tu donnes de repro (URL, qui clique quoi, message d'erreur), plus c'est rapide. ### B. « Je veux ajouter une fonctionnalité » (ex. #4, #16, #31) ``` /new-feature ajouter le champ has_evaluation dans le formulaire d'édition d'un événement ``` Claude demande front ou back / quelle instance, puis route + contrôleur + vue + test. ### C. « Je travaille sur un import/export » (ex. #34, #46, #64, #73) ``` /add-import participants depuis le XLSX d'inscription, refuser les doublons email/téléphone /add-export liste des ateliers par opérateur, joliment formatée ``` L'agent `excel-io` applique d'office : dedup, vérif pays/nom, logs, mode force, pattern Meta. ### D. « C'est spécifique à un client » (ex. #76 FPI, #95 JPT, #86 KEA) ``` /new-instance JPT ajouter la page news + programme ``` L'agent `multi-instance` gère la branche par domaine, le thème Blade du client, l'état Brevo. ### E. « Je veux juste des tests » (ex. #29, #65) ``` /write-tests couvrir le calcul de total_price et le PaymentService ``` Priorité automatique aux chemins argent / imports / RBAC. ### F. « Avant de committer » ``` /pre-commit ``` Lance pint sur les fichiers changés, `php -l`, les tests de la zone, une mini-revue (route protégée ? total côté serveur ? hard delete sur entité auditée ?), **et un contrôle de synchro `CLAUDE.md`** : si ton diff rend une convention obsolète, Claude te le signale et propose l'édition — sans l'appliquer sans ton accord. Sinon il ne touche pas à `CLAUDE.md`. ### G. « Revue de sécurité » (avant un merge sensible) ``` utilise l'agent security-reviewer sur le diff actuel ``` Il classe les findings par sévérité avec fichier:ligne et remédiation. ### H. Enchaîner les agents (cas réel) Pour un gros sujet comme #65 (faux totaux) : ``` 1. utilise bug-investigator pour trouver pourquoi total_price est faux 2. /write-tests pour verrouiller le bon calcul 3. utilise security-reviewer pour vérifier qu'aucun total ne vient du client ``` --- ## 6. Référence rapide des commandes | Commande | À taper | Pour | |----------|---------|------| | `/new-feature` | `/new-feature ` | Feature complète + test | | `/fix-bug` | `/fix-bug ` | Bug + test de régression | | `/add-import` | `/add-import ` | Import Excel durci | | `/add-export` | `/add-export ` | Export Excel formaté | | `/write-tests` | `/write-tests ` | Tests aux conventions du projet | | `/new-instance` | `/new-instance ` | Adaptation par client | | `/pre-commit` | `/pre-commit` | Quality gate avant commit | --- ## 7. Référence rapide des agents | Agent | Spécialité | Le lancer | |-------|-----------|-----------| | `laravel-feature` | Feature back/front bout-en-bout | « utilise laravel-feature pour… » | | `livewire-expert` | Livewire 3, module Participants | « utilise livewire-expert pour… » | | `excel-io` | Imports/Exports Excel | (auto via `/add-import` `/add-export`) | | `test-writer` | Tests Feature/Unit | (auto via `/write-tests`) | | `bug-investigator` | Repro + fix + régression | (auto via `/fix-bug`) | | `multi-instance` | Spécifique client | (auto via `/new-instance`) | | `security-reviewer` | Revue sécu/intégrité | « utilise security-reviewer sur… » | > Tu peux toujours invoquer un agent à la main, même sans command : « lance l'agent test-writer sur ImportParticipants ». --- ## 8. Astuces qui changent tout 1. **Sois précis dans l'intention, pas dans le comment.** ✅ « corrige : annuler la validation laisse validated_at rempli » ❌ « ouvre ParticipantController ligne 412 et change le if » Claude connaît déjà tes patterns — dis-lui le *quoi*, laisse-le sur le *comment*. 2. **Donne une repro pour les bugs.** URL + qui clique + ce qui devrait se passer. Ça divise le temps par deux. 3. **Une tâche = une command.** N'empile pas « fais #4 + #16 + #31 » : lance-les une par une, tu relis mieux. 4. **Relis toujours le diff avant de committer.** Claude est bon, pas infaillible. Le `/pre-commit` t'aide mais ta relecture reste le garde-fou. 5. **Le commit, c'est toi qui le déclenches.** Claude ne committe jamais tout seul. Dis « commit » quand tu es prêt. 6. **Pour les gros sujets vagues du backlog** (#12 mobile, #59, #144 résa) : commence par « aide-moi à découper #144 en sous-tâches » avant de coder. Cadrer > foncer. 7. **`Échap` interrompt.** Si Claude part dans la mauvaise direction, coupe et reformule — pas besoin d'attendre la fin. 8. **`#` pour mémoriser une préférence.** Tape `# toujours utiliser des Form Request pour plus de 2 champs` et Claude le retient pour la suite. 9. **Les skills se chargent seuls** quand tu touches au code concerné. Tu n'as rien à faire — mais si tu vois Claude ignorer une convention, rappelle-la : « respecte la convention de test du projet ». 10. **Plan d'abord pour le risqué.** Pour tout ce qui touche argent/delete/migration, demande « fais-moi un plan d'abord » avant d'autoriser l'écriture. --- ## 9. Pièges à éviter | Piège | Conséquence | À faire à la place | |-------|-------------|--------------------| | Lancer une tâche énorme et vague (« mobile render ») | Résultat dispersé | Découper d'abord en sous-tickets | | Empiler 5 tâches dans un message | Diff illisible | Une command à la fois | | Committer sans relire | Régression silencieuse | `/pre-commit` + relecture du diff | | Oublier de préciser l'instance | Code appliqué partout | Toujours dire « pour JPT » / « toutes instances » | | Demander un test « vite fait » | Assertion faible inutile | Laisser `test-writer` couvrir le chemin critique | | Toucher au hard delete d'une entité auditée | Perte de la piste d'audit | `security-reviewer` le signalera | | `.env.*` dans un commit | Fuite de secrets | Jamais committer les `.env` | --- ## 10. Maintenir et faire évoluer la config La config vit avec le projet. Pour la modifier : - **Ajouter une convention** → édite le skill concerné dans `.claude/skills//SKILL.md`. - **Créer une nouvelle command** → crée `.claude/commands/.md` (copie une existante comme modèle). - **Créer un agent** → crée `.claude/agents/.md` avec un frontmatter `name`/`description`/`tools`. - **Demander à Claude de le faire** : « ajoute une command /new-mailable qui scaffold un Mailable + test ». **Activer des automatisations (hooks)** — non installées pour l'instant, sur ton choix. Si tu veux par ex. lancer Pint automatiquement après chaque édition PHP, demande : « configure un hook qui lance pint après chaque edit » (Claude utilisera la skill `update-config`). **Versionner pour l'équipe :** `agents/`, `commands/`, `skills/`, `GUIDE.md`, `README.md` se committent pour toute l'équipe. `settings.local.json` (permissions perso) reste local, non versionné. --- ## 11. FAQ **Q. Dois-je apprendre tous les agents par cœur ?** Non. Tape `/`, lis les descriptions, choisis. Pour le reste, décris ton besoin en français, Claude choisit le bon agent. **Q. Skill vs agent vs command, lequel j'utilise ?** En pratique : tu utilises surtout les **commands** (`/`). Les **agents** quand tu veux un expert précis. Les **skills**, jamais directement — ils s'activent seuls. **Q. Claude peut-il committer / pousser tout seul ?** Non, pas sans que tu le demandes explicitement. Le code reste sous ton contrôle. **Q. Et si une command ne fait pas exactement ce que je veux ?** Continue la conversation en langage normal : « non, plutôt comme ça… ». La command n'est qu'un point de départ balisé. **Q. Ça marche sur quelles tâches du backlog ?** Quasi toutes les tâches *code*. Les tâches perso/infra (#82 CV, #134 VPS, #141 réunion) sortent du périmètre — voir `ANALYSE_BACKLOG.md`. **Q. Faut-il mettre à jour `CLAUDE.md` après chaque tâche ?** Non — seulement quand une tâche rend une convention/structure du fichier obsolète (ex. soft delete généralisé, nouveau module, changement de routing). Le `/pre-commit` vérifie ça pour toi : il signale et propose l'édition uniquement si nécessaire, sans jamais l'appliquer sans ton accord. Pour un bugfix ou une feature qui suit les conventions existantes : on n'y touche pas. **Q. Comment je teste que tout marche ?** Lance un quick win réel : `/fix-bug` sur le #68, ou `/new-feature` sur le #4. Tu verras le workflow complet. --- *Config décrite dans `.claude/README.md`. Conventions de fond dans `CLAUDE.md` (racine).*