Formation gratuite

Formation Claude Code gratuite – 2026

Ce guide part d’une utilisation basique (génération de code à la demande) et la transforme en un environnement de développement contraint, testé et traçable, utilisable sur une vraie base de code en production. Chaque section est autonome : un concept, une mise en œuvre concrète, les pièges associés.

28 min de lecture
12 chapitres
Aucun email demandé

1. Prise en main

Claude Code est un agent en ligne de commande : il lit les fichiers du projet, propose des modifications, exécute des commandes (tests, build, git) et attend votre validation. Cette section couvre le strict nécessaire pour être opérationnel en une vingtaine de minutes.

1.1 Installation et premier lancement

Claude Code s’utilise via l’application Claude disponible sur Mac ou Windows, via une extension Visual Studio Code ou en global via npm (Node 18+). Une fois installé, on le lance depuis la racine du projet, c’est le dossier courant qui définit le périmètre de travail. Une application desktop (Windows/macOS) existe depuis longtemps pour ceux qui ne veulent pas du terminal ; elle expose le même moteur avec une interface graphique. Pour débuter, le terminal reste le plus direct.

1.2 Boucle de travail de base

Le cycle élémentaire tient en six gestes. L’objectif est de ne jamais accepter de modification sans l’avoir relue : c’est vous qui restez responsable de ce qui entre dans le dépôt.

# 1. Décrire le besoin en langage naturel
> ajoute une validation d'email au formulaire d'inscription

# 2. Claude lit les fichiers concernés et propose un diff
# 3. Relire le diff (ne pas valider à l'aveugle)
# 4. Accepter, refuser, ou demander un ajustement ciblé
> le message d'erreur doit être en français et accessible aux lecteurs d'écran

# 5. Vérifier que le code tourne
> lance les tests unitaires du module d'inscription

# 6. Committer
> crée un commit avec un message conventionnel

1.3 Modes de permission

Le mode de permission détermine ce que l’agent peut faire sans vous demander. On en change à la volée en cyclant avec Shift+Tab, ou au lancement avec --permission-mode. Sur l’application Windows / Mac on utilise la sélection du mode de permission dessous le chat.

Mode	Comportement	Quand l’utiliser
`default`	Demande confirmation avant chaque écriture / commande	Découverte, code sensible
`acceptEdits`	Accepte automatiquement les éditions de fichiers	Tâche cadrée où vous relisez le diff global ensuite
`plan`	Lecture seule : explore et propose un plan, n’écrit rien	Cadrage avant d’écrire la moindre ligne
`bypassPermissions`	N’demande plus rien (dont commandes shell)	Environnement jetable uniquement (conteneur, worktree)
`auto`	Décide seul quand demander selon le risque	Usage quotidien une fois en confiance

# Démarrer en lecture seule pour cadrer sans rien modifier
claude --permission-mode plan

1.4 Suivi du contexte

Claude travaille dans une « fenêtre de contexte » de taille limitée (voir 2.2). Quand elle se remplit, la qualité chute et les instructions anciennes sont oubliées. Le statusline affiche l’occupation en temps réel ; deux commandes aident à la gérer.

# Voir ce qui occupe le contexte (fichiers lus, conversation, mémoire)
/context

# Compacter la conversation en un résumé pour libérer de la place
/compact

1.5 Annulation et points de restauration

Claude Code conserve un historique de points de restauration internes. En complément, git reste le filet de sécurité ultime avant toute opération risquée.

# Ouvrir l'historique des points de restauration (revenir en arrière)
Échap Échap        # double Échap
/rewind            # ou via la commande

# Filet git avant une opération risquée (refacto large, migration)
git stash push -m "checkpoint avant refacto"
git switch -c experimentation   # branche jetable

1.6 Erreurs fréquentes en début d’usage

Sauter le process de plan complexe. Lancer une tâche large sans cadrage produit un gros diff incohérent. Utilisez le mode plan (section 5) ou le process préconisé si besoin d’exécuter après.
Valider les diffs à l’aveugle. Le code généré « ressemble » à du bon code (section 3). Relisez.
Ignorer le contexte. Une session trop longue dérive ; compactez ou redémarrez.
Prompts vagues. « Améliore ça » donne des résultats imprévisibles ; décrivez le comportement attendu et son périmètre.
Mélanger des tâches sans rapport dans une même session : le contexte se pollue. Une session = une intention.
Permissions trop larges par confort, sur un environnement non jetable.

2. Modèle d’exécution

Comprendre comment Claude Code fonctionne en interne permet de le contraindre efficacement. Quatre notions suffisent : l’agent, le contexte, la session, le modèle.

2.1 Agent vs assistant conversationnel

L’assistant conversationnel (l’interface web) répond par du texte. L’agent, lui, agit : il dispose d’outils pour lire et écrire des fichiers, lancer des commandes, exécuter des tests. La conséquence pratique est qu’un agent peut produire des effets de bord réels sur votre machine et votre dépôt — d’où l’importance des validations et des garde-fous.

	Assistant conversationnel	Agent (Claude Code)
