D3 — Configuration et workflows de Claude Code (20 %)

Ouvrez Claude Code dans un dépôt qu'il n'a jamais vu et il part de rien : il doit redécouvrir la commande de build, le lanceur de tests, où vivent les handlers, ce qui a été tenté le mois dernier. CLAUDE.md est le fichier qui arrête cette redécouverte. C'est du Markdown, Claude Code le lit au début de chaque session, et son contenu est ajouté à votre prompt.

Reste à savoir lequel. Le guide teste trois niveaux, et ils diffèrent sur un seul axe : qui les reçoit.

Cette troisième colonne est tout le task statement. Un fichier de niveau user vit dans un répertoire personnel. Committer le dépôt ne l'emporte pas ; cloner le dépôt ne le produit pas. Il n'atteint une seconde machine que si quelque chose l'y recopie.

Garder le fichier modulaire

Deux mécanismes, et le guide nomme les deux.

@import. Un chemin précédé de @, n'importe où dans le fichier, y attire un autre fichier. Les chemins relatifs sont résolus par rapport au fichier qui contient l'import, pas au répertoire de travail, et les imports s'imbriquent jusqu'à une profondeur maximale de quatre niveaux.

# packages/api/CLAUDE.md

Ce package possède la surface REST publique.

@../../standards/http-errors.md
@../../standards/database-migrations.md

C'est la compétence énoncée par le guide : dans un monorepo, le mainteneur importe dans le CLAUDE.md de chaque package les standards dont ce package a réellement besoin, au lieu de charger tous les standards partout.

.claude/rules/. Au lieu d'un seul fichier qui grossit, un fichier par sujet :

.claude/
├── CLAUDE.md            # ce qui est vrai de tout le projet
└── rules/
    ├── testing.md
    ├── api-conventions.md
    └── deployment.md

Les règles sans scoping par chemin se chargent au démarrage, au même rang que .claude/CLAUDE.md. Ajouter un champ paths à une règle la rend conditionnelle. C'est le TS 3.3, plus bas, et c'est la seule chose qui réduise vraiment ce qui se charge.

Pourquoi le fichier cesse de fonctionner

CLAUDE.md est de la guidance, pas de la configuration appliquée de force. Chaque ligne entre en concurrence avec toutes les autres pour l'attention : plus le fichier grossit, moins une règle donnée est suivie de façon fiable. Ce n'est pas un défaut à contourner, c'est la propriété qui dicte votre façon d'écrire.

Trois habitudes en découlent, et elles méritent d'être connues parce qu'elles donnent aussi la forme des mauvaises réponses :

• Spécifique et vérifiable. « Placer les nouvelles routes API dans src/api/handlers, une par fichier », pas « suivre les bonnes pratiques pour les routes API ». Si vous ne pouvez pas vérifier qu'une règle a été suivie, Claude non plus.
• Nommer le remplacement. « Utiliser des exports nommés, pas des exports par défaut » ferme la question ; « ne pas utiliser d'exports par défaut » la laisse ouverte.
• L'emphase est un budget. IMPORTANT et YOU MUST élèvent la priorité d'une règle, mais seulement par rapport aux règles plus discrètes autour d'elle. Si chaque ligne crie, plus aucune ne se distingue.

Et la règle qui n'a pas sa place dans ce fichier du tout : ce qui ne doit jamais arriver. « Ne jamais pousser sur main » écrit dans CLAUDE.md est un espoir. Un hook est du code qui s'exécute en un point fixe et peut refuser l'action. Le mécanisme est le TS 1.5 de D1 ; savoir où va telle règle est le 3.2, plus bas.

Quand vous avez tapé deux fois la même instruction en plusieurs étapes, elle doit cesser d'être quelque chose que vous tapez. Le guide retient deux mécanismes pour cela, et les traite comme distincts.

Les deux existent en deux portées, et le partage est le même qu'en 3.1 :

Le frontmatter que le guide teste

Un skill est un répertoire contenant un SKILL.md : frontmatter YAML, puis la procédure.

