Labs pratiques

Lab 1 — Équiper un codebase existant

Durée : 45-60 min · Niveau : tous · Prérequis : un vrai projet, si possible un que tu connais mal · Livrable : un fichier de contexte qui tient, un filet de tests sur une zone, et une session mesurée

C'est le lab à faire en premier, et de préférence sur ton projet le moins reluisant. Les six autres partent d'un environnement propre ; celui-ci construit l'environnement. Il applique le Module 4 (archéologie et filet) et le Module 5 (contexte), et tout le reste devient plus facile ensuite.

Étape 1 — Une session entièrement en lecture

Aucune écriture pendant toute cette étape. On ferme la porte plutôt que de compter sur sa bonne volonté — chez Claude Code, le plan mode ; ailleurs, l'équivalent de ton outil, ou une branche jetable (Module 4 §2) :

claude --permission-mode plan

Le point 5 est celui qu'on lit en premier. Le point 2 est celui qui va directement dans le fichier de contexte : ce sont les commandes qu'aucun agent ne peut deviner.

Étape 2 — Extraire les conventions plutôt que les inventer

Puis c'est ton tour, et cette partie ne se délègue pas. Tu tries en trois catégories : ce qu'on impose, ce qu'on tolère sans l'étendre, ce qu'on interdit désormais. La deuxième catégorie est celle qui empêchera l'agent de « nettoyer » l'ancien code à chaque passage (Module 4 §5).

Étape 3 — Écrire le fichier, et vérifier qu'il est chargé

Écris ton AGENTS.md (le Starter Pack donne le squelette), puis le CLAUDE.md d'une ligne qui l'importe :

@AGENTS.md

Et surtout, vérifie. C'est l'étape que tout le monde saute et c'est celle qui échoue en silence :

/context

Ton fichier doit apparaître sous Memory files. S'il n'y est pas, tout ce que tu viens d'écrire ne sert à rien, et aucun message d'erreur ne te le dira. Sur un autre outil, cherche son équivalent : ce qui compte est d'avoir une preuve que le fichier est chargé, jamais une supposition.

Étape 4 — Poser un filet sur une zone, une seule

Choisis la fonction que tu vas devoir modifier bientôt, celle qui te fait peur. Pas le module entier.

Puis casse le code exprès. Change un > en >=, relance la suite. Si tout reste vert, tes tests n'observent rien : reprends-les. Ce contrôle prend deux minutes et c'est lui qui décide si le filet en est un.

Étape 5 — Mesurer ce que ça coûte

/context    → combien ton contexte permanent occupe réellement
/usage      → ce que la session a consommé

Ton contexte permanent doit rester sous 5 % de la fenêtre (Module 5 §9). Au-delà, tu n'élagues pas des règles utiles : tu sors les règles spécialisées vers .claude/rules/ avec un champ paths.

Ce que tu dois avoir à la fin

Lab 2 — NestJS : API REST avec Auth JWT

Durée : 45-60 min · Niveau : intermédiaire · Prérequis : NestJS installé, Module 3 lu · Livrable : module auth avec tests E2E

Setup du contexte

<!-- CLAUDE.md pour ce lab -->
# Lab NestJS Auth

## Stack
- NestJS 10, TypeScript 5.x, TypeORM + PostgreSQL 15
- @nestjs/jwt + Passport, class-validator
- Tests : Jest + Supertest