Entrée	Une question	Une intention sur un projet
Action	Génère du texte	Lit, modifie, exécute, teste
Sortie	Une réponse	Un changement que vous validez

2.2 Fenêtre de contexte et tokens

Un token est un fragment de texte (≈ ¾ d’un mot en anglais). La fenêtre de contexte est la quantité de tokens que le modèle garde « en tête » pour une requête : selon le modèle, de l’ordre de 200 000 à 1 000 000 de tokens. À titre indicatif, 1 M de tokens représente grossièrement 75 000 lignes de code, c’est à dire insuffisant pour absorber d’un coup une grosse base existante, d’où le besoin de stratégies de chargement ciblé dans le cas de grosses codebases (sections 4 et 7).

Tout ce qui occupe le contexte est rechargé à chaque message : le CLAUDE.md, les fichiers lus, l’historique de la conversation, votre prompt. Plus on en met, plus c’est lent et coûteux.

2.3 Cycle d’une session

Une session suit un cycle d’événements sur lesquels on peut se greffer (les hooks, section 4.7). C’est ce cycle qui rend l’agent personnalisable de façon déterministe.

SessionStart        → chargement du contexte (CLAUDE.md, rules, skills découverts)
UserPromptSubmit    → réception de l'intention ; un skill peut s'activer
   ┌─ boucle ────────────────────────────____────────────────────┐
   │  PreToolUse   → avant chaque appel d'outil (read/edit/bash) │
   │  (l'outil s'exécute) et on peut déclencher des outils       │
   │  sur cet état (par exemple pour remplacer un grep par       │
   │  quelque chose de plus puissant                             │
   │  PostToolUse  → après chaque appel d'outil (pareil que pre) │
   └───────────────────────────────────────────────────_─────────┘
Stop                → fin du tour ; les contrôles de qualité passent
PreCompact          → juste avant un compactage du contexte

2.4 Modes interactif et non-interactif

Le même moteur se lance de deux façons. En interactif, vous dialoguez tour par tour. En non-interactif (« headless »), une seule passe s’exécute sans humain dans la boucle — c’est ce qui permet de l’intégrer dans un script, un cron ou une CI (section 11).

# Mode interactif (dialogue)
claude

# Mode non-interactif : une passe, pas d'humain dans la boucle
claude -p "corrige le lint du dossier src/ puis committe"

# Sortie structurée, exploitable par un script ou une CI
claude -p "résume les changements du dernier commit" --output-format stream-json

2.5 Sélection de modèle et coûts

Plusieurs modèles existent, avec un compromis capacité / coût / vitesse. La règle pratique : le plus petit modèle qui fait le travail. On réserve les gros modèles à l’analyse complexe, la planification et l’arbitrage final.

Modèle	Profil	Coût in/out ($ / Mtok)	Usage type
Haiku	Rapide, économique	≈ 0,25 / 1,25	Balayage, lecture massive, synthèse simple
Sonnet	Équilibré (défaut)	≈ 3 / 15	Écriture de code au quotidien
Opus	Le plus capable	≈ 15 / 75	Problèmes complexes, planification, étape juge
Fable 5	Dernière génération	élevé	Tâches les plus exigeantes (à mesurer)

# Choisir le modèle au lancement
claude --model opus

# Choisir le modèle sur l'app win/mac
cliquer en bas à droite du chat :)

# Changer de modèle en cours de session
/model sonnet

3. Modes de défaillance du code généré

Avant d’outiller, il faut comprendre pourquoi le code généré sans cadre échoue en production. Ces modes de défaillance justifient chacune des contraintes mises en place dans les sections suivantes.

3.1 Données empiriques

Plusieurs analyses publiées en 2025 convergent : une part importante du code produit par des assistants présente des défauts qui ne se voient pas à la relecture rapide. Les ordres de grandeur rapportés : environ 45 % du code généré analysé porte au moins une faille de sécurité, et une hausse d’environ +150 % de défauts de conception par rapport au code écrit à la main. Le problème n’est pas la quantité de bugs mais leur invisibilité : le code paraît correct.

3.2 Incidents documentés

Les incidents publics impliquant des agents autonomes partagent un schéma : un agent dispose d’un accès trop large et exécute une opération destructrice sans validation.

Suppression d’une base de production et de ses sauvegardes lors d’une migration mal configurée.
Suppression d’un volume de données sans confirmation, perte irréversible de données métier.
Sur certaines plateformes, un déplacement de fichiers qui échoue silencieusement et détruit les fichiers en cours de déplacement.

3.3 Quatre défaillances récurrentes

Défaillance	Symptôme	Section de la formation détaillant la parade
Faux-positif de test	Le test passe au vert mais ne vérifie rien de réel	8 (mutation, golden)
Duplication	L’agent recrée un composant qui existe déjà ailleurs	7 (contexte sémantique)
Dérive vis-à-vis de la spec	Le résultat ressemble à la demande ; cas limites et règles métier ignorés	6 (spec exécutable)
État de commit incohérent	L’agent veut committer alors que des tests cassent, en affirmant qu’ils passent	9 (garde-fous), 10 (juge)

3.4 Trois critères de validation