---
name: dependency-audit
description: Audite les dépendances tierces à la recherche de paquets inutilisés,
  obsolètes ou dupliqués. À utiliser lors d'une revue de dépendances ou avant une
  livraison.
context: fork
allowed-tools: Read, Grep, Glob, Bash
argument-hint: "[package-manager] — npm, pnpm ou cargo"
---

1. Lire le lockfile et lister chaque dépendance directe.
2. Chercher chacune dans les sources et signaler celles qui ne sont jamais importées.
3. Rapporter les paquets inutilisés, obsolètes et dupliqués en trois tableaux.

La description est le champ dont tout dépend : Claude ne charge au démarrage que les noms et les descriptions, et apparie sémantiquement votre demande à ces descriptions. Un skill qui ne se déclenche jamais a presque toujours une description qui ne recoupe pas votre façon réelle de formuler vos demandes.

Trois champs facultatifs portent ce task statement.

context: fork exécute le skill dans un contexte de subagent isolé. Le contenu du skill devient le prompt qui pilote ce subagent ; il n'hérite pas de votre conversation, et ce qui revient à la session principale est le résultat plutôt que toute la trace. C'est la réponse chaque fois que le volume de sortie d'un skill est le problème : une analyse de codebase qui imprime chaque chemin inspecté, un brainstorming qui explore cinq options que vous n'avez pas retenues.

allowed-tools restreint l'accès aux outils pendant l'exécution du skill, par exemple limiter un skill aux opérations d'écriture de fichiers pour qu'il ne puisse rien faire de destructeur. C'est la formulation du guide, et c'est elle qu'il faut répondre. Nuance terrain, pour votre propre machine : la documentation actuelle décrit ce champ comme une pré-approbation des outils listés pour le tour d'invocation, de sorte que Claude peut les employer sans demander, plutôt que comme un retrait des autres ; le champ qui retire réellement un outil du lot est disallowed-tools.

argument-hint est l'indice affiché à l'autocomplétion, de sorte qu'un développeur qui invoque le skill sans argument se voit dire quel paramètre il attend.

Les variantes personnelles, et pourquoi le nom compte

Les skills de même nom sont départagés par leur source, et un skill personnel l'emporte sur un skill projet. Clonez un dépôt qui livre .claude/skills/review/, gardez votre propre ~/.claude/skills/review/, et /review exécute le vôtre, silencieusement, sur votre machine seulement.

Quelle surface possède quelle règle

La dernière compétence du guide sur ce task statement est le choix entre un skill et CLAUDE.md. Le tableau complet mérite d'être gardé en tête, parce que les mauvaises réponses sur ce sujet sont toujours un autre mécanisme réel :

La frontière entre les deux premiers est celle du guide : standards universels toujours chargés contre workflows propres à une tâche chargés à la demande. Une procédure détaillée placée dans CLAUDE.md paie son coût en tokens dans chaque conversation, y compris celles qui n'ont rien à voir avec elle.

La frontière avec le hook est d'une autre nature. CLAUDE.md et les skills sont des instructions que Claude suit ; un hook est du code qui s'exécute. Si sauter la règle est inacceptable, elle ne relève pas du suivi d'instructions.

Les événements, et PreToolUse comme primitive d'application, sont le TS 1.5 de D1 et ne sont pas réenseignés ici. Ce qui diffère de ce côté de la frontière, c'est la façon dont un hook dit non. Un hook Claude Code est une commande déclarée dans les settings : il répond donc par un code de sortie, 2 bloque, et ce qu'il a écrit sur la sortie d'erreur est renvoyé à Claude comme motif. Un hook de l'Agent SDK est un callback dans votre processus et répond par un permissionDecision en JSON. Même événement, même intention, deux conventions. Et exit 1 est le piège côté Claude Code : il a l'air d'un échec et ne bloque rien.

