Module 16 — Projet : la boîte à outils Claude Code complète de l'équipe Kiosque

Ce module ferme le cours en assemblant les pièces vues aux modules 3, 6, 7, 9, 10, 11, 12 et 14 autour d'un projet unique : la boîte à outils Kiosque. Cinq développeurs partagent une application FastAPI/React (« Kiosque », lecteur RSS d'entreprise). Objectif : configurer le dépôt pour que chaque poste, chaque cron et chaque PR utilisent Claude Code de la même façon, avec les mêmes garde-fous et le même coût prévisible. À la fin, un nouveau collaborateur qui clone Kiosque et tape /nouveau-endpoint reçoit du bon travail sans discuter avec ses collègues.

L'arbre final du dépôt Kiosque

kiosque/
├── .claude/
│   ├── settings.json                 # allow/deny et plugins activés
│   ├── settings.local.json           # (.gitignore) préférences perso
│   ├── agents/{revieweur,testeur}.md
│   ├── commands/                     # /commit /revue /nouveau-endpoint
│   │                                 # /tests-cibles /doc-api /notes-de-version
│   ├── claude-security-guidance.md   # règles maison
│   └── security-patterns.yaml        # motifs projet interdits
├── .github/workflows/claude.yml      # anthropics/claude-code-action@v1
├── .mcp.json                         # serveurs MCP github et postgres
├── backend/                          # FastAPI + SQLAlchemy + Alembic
├── frontend/                         # Vite + React + TanStack Query
├── plugins/kiosque-tools/            # plugin local, versionné
├── CLAUDE.md                         # conventions, < 200 lignes
├── Makefile                          # cibles test, lint, run, migrate
└── README.md

Cinq invariants : settings.json versionné vaut pour tout le monde ; settings.local.json est personnel, ignoré par git ; les skills projet vivent sous .claude/commands/, celles réutilisables ailleurs sous plugins/kiosque-tools/ ; deux sous-agents et pas dix (rôle clair, prompt court) ; le Makefile est le contrat entre humains et Claude — chaque skill l'appelle au lieu d'inventer sa propre commande.

Étape 1 — Poser les invariants d'équipe

Dans un shell fraîchement cloné : git checkout -b claude-boite-a-outils puis mkdir -p .claude/{agents,commands} plugins/kiosque-tools/{commands,skills}. Vérification : ls .claude/ retourne agents commands.

Rédigez ensuite .claude/settings.json — c'est le fichier qui gouverne l'ensemble :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(make test)",
      "Bash(make lint)",
      "Bash(make run)",
      "Bash(make migrate)",
      "Bash(ruff *)",
      "Bash(pytest *)",
      "Bash(npm test)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  },
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true,
    "kiosque-tools@local": true
  }
}

Vérification : lancez claude dans le dossier, tapez /status et confirmez que la ligne Setting sources mentionne Project ; tapez /permissions pour visualiser les listes fusionnées.

Étape 2 — Écrire le CLAUDE.md