## Conventions
- Architecture : Module / Controller / Service / Repository
- DTOs typés (jamais d'entité retournée directement)
- Erreurs : HttpException avec messages clairs
- IMPORTANT: bcrypt cost ≥ 12, jamais de mot de passe en clair après hash

Phase EXPLORE

Phase PLAN

Phase CODE

Phase VERIFY

Lab 3 — Next.js : Refactoring avec Context Engineering

Durée : 30-45 min · Niveau : intermédiaire · Prérequis : projet Next.js existant, Module 5 lu · Livrable : composant migré Class → Functional + hooks, tests verts

Setup CLAUDE.md

# Lab Next.js Refactoring

## Stack
- Next.js 15 (App Router), TypeScript 5.x, React 19
- Tailwind CSS
- Tests : Vitest + React Testing Library
- State : Zustand (pas de Redux)

## Conventions composants
- Functional components uniquement
- Props typées par interface : interface ButtonProps {}
- Export named uniquement (pas de default export pour les composants)
- Fichiers : ComponentName.tsx + ComponentName.test.tsx dans le même dossier

## Anti-patterns à éviter
- Pas de useEffect pour fetch (Server Components ou React Query)
- Pas de prop drilling > 2 niveaux (utiliser Zustand)
- Pas d'inline styles (Tailwind uniquement)

Workflow de refactoring

Lab 4 — Laravel : Migration et Soft Delete

Durée : 30-45 min · Niveau : intermédiaire · Prérequis : Laravel 11+ installé, Module 3 lu · Livrable : migration deleted_at, modèle SoftDeletes, tests Pest verts

# CLAUDE.md Laravel

## Stack
- Laravel 11+, PHP 8.3+
- Eloquent ORM + MySQL 8
- Tests : Pest (pas PHPUnit)
- API Resources pour les réponses

## Conventions
- Repository Pattern (interface + implémentation)
- Form Requests pour la validation
- API Resources pour la transformation
- Soft deletes via le trait SoftDeletes d'Eloquent

## Commandes
php artisan serve      # Dev
php artisan test       # Tests (Pest)
php artisan migrate    # Migrations
./vendor/bin/pint      # Linter

Lab : Implémenter le soft delete sur User

Lab 5 — DevOps : Pipeline CI/CD avec revue IA

Durée : 45-60 min · Niveau : intermédiaire · Prérequis : projet sur GitHub, Module 6 §7 lu · Livrable : workflow .github/workflows/ai-review.yml avec 3 jobs (quality, ai-security-review, changelog)

Lab 6 — Python / FastAPI : endpoint async avec SQLAlchemy 2.x

Durée : 45-60 min · Niveau : intermédiaire · Prérequis : projet FastAPI, Module 3 lu · Livrable : endpoint POST /articles async + tests pytest verts

Stack : Python 3.12+, FastAPI 0.115+, SQLAlchemy 2.x async, Pydantic v2

Setup du contexte

# CLAUDE.md (extrait spécifique au lab)

## Stack
- Python 3.12+, FastAPI 0.115+
- SQLAlchemy 2.x **async** uniquement (pas de Session synchrone)
- Pydantic v2 pour les schémas
- pytest + pytest-asyncio + httpx pour les tests

## Conventions
- Fichiers par feature : `app/<feature>/{router,schemas,models,service}.py`
- Routes ne contiennent JAMAIS de logique métier — tout passe par `service.py`
- Dépendances FastAPI : injection via `Depends()`, jamais de globals
- Async partout : pas de `requests`, utiliser `httpx.AsyncClient`

## Tests
- Base de test isolée par test (SQLite async via aiosqlite, ou Postgres jetable)
- Fixtures dans `conftest.py`, factory-boy pour les seeds
- Marker `@pytest.mark.asyncio` sur les tests async

## Anti-patterns
IMPORTANT: SQLAlchemy 2.x style uniquement (`Mapped`, `mapped_column`, `select().where()`) — pas de raw SQL ni de syntaxe v1.

Phase EXPLORE

Phase PLAN

Phase CODE

Phase VERIFY

Lab 7 — Production Incident Response avec Sentry MCP

Durée : 30-45 min · Niveau : senior · Prérequis : projet en prod connecté à Sentry, MCP Sentry configuré · Livrable : PR avec fix, test de non-régression et garde-fou versionné

Utiliser Claude Code en mode incident commander : récupérer les infos Sentry, formuler une hypothèse, la valider, proposer un fix minimal, documenter.

Setup MCP

Sentry propose un serveur MCP hébergé (OAuth, sans token local à gérer). C'est la voie à privilégier ; vérifie l'URL courante sur la doc Sentry avant de te rabattre sur une install locale.

# Portée project : le serveur atterrit dans .mcp.json, versionné avec le repo
claude mcp add --transport http --scope project sentry <url-mcp-sentry>

# Vérifie que la connexion est bien établie avant de commencer le lab
claude mcp list

Si tu dois passer par un serveur local en stdio, le .mcp.json produit ressemble à ça :

// .mcp.json (racine du projet, pas .claude/settings.json)
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
        "SENTRY_ORG": "my-org",
        "SENTRY_PROJECT": "api"
      }
    }
  }
}

Phase 1 — Capture

Phase 2 — Triage

Phase 3 — Fix

Phase 4 — Empêcher la récidive

C'est la question du Module 8 §4, appliquée pour de vrai : est-ce que l'agent va me le refaire ?

Ressources complémentaires

Templates à reprendre

Le Starter Pack du guide est sur la page dédiée /templates : un fichier de contexte (AGENTS.md) qui marche pour tous les outils, une configuration Claude Code avec des permissions sécurisées par défaut, un hook qui bloque l'écriture de fichiers contenant des secrets, et trois slash commands (/audit-security, /test-gen, /release-notes). Tout est aligné avec les modules 3, 5, 6 et 9.

Pour le reste (Skills spécialisés, serveurs MCP, agents prêts à l'emploi), le catalogue de référence est aitmpl.com, un catalogue communautaire de composants pour Claude Code. La page Templates signale ceux qu'on recommande spécifiquement.