Toute la démarche se résume à répondre, de façon vérifiable, à trois questions distinctes. La plupart des outils ne répondent qu’à la première.

Est-ce que ça tourne ? Le code s’exécute, les tests passent, l’app démarre.
Est-ce conforme à la demande ? Le comportement correspond à la spécification, cas limites compris.
Est-ce le bon besoin ? La spécification elle-même répond au besoin métier réel.

4. Configuration et mémoire

Un agent oublie tout à la fermeture de la session. Pour qu’il travaille de façon cohérente d’une fois sur l’autre, on déporte les règles et le savoir-faire dans des fichiers. C’est le socle de toute la fiabilisation.

4.1 Hiérarchie de mémoire

Niveau	Durée de vie	Contenu
Contexte	Volatile (le tour courant)	Fichiers lus, conversation ; effacé par `/clear` ou `/compact`
Session	Le temps de la session	Historique reprenable avec `--resume`
Mémoire persistante	Durable	Fichiers Markdown (`CLAUDE.md`, skills), fichiers .md répertoriant l’historique des problèmes / issues rencontrées durant le projet

4.2 Structure du dossier `.claude/` et règles de précédence

Toute la configuration vit dans un dossier .claude/ à la racine du projet, complété par un CLAUDE.md de projet. On peut empiler des CLAUDE.md par sous-dossier pour spécialiser les règles.

mon-projet/
├── CLAUDE.md                 # règles projet (chargé à chaque session)
├── .claude/
│   ├── settings.json         # config d'équipe (versionnée)
│   ├── settings.local.json   # config perso (git-ignorée)
│   ├── skills/               # protocoles chargés à la demande
│   │   └── audit-securite/
│   │       └── SKILL.md
│   ├── rules/                # contraintes par chemin de fichier
│   ├── commands/             # commandes /personnalisées
│   ├── agents/               # sous-agents spécialisés
│   └── hooks/                # scripts déclenchés par événement
└── src/
    └── frontend/
        └── CLAUDE.md         # règles spécifiques à ce sous-dossier

Précédence (du plus général au plus spécifique, le plus spécifique l’emporte) : ~/.claude/CLAUDE.md (global, tous projets) → CLAUDE.md (racine projet) → CLAUDE.md des sous-dossiers traversés. Pour les settings.json : entreprise → local → projet → utilisateur.

4.3 `CLAUDE.md` : le fichier de règles projet

CLAUDE.md n’est pas un README (qui décrit le projet à un humain) : c’est un contrat qui dit à l’agent comment travailler. Il est injecté en tête de chaque session, donc il consomme du contexte — restez concis, privilégiez les règles « toujours / jamais » et un index « où vit quoi ».

# Projet — Règles permanentes

## Toujours
- Écrire un test en échec avant tout correctif.
- Passer par le design system (aucun composant natif).
- Messages d'erreur en français, conformes WCAG.

## Jamais
- Committer si un test échoue.
- Tracer un email ou un mot de passe dans les logs (RGPD).

## Où vit quoi (index)
- `*.sql`     → charge la rule rls-queries
- `frontend/` → conventions dans frontend/CLAUDE.md
- incident    → gabarit postmortem (skill recording-decisions)

4.4 `settings.json` et `settings.local.json`

settings.json porte la configuration partagée par l’équipe (versionnée). settings.local.json porte vos préférences personnelles et permissions (git-ignoré). Les permissions s’expriment en allow/deny par outil.

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(git status)", "Edit"],
    "deny": ["Bash(rm -rf*)", "Read(./.env)", "Read(./secrets/**)"]
  }
}

4.5 Skills

Un skill est un dossier contenant un SKILL.md : un protocole étape par étape, chargé uniquement quand il est pertinent. Le front-matter déclare quand il s’active — c’est ce qui évite de tout charger en permanence. Un skill peut embarquer des scripts, gabarits et données, et se composer avec d’autres skills.

---
name: audit-securite
description: Auditer TLS, secrets, authentification et en-têtes HTTP.
when: l'utilisateur demande un audit de sécurité, ou avant une mise en prod
version: 1.2.0
---

# Audit de sécurité — protocole

1. Scanner les secrets exposés (script ./scan-secrets.sh).
2. Vérifier les en-têtes HTTP de sécurité.
3. Contrôler l'isolation multi-tenant des requêtes.
4. Produire un rapport selon ./gabarit-rapport.md.

4.6 Rules

Une rule borne le comportement par chemin de fichier et reste toujours active dans son périmètre. Contrairement au skill (un protocole qu’on déroule), la rule est une contrainte permanente attachée à un type de fichier.

# .claude/rules/rls-queries.md
# Périmètre : **/*.sql, backend/**/repositories/*

Toute requête sur une table multi-tenant DOIT inclure le filtre
d'organisation. Une requête sans clause de scoping est interdite :
elle constitue une fuite de données entre clients.

4.7 Hooks

Un hook exécute un script déterministe sur un événement du cycle de session (2.3). C’est le levier pour automatiser sans dépendre du « bon vouloir » du modèle : formatage après édition, blocage de commandes dangereuses, filtrage de sortie pour économiser des tokens, injection de contexte (section 7).