# .claude/hooks/protect-main.sh — refuser un push sur main, à chaque fois.
# Un hook PreToolUse reçoit le nom de l'outil et son entrée en JSON sur stdin.
if grep -qE 'git +push.*\bmain\b'; then
  echo "Pousser sur main est interdit ; ouvrez une pull request." >&2
  exit 2          # 2 bloque et explique. 0 laisse passer. 1 ne fait ni l'un ni l'autre.
fi

Les subagents sont l'autre voisin. Ils se définissent comme des fichiers Markdown à frontmatter YAML sous .claude/agents/, et /agents en crée un de façon interactive. Deux faits appartiennent à ce task statement plutôt qu'à D1 : un subagent n'hérite pas de vos skills, et un subagent personnalisé ne charge que les skills que nomme son champ de frontmatter skills.

---
name: accessibility-reviewer
description: Relit les changements frontend à la recherche de régressions d'accessibilité.
tools: Read, Grep, Glob
skills: accessibility-audit, contrast-check
---

Relire le diff à la recherche de violations WCAG. Rapporter les constats ; ne jamais éditer de fichier.

Le reste — pourquoi le contexte isolé d'un subagent est le point, et ce qui doit voyager dans le prompt à cause de cela — est le TS 1.2 et le TS 1.3 de D1.

Découper CLAUDE.md en fichiers .claude/rules/ rend les instructions maintenables, et charge exactement autant de tokens qu'avant : c'est le problème que le 3.1 a laissé ouvert. C'est l'ajout d'un champ paths à une règle qui rend le chargement conditionnel.

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---

# Conventions de test

- Un `describe` par symbole exporté, des phrases `it` au présent.
- Construire les fixtures avec les factories de `test/factories` ; jamais de littéral en ligne.
- Ne jamais mocker la base — utiliser la base de test de `test/db.ts`.

paths prend une liste de glob patterns. Le corps de la règle n'entre en contexte que lorsque Claude travaille sur un fichier qui correspond à l'un d'eux ; le reste du temps il ne coûte rien. Un fichier de règle sans champ paths se charge inconditionnellement, comme le CLAUDE.md du projet.

Les globs sont ordinaires :

Pourquoi pas un CLAUDE.md dans le sous-répertoire

Les deux mécanismes scopent des instructions. Ils les scopent selon des choses différentes, et le guide teste cette différence.

Un CLAUDE.md de sous-répertoire est attaché à un lieu. C'est la bonne réponse quand la convention est réellement locale : tout ce qui est sous terraform/ obéit à ces règles de tagging, et rien en dehors.

Une règle scopée par chemin est attachée à un motif. C'est la bonne réponse quand les fichiers qui partagent une convention ne partagent pas de répertoire. Le cas canonique est celui des fichiers de test, colocalisés avec le code qu'ils couvrent et donc dispersés dans tout l'arbre. Écrire un CLAUDE.md dans chacun de quarante répertoires pour y dire les mêmes trois choses sur les tests est impossible à maintenir, et un unique CLAUDE.md racine qui les dit coûte à chaque session qui n'ouvre jamais un test.

Le plan mode est un mode de permission dans lequel Claude lit, cherche et lance des commandes en lecture seule, pose ses questions de clarification, et renvoie un plan, sans rien modifier. L'exécution directe est le mode ordinaire : vous décrivez le changement et Claude le fait.

# Y entrer pour toute une session…
claude --permission-mode plan "Restructurer le monolithe de facturation en services"

# …ou presser Shift+Tab pour y basculer en cours de session, /plan pour un seul prompt.

Le choix ne porte pas sur la prudence, il porte sur l'endroit où sont les décisions.

Le plan mode vaut son coût pour une raison : itérer sur un plan est bien moins cher que laisser une exécution avoir lieu puis nettoyer derrière. L'endroit où corriger le tir est avant qu'une ligne soit écrite. Et quand le plan revient, lisez-le au lieu de le parcourir : un plan non lu est une approbation que vous n'avez pas réellement donnée.

Le subagent Explore

