D2 · Claude Code Configuration and Workflows

Ce domaine vaut environ 12 des 60 items et correspond aux scénarios Code-Generation et CI/CD. Il évalue votre capacité à configurer Claude Code correctement pour un individu et, surtout, pour une équipe : où vit le contexte, comment les settings et les permissions se résolvent, quand appliquer par des hooks plutôt qu’orienter par des prompts, et comment exécuter Claude Code en headless dans la CI. Le thème récurrent est la précédence et le bon mécanisme pour la bonne tâche.

Objectifs d’apprentissage

À la fin de cette page, vous devriez savoir :

1. Ordonner la hiérarchie CLAUDE.md et décider de ce qui appartient à chaque niveau.
2. Résoudre les portées de settings.json et la précédence des permissions (allow / deny / ask).
3. Configurer des hooks pour chaque événement, utiliser le code de sortie 2 pour bloquer, et lire/écrire du JSON sur stdin/stdout.
4. Choisir parmi Skill, CLAUDE.md, slash command, subagent et MCP pour un besoin donné.
5. Écrire des slash commands personnalisées avec $ARGUMENTS et définir des subagents avec des allowlists d’outils et des modèles par agent.
6. Trancher entre plan mode et exécution directe et exécuter Claude Code en headless dans la CI avec les bons drapeaux et la gestion des codes de sortie.
7. Concevoir des conventions à l’échelle de l’équipe : settings de projet versionnés, managed policies, portées de configuration MCP et maîtrise des coûts.

2.1 La hiérarchie CLAUDE.md

Les fichiers CLAUDE.md injectent un contexte de projet persistant dans chaque session. Ils se composent du plus large au plus étroit, les fichiers plus spécifiques se superposant par-dessus.

Managed policy (enterprise, admin-controlled)   ← highest authority, cannot be overridden
        ▼
User        ~/.claude/CLAUDE.md                  ← your personal defaults across all projects
        ▼
Project     ./CLAUDE.md   (checked into git)     ← shared team context for this repo
        ▼
Subdirectory ./packages/x/CLAUDE.md              ← context specific to a part of the repo

CLAUDE.local.md est un fichier personnel ignoré par git pour les notes propres au projet que vous ne voulez pas partager. Utilisez @path/to/file pour importer d’autres fichiers (par ex. @docs/architecture.md) afin que le contexte reste modulaire et DRY.

2.2 Portées et précédence de settings.json

settings.json configure les permissions, les hooks, l’environnement et le modèle. Les portées se résolvent du plus au moins autoritaire :

Managed policy settings         (admin, cannot be overridden)
        ▼ overrides
.claude/settings.local.json     (personal, git-ignored)
        ▼ overrides
.claude/settings.json           (project, checked in)
        ▼ overrides
~/.claude/settings.json         (user, global default)