// .claude/settings.json — formater automatiquement après chaque édition
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/format.sh" }
        ]
      }
    ]
  }
}

Cas d’usage 1 : Un hook PreToolUse sur l’entrée permet d’injecter du contexte via un outil comme code-review-graph pour pouvoir enrichir l’analyse avant l’exécution de Claude et lui éviter par exemple des commandes “grep” inutiles.

4.8 Commandes

Les commandes /... sont des actions invocables depuis la session. Quelques natives utiles, puis vos propres commandes versionnées dans .claude/commands/.

Commande	Rôle
`/plan`	Réfléchir à une tâche sans écrire de code (cadrage)
`/goal`	Répéter jusqu’à atteindre une condition (« tous les tests verts »)
`/loop`	Réexécuter une commande à intervalle régulier
`/monitor`	Surveiller un processus long jusqu’à sa fin

Une commande personnalisée est un simple fichier Markdown décrivant le déroulé ; elle devient /mon-geste.

# .claude/commands/commit.md
Crée un commit conventionnel pour les changements indexés.
Étapes :
1. Lancer la suite de tests ; abandonner si rouge.
2. Rédiger un message de commit conventionnel.
3. Committer (jamais de --no-verify).

4.9 Plugins et marketplace

Les plugins regroupent des skills, agents et hooks prêts à l’emploi, installables depuis une marketplace. Ils évitent de tout réécrire soi-même.

# Ajouter une marketplace puis installer un ensemble de capacités
/plugin marketplace add anthropics/skills
/plugin install superpowers

# Lister / retirer
/plugin list

5. Workflow en étapes

Demander une fonctionnalité entière en un seul prompt produit un gros diff impossible à relire et souvent à côté du besoin. La parade est de découper le travail en étapes, chacune produisant un livrable contrôlable.

5.1 Du prompt unique au pipeline en six étapes

On remplace « un prompt, et j’espère » par une chaîne de six maillons. L’intérêt : à l’étape de vérification, on peut répondre aux trois questions de la section 3.4.

Cadrer → Spécifier → Découper → Exécuter → Vérifier → Tracer
  │         │           │          │           │          │
  besoin   contrat    lots      code+tests   gates+juge  ADR/postmortem

5.2 Enchaînement des commandes

Concrètement, on matérialise chaque maillon par une commande personnalisée (section 4.8). Voici une chaîne de référence ; les noms sont les vôtres (et les skills/commands sont à définir vous même également), l’important est la séquence et les artefacts.

Commande	Maillon	Produit
`/brainstorming`	Cadrer	Intention explicite (interview du besoin)
`/specify`	Spécifier	Spécification Gherkin + NFR
`/split`	Découper	Lots livrables + graphe de dépendances
`/execute`	Exécuter	Code + tests (en worktree isolé)
`/check`	Vérifier	Verdict des gates + de l’agent juge
`/trace`	Tracer	ADR / postmortem / rapport de livraison

5.3 Artefacts produits à chaque étape

Chaque maillon laisse une trace écrite plutôt qu’un échange oral qui s’évapore. Un bon artefact est structuré (un format, pas de la prose), contrôlable (relisible et corrigeable), vérifiable (une gate peut le juger) et versionné (suivi dans git).

5.4 Cas feature vs cas bugfix

Le début de chaîne diffère selon la nature du travail ; le tronc commun reprend ensuite.

Feature : on explore le besoin par interview (/brainstorming) jusqu’à une intention explicite.
Bugfix : on impose de reproduire avant de corriger. Isoler le cas, écrire un test qui prouve le bug (rouge), corriger jusqu’au vert, puis évaluer l’impact du correctif sur le reste (blast radius).

5.5 Planification

Avant d’écrire, on planifie en lecture seule (mode plan, section 1.3). La sortie est un plan daté et versionné, découpé en tâches avec leurs dépendances — un graphe qui révèle ce qui peut s’exécuter en parallèle.

# plans/2026-06-27-regle-facturation.md

## T1 — schéma de la règle
## T2 — validations          (dépend de T1)
## T3 — tests                (dépend de T1)
## T4 — job CI               (dépend de T2, T3)

6. Spécifications exécutables

Une spécification floue garantit des allers-retours sans fin. Une spécification exécutable transforme les exigences en tests que la machine peut vérifier seule.

6.1 La spécification comme contrat

La spec joue le rôle d’un ticket prêt à développer : contexte, critères d’acceptation explicites, et exigences non-fonctionnelles. Elle est le contrat contre lequel l’agent juge (section 10) évaluera le travail.

6.2 Syntaxe Gherkin

Gherkin décrit un comportement en langage structuré (Étant donné / Quand / Alors). Chaque scénario devient un test exécutable, centralisé avec le code.

# specifications/inscription.feature
Fonctionnalité: Validation de l'email à l'inscription

  Scénario: Email valide
    Étant donné un formulaire d'inscription
    Quand je saisis "alice@exemple.fr"
    Alors le formulaire est accepté

  Scénario: Email sans domaine
    Étant donné un formulaire d'inscription
    Quand je saisis "alice@"
    Alors un message d'erreur accessible s'affiche