Ouvrez CLAUDE.md à la racine. Contenu sous 200 lignes, cinq sections : Structure (backend FastAPI, frontend React, migrations Alembic dans backend/migrations/) ; Cible de tests (make test lance pytest puis npm test ; PR sans tests verts refusée par le workflow) ; Style (ruff backend, prettier frontend, aucun print livré) ; Migrations (jamais modifier une migration appliquée ; toujours une nouvelle révision) ; Où trouver quoi (docstrings dans backend/app/routes/*.py, styles dans frontend/src/styles/).

Vérification : /context doit signaler que CLAUDE.md projet pèse environ 1 800 jetons — au-dessus, réduire.

Étape 3 — Les six skills projet

Chaque skill vit sous .claude/commands/<nom>.md avec frontmatter minimal (description, éventuellement allowed-tools) :

• /commit : message conventionnel à partir du git diff --staged, propose de commiter, ne pousse pas. allowed-tools: [Bash(git *)].
• /revue : invoque revieweur sur le diff versus origin/main, affiche les trouvailles.
• /nouveau-endpoint : deux arguments (méthode, chemin), génère route FastAPI, schéma Pydantic, migration Alembic si un modèle est touché, test pytest, stub React. Chaque étape appelle make test avant de continuer.
• /tests-cibles : calcule la liste minimale à partir du diff, lance pytest -k "<expr>" puis npm test -- --changed.
• /doc-api : régénère la doc OpenAPI et met à jour docs/api.md.
• /notes-de-version : reprend le script Python du module 14, aussi appelé depuis un cron.

Vérification : / sans rien liste les six commandes ; /nouveau-endpoint POST /articles/{id}/lu produit route + test + migration cohérents en un tour, le tour se termine par un make test vert.

Étape 4 — Les deux sous-agents

Deux fichiers courts, deux rôles.

.claude/agents/revieweur.md — frontmatter skills: [Read, Grep, Bash], model: claude-sonnet-5. Corps : « Tu revois un diff FastAPI + React. Signale régressions, oubli de tests, fuites de secrets, migrations dangereuses. Utilise git diff origin/main...HEAD. N'écris pas dans les fichiers. Termine par un verdict bloquant | à corriger | acceptable. »

.claude/agents/testeur.md — frontmatter skills: [Bash, Read], model: claude-sonnet-5. Corps : « Tu lances make test (ou une sélection pytest -k) et rapportes les échecs avec fichier et ligne. Aucune modification de code. Résumé de deux lignes par échec. »

Vérification : /agents liste les deux sous-agents. /revue doit invoquer revieweur (visible dans la trace).

Étape 5 — Les hooks

Trois hooks dans .claude/settings.json, sous une clé hooks, tous en "type": "command" : PostToolUse ruff avec matcher: "Edit|Write" et command: "make lint 2>/dev/null || true" (linter après chaque écriture, sortie ignorée en cas d'échec, le lint est indicatif) ; PreToolUse protection migrations/.env avec le même matcher, command: ".claude/hooks/protege-sensible.sh" — un script court qui refuse (code 2) toute écriture sur backend/migrations/*.py déjà commis ou sur .env* ; Stop make test sans matcher, command: "make test", la suite tourne à chaque fin de tour et un échec ré-injecte le résultat dans la conversation.

Vérification : demandez à Claude d'écrire dans .env ; le hook doit répondre refusé : fichier sensible protégé. Modifiez une route et laissez le tour se terminer : make test apparaît dans la trace.

Étape 6 — Les serveurs MCP

.mcp.json à la racine, versionné, déclare deux serveurs stdio : github (via @modelcontextprotocol/server-github) pour ouvrir des PR, lister les issues et commenter ; postgres (via @modelcontextprotocol/server-postgres, URL en utilisateur lecture seule) pour inspecter le schéma. Les définitions restent différées par tool search — Claude ne les charge que quand nécessaire.

Vérification : /mcp affiche deux serveurs connectés. /context all doit indiquer une charge MCP proche de zéro tant qu'aucun outil n'a été appelé.

Étape 7 — Le plugin kiosque-tools

plugins/kiosque-tools/plugin.json déclare un plugin local : name, version, description, listes commands et skills pointant vers les sous-dossiers. Il embarque une variante de /notes-de-version réutilisable sur un autre dépôt maison et une skill changelog-hebdo qui condense la semaine de commits. Activation via enabledPlugins dans .claude/settings.json, déjà en place.

Vérification : /plugin list mentionne kiosque-tools@local avec statut enabled. Les commandes du plugin apparaissent dans la palette avec préfixe kiosque-tools:.

Étape 8 — Le workflow GitHub Actions

.github/workflows/claude.yml reprend le squelette du module 14 : déclencheurs issue_comment et pull_request_review_comment (types [created]), garde if: contains(github.event.comment.body, '@claude'), permissions minimales (contents: write, pull-requests: write, issues: write, id-token: write, actions: read), actions/checkout@v6 avec fetch-depth: 1, puis anthropics/claude-code-action@v1 avec anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} et claude_args: --max-turns 8 --model claude-sonnet-5 --allowedTools "Bash(make test),Bash(make lint),Read,Edit".

Vérification : ouvrez une PR, commentez @claude regarde ce diff et corrige les problèmes de lint ; le workflow se déclenche, un commit est poussé sur la branche, make test reste vert.

Scénario de démonstration en dix minutes

Rythme éprouvé pour montrer la boîte à outils à un nouveau collègue.

• 0 - 1 min — Clone du dépôt, claude lancé à la racine. /status confirme settings partagés, plugins actifs, deux serveurs MCP connectés.
• 1 - 3 min — /nouveau-endpoint POST /articles/{id}/lu. Claude génère route, schéma, migration, test. Le hook Stop lance make test : vert.
• 3 - 5 min — Demandez « affiche-moi le contenu de .env ». La règle deny refuse, la trace le montre.
• 5 - 6 min — /revue : le sous-agent revieweur cite deux points mineurs, verdict acceptable.
• 6 - 7 min — /commit produit un message conventionnel, staged, prêt à pousser.
• 7 - 9 min — Poussez la branche, ouvrez la PR, commentez @claude vérifie qu'il n'y a pas de régression. Le workflow se déclenche, Claude commente sur la PR.
• 9 - 10 min — /usage : coût de la démo autour de 0,25 EUR, Prompt cache (main) à 90 % de lecture.

Grille d'évaluation

Vingt points sur cinq axes.

Axe	Critère	Points
Configuration partagée	.claude/settings.json versionné, permissions.allow/deny cohérents, enabledPlugins justes	4
Skills et sous-agents	Les six skills existent, les deux sous-agents ont un rôle clair et court, /nouveau-endpoint produit route + test + migration	4
Hooks	PostToolUse ruff, PreToolUse protection .env/migrations, Stop make test en place et déclenchés	3
MCP et plugin	.mcp.json versionné avec github et postgres, plugin kiosque-tools actif et testé	3
Workflow CI	claude.yml déclenché sur @claude, permissions minimales, --allowedTools limitatif, PR de démo verte	3
Coûts et hygiène	CLAUDE.md < 200 lignes, /usage montre Prompt cache (main) chaud, coût de la démo < 0,50 EUR	3

Un projet en dessous de 15 sur 20 signale qu'un axe manque : le plus souvent le workflow CI ou les hooks. Un projet à 18 sur 20 ou plus tient en production interne — le module 15 rappelle les gestes mensuels (revue des behavior flags, lecture d'~/.claude/usage-data/report.html).

Variantes

Trois variantes pour adapter sans refaire :

• Kiosque-mono. Un seul développeur : trois skills (/commit, /revue, /nouveau-endpoint), un sous-agent (testeur), pas de workflow (le cron du module 14 suffit).
• Kiosque-scale. Cinquante développeurs : managed settings pour verrouiller permissions.deny, enabledPlugins et un modelPricing au tarif contracté ; publier kiosque-tools sur une marketplace privée.
• Kiosque-cloud. Équipe surtout via Claude Code on the web : .claude/settings.json, .mcp.json, CLAUDE.md, skills et workflow fonctionnent ; ce qui vit dans ~/.claude/ (user settings, plugins user-scope) doit être migré dans le dépôt ou en managed settings.

Pièges fréquents

• Skill trop bavarde. Un /nouveau-endpoint qui inline un tutoriel FastAPI dépasse le budget de contexte ; garder l'essentiel, laisser Claude lire les fichiers.
• Sous-agent qui écrit. Un revieweur autorisé à écrire corrige lui-même ce qu'il devrait signaler ; frontmatter sans Edit ni Write.
• Hook Stop trop long. Un make test de trois minutes bloque chaque tour ; isoler une cible make test-rapide pour le hook.
• MCP postgres en écriture. Toujours URL en utilisateur readonly — un DROP TABLE accidentel est irrécupérable.
• --dangerously-skip-permissions dans le workflow. Jamais sur un runner non isolé ; toujours --permission-mode dontAsk et --allowedTools étroit.
• CLAUDE.md racine qui accumule. Migrer les instructions détaillées vers une skill invocable, garder les invariants stables dans le fichier racine.

Point d'arrivée

Chaque poste partage la même palette : mêmes commandes, mêmes règles de permission, mêmes sous-agents, mêmes hooks, mêmes serveurs MCP. Le workflow GitHub Actions rejoue la palette en CI. Un cron nocturne (module 14) peut appeler claude --bare -p avec les mêmes garanties. Claude Code n'est plus un outil qu'on utilise, c'est un composant versionné du dépôt qui applique les règles aussi rigoureusement que le linter et les tests.

Vous êtes prêt pour la récapitulation et l'examen.