Un subagent s'exécute dans sa propre fenêtre de contexte et renvoie un résumé ; les lectures, les recherches et les impasses restent avec lui. Cette isolation est le sujet de D1 (TS 1.2 et 1.3). Ce qui relève d'ici, c'est ce que le guide lui demande dans ce task statement.

Explore est le subagent intégré, en lecture seule, dédié à la découverte. Claude lui délègue la recherche ou la compréhension d'un codebase sans le modifier, et seul son résumé atteint la conversation principale. C'est la réponse chaque fois qu'une tâche en plusieurs phases épuise sa fenêtre pendant la phase de découverte : le coût de l'exploration est payé dans un contexte que vous allez jeter, et la fenêtre principale reste disponible pour planifier puis implémenter.

Il n'est pas lié au plan mode. Vous pouvez demander une exploration via le subagent hors plan mode quand tout ce que vous voulez est un résumé du fonctionnement de quelque chose.

La combinaison sur laquelle le guide interroge

Le plan mode et l'exécution directe ne sont pas une allégeance définitive. La forme courante est les deux, dans l'ordre : planifier la migration de bibliothèque, approuver le plan, puis l'exécuter directement. Le plan approuvé devient le périmètre de la phase d'écriture. L'arbitrage a eu lieu avant qu'un fichier change.

Les quatre techniques de ce task statement viennent de la liste du guide lui-même. Elles répondent à quatre défaillances différentes, et la question d'examen est toujours de quelle défaillance il s'agit.

Des exemples entrée/sortie concrets

La défaillance : la même consigne en prose produit un résultat différent à chaque exécution. Le remède que le guide dit le plus efficace n'est pas plus de prose. C'est deux ou trois paires concrètes montrant la transformation.

Normalise ces fiches client.

  "Dupont,  Marie-Claire"  →  { first: "Marie-Claire", last: "Dupont" }
  "jean pierre MARTIN"     →  { first: "Jean Pierre", last: "Martin" }
  "O'Brien, Sean (Jr.)"    →  { first: "Sean", last: "O'Brien", suffix: "Jr." }

Trois paires tranchent ce qu'un paragraphe de définition laissait ouvert : où va la virgule, ce qu'il advient de la casse, qu'un suffixe reçoit son propre champ. Un exemple montre le résultat au lieu de le décrire, et les cas limites que vous choisissez d'y inclure sont exactement ceux qui vous inquiétaient.

L'itération guidée par les tests

La défaillance : vous ne pouvez pas dire si le code est juste, donc Claude non plus. Écrivez la suite de tests d'abord — comportement attendu, cas limites, exigences de performance — puis faites écrire l'implémentation contre elle, puis itérez en renvoyant les échecs.

$ pytest tests/test_migration.py
FAILED test_null_effective_date - AssertionError: expected None, got '1970-01-01'
FAILED test_duplicate_account_ids - KeyError: 'legacy_id'

Deux conditions font que cela fonctionne au lieu de simplement paraître rigoureux. Les tests doivent être une source de vérité fiable : une suite qui passe sur du code cassé transforme l'itération en fausse confiance. Et « terminé » doit vouloir dire que les portes ont été franchies et observées, pas qu'un résumé affirme qu'elles l'ont été.

La version la plus tranchante qu'en donne le guide concerne les cas limites. Plutôt que de décrire le problème, fournissez le cas précis : cette entrée, cette sortie attendue, par exemple la valeur nulle que votre script de migration traite mal.

L'interview pattern

La défaillance : la spécification est incomplète et personne ne le sait encore. Demandez à Claude de vous interroger avant d'implémenter.

Avant d'implémenter le cache de l'API de tarification, pose-moi les questions dont
tu as besoin pour trancher la conception. N'écris pas de code avant mes réponses.

  1. Invalidation par TTL, ou sur événement d'écriture ?
  2. Des données périmées sont-elles acceptables si le cache est injoignable ?
  3. Par locataire ou global ?
  4. Quel volume de lecture doit-il tenir ?