6.3 Exigences non-fonctionnelles (NFR)

Les NFR (performance, accessibilité, sécurité, internationalisation, design system) se déclarent en amont, sous forme vérifiable et bloquante. Exemple d’une exigence de performance exprimée en Gherkin puis traduite en budget mesurable.

# Exigence de performance — bloquante en CI
Étant donné un changement qui dégrade le FCP au-delà de 1,5 s
  ou le TBT au-delà de 100 ms
Quand le job lighthouse s'exécute
Alors le job échoue, métriques à l'appui

// lighthouserc.js
module.exports = {
  ci: { assert: { assertions: {
    'first-contentful-paint': ['error', { maxNumericValue: 1500 }],
    'total-blocking-time':    ['error', { maxNumericValue: 100 }]
  }}}
};

Le même principe s’applique aux autres domaines : accessibilité (« toute information portée par la couleur doit l’être aussi autrement » → règle axe), sécurité (scan de secrets bloquant), i18n (« zéro chaîne en dur » → échec si une traduction manque), design system (composant natif interdit).

6.4 Rédaction structurée des prompts

Structurer le prompt avec des balises et des ancres sémantiques réduit l’ambiguïté et améliore la conformité. On sépare explicitement contexte, tâche, contraintes et critères d’acceptation.

<contexte>
Module de facturation, backend Node, base PostgreSQL multi-tenant.
</contexte>
<tache>
Ajouter le calcul de la TVA par pays.
</tache>
<contraintes>
- Aucune requête sans filtre d'organisation.
- Arrondi au centime, demi vers le haut.
</contraintes>
<criteres_acceptation>
- Tests pour la France (20 %), l'Allemagne (19 %) et un cas exonéré (0 %).
</criteres_acceptation>

7. Contexte sémantique et contraintes statiques

Deux problèmes de la section 3 se règlent au moment où l’agent écrit le code : la duplication (il recrée ce qui existe car il ne le « voit » pas) et les écarts de structure. La parade : lui donner une vraie compréhension des relations du code, et contraindre la forme du code par des motifs.

7.1 Serveur de langage (LSP) via Serena

Un serveur de langage donne à l’agent la même vision qu’un IDE : aller à la définition d’un symbole, lister toutes ses références, lire les diagnostics du compilateur en direct. Cela évite de relire des fichiers entiers (économie de tokens) et de détecter les erreurs sans relancer le build. On l’expose via un MCP comme Serena. A noter que Claude inclut déjà des LSP (plugins Claude) mais ceux-ci ne couvrent pas correctement tous les langages.

// .mcp.json — exposer un serveur de langage à l'agent
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena",
               "serena", "start-mcp-server"]
    }
  }
}

L’agent dispose alors d’outils de type go_to_definition et find_references : il connaît les relations du code avant de créer, ce qui réduit la duplication.

7.2 Pourquoi le `grep` natif est insuffisant

La recherche textuelle (grep) trouve des chaînes, pas des relations. Chercher CheckItem remonte des occurrences, mais pas qui l’importe, qui l’appelle, quelles fonctions en dépendent, ni quel composant équivalent existe déjà sous un autre nom. L’agent qui ne dispose que du grep reconstruit ce qu’il ne retrouve pas d’où la duplication.

7.3 Code Review Graph : moteur de contexte sémantique

Un moteur de contexte à base de graphe sémantique indexe la base de code en un graphe de symboles, références et dépendances. À partir d’un changement ou d’une intention, il répond à « quels fichiers sont réellement pertinents ici », bien mieux qu’une recherche par mots-clés.

7.4 Injection de contexte par hook `PreToolUse`

Le problème classique des outils MCP : ils sont proposés à l’agent, qui doit décider de les appeler — et en pratique il retombe vite sur le grep. La solution : ne pas exposer un outil, mais brancher un hook qui intercepte le prompt, interroge le graphe et injecte directement les bons fichiers dans le contexte avant que le modèle ne réfléchisse. Le modèle n’a plus rien à choisir : le contexte est déjà là, et le grep devient inutile (et peut être rationné par ailleurs).

// .claude/settings.json — injecter le contexte du graphe à chaque prompt
{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [
        { "type": "command",
          "command": ".claude/hooks/inject-graph-context.sh" }
      ]}
    ]
  }
}

# .claude/hooks/inject-graph-context.sh
# Interroge le graphe sémantique et renvoie les fichiers pertinents,
# qui seront ajoutés au contexte (additionalContext) avant le raisonnement.
PROMPT="$(cat)"
code-review-graph related --query "$PROMPT" --top 8 --format paths

7.5 Contraintes par motif AST (ast-grep)

L’AST (arbre syntaxique) représente le code comme une structure, pas comme du texte. ast-grep permet d’interdire ou d’imposer des motifs structurels, surfacés comme des diagnostics dans l’éditeur et bloquants en CI.

# Interdire les tests focalisés (.only) — ast-grep
id: no-focused-test
language: typescript
rule:
  any:
    - pattern: it.only($)
    - pattern: describe.only($)
    - pattern: test.only($)