{
  "model": "claude-opus-5",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm test:*)", "Bash(git status)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./secrets/**)"],
    "ask": ["Bash(git push:*)", "WebFetch"]
  },
  "env": { "NODE_ENV": "test" }
}

2.3 Permissions : allow / deny / ask

deny l’emporte sur allow. Les motifs correspondent au nom de l’outil et à ses arguments (par ex. Bash(git commit:*)). Préférez une allowlist étroite plus des deny explicites pour les opérations dangereuses ; utilisez ask pour les actions généralement bénignes mais parfois lourdes de conséquences.

2.4 Hooks

Les hooks sont des gestionnaires shell (ou HTTP) déterministes qui se déclenchent sur des événements du cycle de vie. Ils reçoivent le JSON de l’événement sur stdin et peuvent émettre du JSON sur stdout ; le code de sortie 2 bloque l’action (et renvoie stderr à Claude), tandis que le code de sortie 0 l’autorise.

Événements : PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, Notification, SubagentStop, PreCompact.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "./.claude/hooks/guard.sh" }]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/guard.sh — lit le JSON de l'appel d'outil sur stdin, bloque les commandes destructrices.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -qE 'rm -rf|:(){ :|:& };:'; then
  echo "Blocked destructive command: $cmd" >&2
  exit 2      # le code de sortie 2 bloque l'appel d'outil
fi
exit 0

#!/usr/bin/env bash
# Bloque un git commit si la suite de tests échoue. Déterministe — pas une instruction de prompt.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -q 'git commit'; then
  if ! npm test --silent; then
    echo "Tests failing — commit blocked." >&2
    exit 2
  fi
fi
exit 0

#!/usr/bin/env bash
# Après que Claude a édité un fichier, le linter automatiquement et remonter les problèmes à Claude.
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // ""')
if [[ "$file" == *.ts || "$file" == *.tsx ]]; then
  npx eslint --fix "$file" 2>&1 || echo "Lint issues remain in $file" >&2
fi
exit 0

2.5 Skills, CLAUDE.md, slash commands, subagents, MCP — lequel ?

Ces cinq mécanismes se recoupent, et bien choisir est fortement testé.

Skills et divulgation progressive

Un Skill vit dans .claude/skills/<name>/SKILL.md avec un frontmatter (name, description) et des scripts optionnels fournis. Claude lit la description pour décider quand le skill est pertinent et ne charge le corps complet qu’à ce moment — la divulgation progressive garde le contexte léger.

---
name: pdf-invoice-extractor
description: Extract structured fields from PDF invoices. Use when the user asks to pull totals, dates, or line items from an invoice PDF.
---

# PDF Invoice Extractor
1. Read the PDF text layer.
2. Extract fields into the JSON schema in ./schema.json.
3. Validate and report any missing required fields.

2.6 Slash commands personnalisées

Un fichier .claude/commands/review.md devient /review. $ARGUMENTS est substitué par ce qui suit la commande.

---
description: Review a pull request for security and style issues.
---
Review the changes in PR #$ARGUMENTS. Check for injection risks, missing input
validation, and deviations from ./CLAUDE.md conventions. Output a table of
findings with severity.

Invoquez avec /review 482. Les commandes peuvent être de portée projet (.claude/commands/) ou user (~/.claude/commands/).

2.7 Subagents

Un subagent est défini dans .claude/agents/<name>.md avec son propre system prompt, son allowlist d’outils et son modèle. Il s’exécute dans une fenêtre de contexte isolée, protégeant la conversation principale du bruit.

---
name: security-reviewer
description: Reviews diffs for security vulnerabilities. Use proactively before merges.
tools: Read, Grep, Bash(git diff:*)
model: claude-opus-5
---
You are a security reviewer. Examine the diff for injection, authz gaps, secret
leakage and unsafe deserialisation. Report findings with severity and file:line.
Do not modify code.

Points de conception clés : donnez à chaque subagent une allowlist d’outils étroite (moindre privilège), choisissez un modèle par agent (un classifieur Haiku bon marché, un relecteur Opus), et rappelez-vous que son contexte est isolé — le parent doit passer le contexte explicitement (même règle qu’au Domaine 1).

2.8 Plan mode vs exécution directe

Le plan mode (Shift+Tab) fait explorer Claude en lecture seule et produire un plan avant de toucher à quoi que ce soit. L’exécution directe le laisse éditer et exécuter immédiatement.

2.9 Usage headless et CI

Exécutez Claude Code de façon non interactive avec claude -p (print mode). C’est le scénario CI/CD.

# Revue headless en CI, sortie lisible par machine, allowlist d'outils étroite, sans invites.
claude -p "Review the diff in this PR for security issues and output JSON findings." \
  --output-format json \
  --allowedTools "Read,Grep,Bash(git diff:*)" \
  --permission-mode acceptEdits

echo "exit code: $?"   # 0 succès ; non nul en cas d'échec — barrez le pipeline dessus

Barrez le pipeline sur le code de sortie ; parsez le JSON pour des découvertes structurées. Gardez l’allowlist d’outils minimale en CI pour qu’une instruction injectée ne puisse pas exécuter de commandes arbitraires.

2.10 Revue de code multi-passes pour les grosses PR

Les grosses PR débordent d’une seule passe de revue. Découpez le travail :

1. Partitionnez le diff par fichier ou module pour que chaque passe tienne confortablement en contexte.

2. Relisez chaque partition dans sa propre passe (ou subagent) avec un prompt ciblé, en émettant des découvertes structurées.

3. Agrégez les découvertes, dédupliquez et classez par sévérité dans une passe finale de synthèse.

Cela reflète orchestrator-workers : des partitions indépendantes relues dans des contextes isolés, puis agrégées. Cela garde aussi chaque contexte assez petit pour que la qualité ne se dégrade pas.

2.11 Conventions à l’échelle de l’équipe

Portées de configuration MCP

Agent teams, dynamic workflows, routines

Claude Code prend en charge les agent teams (plusieurs subagents coordonnés), les dynamic workflows (étapes composées à l’exécution) et les routines (procédures multi-étapes sauvegardées). Positionnez-les comme une orchestration de plus haut niveau bâtie sur les primitives ci-dessus ; à l’examen, préférez la plus simple qui résout le problème énoncé.

Maîtrise des coûts

Utilisez /cost pour inspecter la dépense, choisissez un modèle par subagent moins cher là où la qualité le permet (Haiku pour la classification, Sonnet pour le travail équilibré, Opus pour le codage difficile), et gardez CLAUDE.md concis pour réduire les tokens par tour. Le prompt caching s’applique au préfixe stable CLAUDE.md/outils.

2.12 Une configuration d’équipe complète et travaillée

L’examen récompense de savoir exactement quel fichier détient quel réglage. Voici une organisation de projet cohérente et versionnée pour le scénario Code-Generation, suivie du raisonnement pour chaque placement.

repo/
├── CLAUDE.md                      # shared: build/test cmds, architecture, conventions (+ @imports)
├── CLAUDE.local.md                # git-ignored: personal scratch notes, local paths
├── .mcp.json                      # shared: project-scope MCP servers
└── .claude/
    ├── settings.json              # shared: permissions, hooks, model, env
    ├── settings.local.json        # git-ignored: personal overrides
    ├── agents/
    │   └── security-reviewer.md   # subagent: isolated context, tool allowlist, model
    ├── commands/
    │   └── review.md              # /review $ARGUMENTS
    ├── skills/
    │   └── release-notes/SKILL.md # progressive-disclosure capability
    └── hooks/
        └── guard.sh               # PreToolUse guard (exit 2 blocks)

CLAUDE.md travaillé (concis, imports pour le volume) :

# Payments Service
Build: `pnpm build`  ·  Test: `pnpm test`  ·  Lint: `pnpm lint`
Never touch `migrations/` without a reviewed plan.
Architecture and coding conventions: @docs/architecture.md
Never put secrets here; use the secret manager. See @docs/security.md

.claude/settings.json travaillé :

{
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./secrets/**)"],
    "ask": ["Bash(git push:*)", "WebFetch"]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "./.claude/hooks/guard.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "./.claude/hooks/lint.sh" }] }
    ]
  },
  "env": { "NODE_ENV": "test" }
}

2.13 Les événements de hook en profondeur et la sémantique des codes de sortie

Chaque hook reçoit le JSON de l’événement sur stdin ; le code de sortie 2 bloque (stderr est renvoyé à Claude), le code 0 autorise, et les autres codes non nuls font remonter une erreur sans nécessairement bloquer. Faire correspondre l’événement à l’objectif est directement testé.

#!/usr/bin/env bash
# PreCompact hook: persiste le journal de décisions courant avant que la fenêtre ne soit compactée.
input=$(cat)
echo "$input" | jq -r '.transcript_summary // ""' >> ./.claude/decision-log.md
exit 0

2.14 Formats de sortie headless et gating par code de sortie en CI

claude -p prend en charge deux formats de sortie lisibles par machine. Bien choisir compte pour la conception de la CI.

set -euo pipefail
result=$(claude -p "Review the diff for security issues; output JSON {findings:[{severity,file,line,note}]}." \
  --output-format json \
  --allowedTools "Read,Grep,Bash(git diff:*)")
# Fait échouer le build si une découverte de sévérité élevée existe.
echo "$result" | jq -e '.findings | map(select(.severity=="high")) | length == 0' >/dev/null \
  || { echo "High-severity findings — failing build."; exit 1; }

Barrez le pipeline sur à la fois le code de sortie du processus et les découvertes structurées parsées ; ne faites jamais de grep sur la prose.

Idées reçues fréquentes

Étude de scénario — standardiser une équipe sur Claude Code en toute sécurité

Situation. Une organisation de 40 ingénieurs adopte Claude Code. La sécurité impose que les fichiers de secrets de production ne soient jamais lisibles et que rm -rf ne soit jamais exécuté — pour tout le monde, sans surcharge locale. L’équipe plateforme veut des commandes de build/test et des conventions d’architecture partagées et disponibles pour tous, un moyen de bloquer les commits quand les tests échouent, une commande de revue de PR répétable, et un assistant de revue de diff qui ne peut jamais éditer ni pousser. Un ingénieur veut des notes personnelles qui restent hors du repo partagé. La CI doit relire les PR en headless et faire échouer les builds sur les problèmes de sévérité élevée sans être détournée par un contenu de diff malveillant.

Trace de raisonnement d’expert.

1. Règles de sécurité non contournables → managed policy. « Pour tout le monde, sans surcharge » est la définition d’une managed policy ; placez-y les règles deny pour Read(./secrets/**) et Bash(rm -rf:*) (et étayez le blocage de commande destructrice par un PreToolUse hook managé sortant en 2). Rejetez settings.local.json (par utilisateur, surchargeable) et la prose CLAUDE.md (#3).

2. Conventions partagées → CLAUDE.md de projet versionné, gardé concis avec @import pour le volume. Rejetez le fichier user (par personne) et CLAUDE.local.md (ignoré par git).

3. Tests-avant-commit → PreToolUse hook sur le commit qui exécute les tests et sort en 2. Rejetez une instruction CLAUDE.md (probabiliste) et une slash command (opt-in).

4. Revue répétable → slash command .claude/commands/review.md avec $ARGUMENTS. Rejetez un subagent (c’est pour des contextes délégués isolés, non un prompt nommé à la demande).

5. Relecteur de diff qui ne peut pas éditer/pousser → subagent avec une allowlist de moindre privilège (Read, Grep, Bash(git diff:*)). Rejetez « le lui dire dans le prompt » (style #3, contournable).

6. Notes personnelles → CLAUDE.local.md ignoré par git.

7. CI headless → claude -p --output-format json avec un --allowedTools minimal, barrer sur le code de sortie + les découvertes parsées, jamais bypassPermissions, pour qu’une instruction injectée dans le diff ne puisse pas exécuter du shell arbitraire.

Décision correcte à l’examen : managed policy + CLAUDE.md/settings versionnés + PreToolUse hooks + slash command + subagent de moindre privilège + fichier local pour les notes personnelles + JSON headless avec une allowlist étroite. Chaque option rejetée est un mécanisme utilisé pour la mauvaise tâche — la forme exacte des distracteurs D2.

Pièges d’examen dans ce domaine

Questions d’entraînement

Points clés à retenir

• CLAUDE.md se compose managed policy → user → project → subdirectory ; gardez-le concis, ne stockez jamais de secrets, et utilisez @import pour la modularité.
• settings.json se résout managed policy → local → project → user ; deny bat allow ; utilisez ask pour les actions parfois lourdes de conséquences.
• Les hooks sont déterministes : le code de sortie 2 bloque, JSON sur stdin/stdout, les événements couvrent tout le cycle de vie. Utilisez des hooks (non des prompts) pour les règles critiques, et PreToolUse (non PostToolUse) pour bloquer.
• Choisissez le mécanisme délibérément : CLAUDE.md (contexte toujours actif), Skill (capacité progressive à la demande), slash command (prompt invoqué), subagent (contexte/outils/modèle isolés), MCP (intégration externe).
• Les subagents reçoivent des allowlists d’outils de moindre privilège et un modèle par agent ; plan mode pour le travail volumineux/inconnu/risqué.
• CI headless : claude -p avec --output-format json (court) ou stream-json (long), un --allowedTools minimal, et un gating du pipeline sur le code de sortie et les découvertes parsées — ne faites jamais de grep sur la prose.
• Échelle d’équipe : settings de projet et .mcp.json versionnés, managed policy pour les règles obligatoires, /cost et modèles par subagent pour la maîtrise des coûts, revue multi-passes pour les grosses PR.
• Mappez chaque question « où doit vivre X » sur deux axes — partagé vs personnel, indicatif vs obligatoire — pour choisir le fichier/mécanisme correct.
• Ne stockez jamais de secrets dans un fichier versionné (CLAUDE.md ou settings.json) ; utilisez un secret manager plus des règles deny sur les chemins de secrets.