Sa valeur, c'est la question 2. Vous n'aviez pas pensé au cache injoignable, et vous l'auriez découvert en production. Prenez-le dans les domaines peu familiers, là où les implications ne sont pas évidentes — stratégies d'invalidation de cache, modes de défaillance — et là où plusieurs approches sont valides et où la bonne dépend d'un contexte que vous n'avez pas énoncé.

Un seul message, ou un à la fois

La défaillance : plusieurs problèmes à la fois, et les correctifs se combattent.

Une gestion d'erreurs manquante et une validation d'entrée fausse font un seul message : une réponse unifiée doit les placer ensemble. Renommer une variable et changer un type de retour font deux conversations.

Claude Code est interactif par défaut. Invoqué dans un pipeline sans personne pour répondre à une invite, il attend, et le runner finit par le tuer au timeout de l'étape. Tout ce task statement découle de là.

-p, et la forme de la sortie

-p, écrit en toutes lettres --print, exécute Claude Code comme une commande à un coup : il traite le prompt, écrit le résultat sur la sortie standard, et se termine. Il lit l'entrée standard et écrit sur la sortie standard, donc il se branche en pipe comme n'importe quel outil shell.

Cela fait aboutir le job. Obtenir quelque chose que l'étape suivante peut exploiter demande deux flags de plus : --output-format json fait de la réponse une enveloppe JSON, et --json-schema contraint la charge utile à un schéma que vous fournissez. L'objet conforme atterrit dans le champ structured_output de l'enveloppe, à un endroit fixe, si bien que rien en aval n'a de prose à parser.

- name: Revue du diff
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "Relis $(git diff origin/main...HEAD) à la recherche de failles de sécurité et de bugs." \
      --output-format json \
      --json-schema '{
        "type": "object",
        "properties": {
          "issues": {"type": "array", "items": {
            "type": "object",
            "properties": {
              "severity": {"enum": ["critical", "major", "minor"]},
              "file": {"type": "string"},
              "line": {"type": "integer"},
              "message": {"type": "string"}
            },
            "required": ["severity", "file", "message"]
          }}
        }
      }' \
      | jq '.structured_output.issues' > findings.json

findings.json est maintenant une liste qu'une étape ultérieure peut poster en commentaires inline sur la pull request via l'API GitHub. La clé d'API vient des secrets du dépôt, jamais du fichier de workflow.

Ce que l'instance CI sait

Un Claude Code invoqué en CI n'a pas d'historique de session et personne à qui demander. La réponse du guide à cela est CLAUDE.md : le fichier projet versionné est le mécanisme qui porte à l'instance qui tourne dans le pipeline les standards de test, les conventions de fixtures et les critères de revue. Documentez quelles fixtures existent et ce qui fait qu'un test vaut la peine d'être écrit, et la génération de tests cesse de produire des tests de faible valeur qui recouvrent un terrain que la suite tient déjà, c'est aussi pourquoi vous mettez les fichiers de test existants en contexte quand vous en demandez de nouveaux.

Relire est le travail d'une seconde instance

La session qui a écrit le code en est le plus mauvais relecteur. Elle porte le raisonnement qui a produit ce code et remet le moins en question ses propres décisions, le même biais qu'un auteur relisant son propre texte. La revue tourne dans une instance indépendante : une session séparée, ou un subagent sans mémoire de la façon dont le code a été construit. Un œil neuf attrape ce que l'exécution d'origine s'est raconté pour passer outre.

Deux règles opérationnelles complètent le tableau, et toutes deux sont des compétences du guide :

• En relançant une revue après de nouveaux commits, passez-lui les constats précédents et demandez à Claude de ne rapporter que ce qui est nouveau ou encore non traité. Sinon chaque push soulève de nouveau les mêmes problèmes, la pull request se remplit de commentaires dupliqués, et les développeurs cessent de les lire.
• Passez les fichiers de test existants lors de la génération de tests, pour que les nouveaux ne dupliquent pas des scénarios déjà couverts.