message: "Test focalisé interdit : il masque les autres tests."
severity: error

Autres usages typiques : interdire la suppression de colonne dans une migration (DROP COLUMN), imposer un feature flag à toute nouvelle page, interdire d’ouvrir une transaction sans contexte de sécurité, faire respecter les frontières d’architecture.

7.6 Duplication, code mort, i18n et recherche exacte

En complément, des contrôles statiques attrapent ce que l’agent laisse passer : détection de duplication (un composant équivalent existe déjà), suppression du code mort, refus des chaînes non internationalisées (texte en dur). Pour les recherches précises et ciblées, ripgrep (rg) reste l’outil exact à privilégier sur le grep générique.

8. Stratégie de test

Le faux-positif de test (section 3.3) est la défaillance la plus dangereuse : un test vert qui ne vérifie rien donne une fausse confiance, pire que pas de test. Cette section cible spécifiquement ce risque.

8.1 TDD : test en échec avant correction

On écrit d’abord un test qui échoue (rouge), prouvant que le comportement attendu n’est pas encore là, puis on code jusqu’au vert. Pour un bug, le test rouge reproduit le défaut ; pour une feature, il encode le critère d’acceptation.

1. RED    — écrire un test qui échoue (le comportement n'existe pas)
2. GREEN  — écrire le minimum de code pour le faire passer
3. REFACTOR — nettoyer sans casser le test

8.2 Jeux de données de référence (golden datasets)

Pour les sorties complexes (rapports, transformations, rendus), on fige une sortie de référence validée. Tout écart futur fait échouer le test : c’est une non-régression sur le résultat exact, et la référence est protégée contre toute modification non intentionnelle.

8.3 Détection de tests instables (flaky)

Un test qui passe une fois ne prouve rien s’il dépend du temps ou d’un ordre non déterministe. On relance les tests de nombreuses fois (la nuit) pour détecter ceux qui alternent vert/rouge, et on ouvre un ticket automatiquement au-delà d’un seuil.

# Relancer la suite N fois et repérer les alternances (exemple)
for i in $(seq 1 50); do npm test -- --reporter=dot || echo "ÉCHEC run $i"; done

8.4 Tests de mutation

Le test de mutation répond directement au faux-vert : on introduit volontairement des modifications dans le code (mutants) ; si un test reste vert malgré la mutation, c’est qu’il ne protège rien. On exécute généralement ces tests la nuit (coûteux).

# Tests de mutation (nightly) — exemple Stryker (JS/TS)
npx stryker run
# Mutant survivant = test qui ne détecte pas le changement -> à renforcer

8.5 Pattern Page Object et choix du niveau de test

Pour l’E2E (navigateur piloté par l’agent), on sépare la description de la page (sélecteurs) de la logique de test via le pattern Page Object — sans quoi la suite devient inmaintenable. La pile de test est un logiciel à part entière, soumise aux mêmes exigences d’ingénierie que l’application.

9. Permissions, environnements et garde-fous

Les incidents de la section 3.2 viennent tous d’un excès de droits. On borne donc explicitement ce que l’agent peut faire, où, et jusqu’où.

9.1 Matrice de droits par environnement

La règle structurante : pouvoir total en développement (jetable), droits sous condition en pré-production, lecture seule en production.

Action	Dev	Staging	Prod
Écrire & itérer	✓ libre	✓ via PR	✗
Exécuter des commandes	✓	sous gate	✗
Déployer	✓ auto	validation humaine	✗ jamais
Toucher aux données	✓ jetable	✗	✗
Lire signaux & logs	✓	✓	✓

9.2 Permissions et allowlist d’outils

Les permissions s’expriment par outil dans settings.json (4.4). On limite chaque agent au strict nécessaire (allowlist) et on refuse explicitement le dangereux.

{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(git*)", "Edit", "Read"],
    "deny":  ["Bash(rm -rf*)", "Bash(git push --force*)",
              "Read(./.env)", "Read(./secrets/**)"]
  }
}

9.3 Accès aux données de production sécurisé via un MCP custom

C’est une technique pour donner un accès à la prod en toute sécurité : on place un serveur MCP au milieu. L’agent appelle l’outil sans détenir aucun credential ; le MCP détient les accès côté serveur, interroge la source (logs, métriques) et ne renvoie que de la donnée filtrée.

Agent  →  MCP  →  API logs/metrics  →  Prod
(0 credential)   (détient les accès, filtre la donnée)

↩ ne remontent que les données filtrées ; les secrets restent côté serveur.

9.4 Worktrees git et isolation des agents

Pour exécuter plusieurs tâches en parallèle sans que les agents se marchent dessus, on donne à chacun un worktree git : un répertoire de travail dédié, une branche par tâche. On peut même demande à Claude de les gérer en autonomie bien sûr !

# Un worktree isolé par ticket
git worktree add ../projet-ticket-265 -b ticket-265
# ... l'agent travaille dans sa "chambre" ...
git worktree remove ../projet-ticket-265   # nettoyage après merge

9.5 Limites d’exécution

On plafonne les ressources pour éviter l’emballement : nombre de MR simultanées (au-delà, les conflits explosent), nombre de worktrees (espace disque, compilation), scan de secrets avant tout push.

# .claude/hooks/limite-worktrees.sh — refuser au-delà de 6 worktrees
COUNT=$(git worktree list | wc -l)
if [ "$COUNT" -ge 7 ]; then
  echo "Limite de worktrees atteinte (6)." >&2
  exit 2   # bloque l'action et réengage l'agent
fi

9.6 Pipeline CI multi-étapes

La CI prolonge les gates locales : tout est bloquant (sauf les jobs nocturnes). Un découpage typique en étapes successives, du local au runtime.

Étape	Contrôles
Pre-commit (local)	format, lint, tests rapides
Sécurité (CI)	secrets, motifs interdits, vulnérabilités des dépendances, scan d’image
Migrations	aucun changement destructeur, rétro-compatibilité
Front	performance, accessibilité, poids du bundle, régression visuelle, i18n
Build & deploy	image, déploiement, test de fumée
Nightly	détection de flaky, tests de mutation

9.7 Optimisation des coûts

Trois leviers simples réduisent la facture en tokens sans perte de qualité : router les tâches de lecture/balayage vers Haiku, compacter le contexte aux bons moments, et marquer les portions stables du prompt pour le cache.

# Lecture massive / synthèse : modèle économique
/model haiku
# Compacter dès qu'une sous-tâche est finie
/compact

10. Revue automatisée et traçabilité

Une fois le code produit et testé, on le fait relire par la machine d’abord, par un humain en dernier ressort et on trace les décisions pour ne pas répéter les mêmes erreurs.

10.1 Agent juge indépendant

On rassemble l’implémentation et la spécification, et un agent juge tranche. Ce juge est indépendant : il ne voit que le Gherkin (ce qui était demandé) et le code modifié, et rend un verdict binaire. Il vérifie que le test fonctionnel correspond à la spec, qu’il tourne et qu’il couvre les critères.

Entrée : spec Gherkin + diff du code
Sortie : VALIDATED  (conforme à chaque critère)
         FAILED     (+ critères manquants ou non couverts)

10.2 Revue de code automatisée et revue humaine finale

Un second agent, sur un modèle plus capable, relit le fond comme le ferait un relecteur humain. En local, une commande de revue renforcée (/ultrareview) dégrossit le fond avant la CI. Mais le dernier mot reste humain.

10.3 ADR : décisions d’architecture (dans des fichiers .md)

Un ADR (Architecture Decision Record) trace les décisions dans un fichier .md : contexte, le choix retenu, ses conséquences. Il devient la mémoire durable de l’agent sur les choix structurants, à relire et rechallenger régulièrement.

# ADR 0042 — Isolation multi-tenant par Row-Level Security
Date : 2026-06-27
Statut : accepté

## Contexte
Plusieurs organisations partagent la même base ; une requête sans
filtre a déjà provoqué une fuite inter-tenant.

## Décision
Activer la RLS au niveau base ; tout accès passe par un contexte
d'organisation explicite.

## Conséquences
+ Fuite inter-tenant structurellement impossible.
− Toute requête doit fournir le contexte ; surcoût léger.

10.4 Postmortems (fichiers .md aussi) et seuils de récidive

Les postmortem retracent un incident : cause racine, correctif, actions de suivi, dette assumée. On ne l’attend pas indéfiniment : on le déclenche par seuils, pour transformer un problème répété en amélioration de méthode.

Récurrence	Action
1 à 2 correctifs	rien de particulier
≥ 3 correctifs sur le même sujet	postmortem déclenché
≥ 5 correctifs	analyse de cause racine obligatoire
3+ postmortems sur le même thème	méta-postmortem : on juge la méthode, pas le bug

10.5 Rapports de livraison (MR)

Le rapport de livraison (Merge Request) résume ce qui a été fait, le périmètre préservé et le plan de test coché. Au format constant, il sert ensuite à corréler un déploiement à une investigation (section 11).

## Résumé
Unifie le widget Checks via le composant partagé CheckItem.

## Périmètre préservé
Le groupement existant est conservé ; seul le rendu des items change.

## Plan de test
- [x] tests unitaires
- [x] E2E (parcours principal)
- [ ] revue visuelle (humaine)

11. Exécution non-interactive et orchestration

Une fois les garde-fous en place, on peut augmenter l’autonomie : déclencher l’agent sans frappe au clavier, puis l’inscrire dans un workflow déterministe qui le pilote.

11.1 Mode headless et déclenchement par événement

Le mode claude -p (2.4) exécute une passe sans humain. En le branchant sur un événement, ce n’est plus vous qui appuyez sur Entrée, c’est l’événement qui le fait.

# Déclenché par un événement plutôt qu'au clavier
claude -p "corrige le ticket #412 puis ouvre une MR" --output-format stream-json

# Déclencheurs typiques :
#   - hook PostToolUse -> écrit une métrique
#   - cron toutes les 5 min -> dépile le backlog
#   - webhook CI -> relance une investigation

11.2 Workflow déterministe pilotant l’agent

Deux façons d’assembler agent et workflow. Mettre le workflow dans l’agent (tout le protocole dans des skills) rend l’ordre fragile : l’agent compacte, perd la mémoire et dérive. L’inverse est plus robuste : c’est le workflow qui appelle l’agent, un pas à la fois. Le code déterministe tient la chaîne ; l’agent ne fait qu’une étape.

11.3 Daemon : cycle autonome et garde-fous

Un daemon dépile le backlog en continu et fait tourner, pour chaque ticket, un cycle court. Les garde-fous bornent l’autonomie ; le merge reste un geste humain.

// Cycle autonome (run.ts), piloté par le daemon
preflight   → tout doit être vert au départ
plan        → fixer le périmètre
execute     → un pas d'implémentation
review      → juge LLM ; si rouge, on reprend, jamais de merge auto

// Garde-fous : max 2 agents simultanés ; 3 échecs sur une tâche = pause ;
// le merge est déclenché par l'humain, pas par le daemon.

11.4 Dépilage de backlog en parallèle

Une commande d’orchestration (par ex. /autopilot) prend les tickets prêts à développer, en délègue plusieurs en parallèle (un worktree par ticket, section 9.4), puis vous laisse relire les MR. La délégation est explicite et plafonnée, pas « un agent qui appelle tout le monde ».

11.5 Boucle d’amélioration

L’agent fait partie du système qu’il entretient : on le monitore lui aussi (chaque appel d’outil, chaque échec). Une analyse régulière distingue le travail utile de la friction = toil (gestes répétitifs sans valeur, même scriptés) + retries (relancer une étape en espérant qu’elle passe). Ce qui revient souvent devient un script ou une règle.

Signal mesuré en continu	Objectif
Temps de détection d’un bug en prod	diminuer
Taux de régression par livraison	diminuer
Part de correctifs proposés automatiquement	augmenter
Friction (toil + retries) par semaine	diminuer

11.6 Reprise d’une base de code existante (legacy)

Sur une base déjà « vibe-codée » depuis des mois, on procède comme pour tout legacy, par paliers — on n’accélère jamais une zone non sécurisée.

Comprendre : cartographier les zones chaudes et le besoin métier réel.
Sécuriser : poser des tests de caractérisation (vert d’abord).
Découper : isoler une couture, pas de big-bang.
Verrouiller : gates (lint, tests, revue) ; le rouge bloque.
Accélérer : augmenter l’autonomie sur la zone désormais sécurisée.

12. Référence

12.1 Tableau des commandes

Commande	Effet
`/plan`	Cadrer une tâche sans écrire de code
`/goal`	Itérer jusqu’à une condition
`/loop`	Réexécuter périodiquement
`/monitor`	Surveiller un processus long
`/context`	Inspecter l’occupation du contexte
`/compact`	Compacter la conversation
`/rewind`	Revenir à un point de restauration
`/model`	Changer de modèle
`/plugin`	Gérer les plugins

12.2 Raccourcis clavier

Raccourci	Effet
`Shift+Tab`	Cycler les modes de permission
`Échap`	Interrompre l’action en cours
`Échap Échap`	Ouvrir l’historique / revenir en arrière
`@`	Référencer un fichier
`/`	Invoquer une commande
`#`	Ajouter une note à la mémoire (CLAUDE.md)

12.3 Dépannage

Symptôme	Cause probable	Action
Réponses qui dérivent	Contexte saturé	`/compact` ou redémarrer la session
Un skill ne se déclenche pas	`when:` / description trop vague	Préciser la condition d’activation
L’agent relit un fichier en boucle	Doc périmée en mémoire	Mettre à jour le fichier source et le `CLAUDE.md`
Trop de demandes de permission	Mode trop strict	Ajuster allow/deny ou passer en `auto`
Coût élevé	Gros modèle, contexte lourd	Router vers Haiku, `/compact`, cache

12.4 Checklist quotidienne et calibration de la confiance

Démarrer en mode plan pour cadrer ; ne coder qu’après validation du plan.
Relire chaque diff ; ne jamais accepter à l’aveugle.
Un test rouge avant tout correctif ; aucun commit en faux-vert.
Surveiller le contexte ; compacter aux transitions de sous-tâche.
Réserver la revue humaine obligatoire aux zones sensibles (SQL multi-tenant, données).
Tracer décisions (ADR) et incidents (postmortem) au fil de l’eau.

Calibration de la confiance : plus le périmètre est risqué (données, multi-tenant, prod), plus la vérification doit être humaine et systématique. Plus il est jetable (worktree de dev), plus on peut déléguer. La confiance se règle par zone, pas globalement.

12.5 Récapitulatif de la configuration type

Couche	Rôle	Exemples
MCP installés	Capacités branchées une fois	Serena (LSP), navigateur piloté, accès logs/métriques
Skills	Protocoles chargés à la demande	brainstorming, debugging, test, audit-*
Rules	Contraintes par fichier, toujours actives	commits, code minimal, logs sûrs, rls-queries
Hooks	Automatisations déterministes	format, scan secrets, injection de contexte
Le moteur	Raccourcis déterministes (du code)	daemon, dispatch de tickets, worktrees, métriques