Claude Code —
Guide de personnalisation avancée

Le fichier CLAUDE.md est chargé automatiquement par Claude Code à chaque session. Il joue le rôle des custom instructions de Copilot, mais avec une portée hiérarchique basée sur l'emplacement des fichiers plutôt que sur des globs.

Portée et priorité

Imports avec @

Un CLAUDE.md peut inclure d'autres fichiers via la directive @, ce qui permet de découper les instructions par thème.

# Conventions du projet

@.claude/conventions/typescript.md
@.claude/conventions/api.md
@.claude/conventions/tests.md

## Contexte général
Stack : Next.js 15, tRPC, Drizzle ORM, PostgreSQL.
Toujours typer explicitement les retours de fonctions.
Préférer les Server Components sauf si l'interactivité l'exige.

Les skills encapsulent un domaine d'expertise et sont invoqués automatiquement par Claude quand la description correspond au contexte, ou manuellement via une commande slash.

Emplacement

.claude/skills/nom-du-skill.md

Structure

---
name: api-rest
description: "Conception REST : nommage des routes, versioning,
  pagination, gestion d'erreurs RFC 7807, OpenAPI."
whenToUse: "Lorsqu'on crée ou révise des endpoints API."
---

# Expertise API REST
Contenu décrivant le domaine : conventions, exemples,
anti-patterns à éviter, décisions architecturales...

Les hooks exécutent des commandes shell en réaction aux événements de Claude Code. Ils sont configurés dans .claude/settings.json.

Événements disponibles

Configuration

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",            // "" = toujours
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",        // matcher sur le nom de l'outil
        "hooks": [
          {
            "type": "command",
            "command": "echo 'running shell command'"
          }
        ]
      }
    ]
  }
}

Le protocole MCP connecte Claude à des outils et services externes. La configuration se fait dans .claude/settings.json (projet) ou ~/.claude/settings.json (global).

Serveurs populaires

Configuration

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "${DATABASE_URL}"]
    }
  }
}

Les commandes slash sont des templates de prompts invocables via /nom dans le chat. Équivalent des Prompt Files de Copilot.

Emplacement

.claude/commands/nom.md

Structure

---
description: "Crée un composant React selon le design system"
---

Crée un composant React nommé $ARGUMENTS.

Respecte les conventions de CLAUDE.md.
Utilise les tokens du design system dans src/tokens.ts.
Génère le fichier composant et son test unitaire associé.

Structure attendue :
- Props typées explicitement
- Storybook story si applicable
- Export nommé (pas default)

Variables disponibles

Claude Code peut déléguer des sous-tâches à des agents spécialisés, chacun avec ses propres instructions, outils, et contexte de travail. Les types d'agents personnalisés se définissent dans .claude/agents/.

Quand utiliser un agent

Préférer un agent pour les tâches longues ou exploratoires : audit de code, recherche dans le codebase, génération de rapports — toute opération dont le volume de sortie encombrerait la conversation principale.

La direction de l'agence : produire le moins de code possible manuellement. Pour y parvenir, il faut identifier les bons cas d'usage, appliquer les bonnes pratiques, et rester efficace — l'objectif est le gain de temps, pas l'IA pour l'IA.

Plan avant développement

Toujours faire un plan avant chaque développement (mode Plan : Shift+Tab ou /plan). Prendre le temps de le préparer : c'est un investissement qui fait gagner du temps par la suite. Un plan validé évite les allers-retours et limite le code cassé.

Structure d'un bon prompt

Cas d'usage validés par l'équipe

La qualité des réponses dépend directement de la qualité du contexte. Trois règles issues de nos retours d'expérience :

Cycle de session recommandé

# Quand le contexte devient trop lourd :
> Fais un état des lieux de notre avancement dans
  docs/handoff.md : ce qui est fait, ce qui reste,
  les décisions prises et les fichiers concernés.

# Puis nouvelle session :
/clear
> Lis docs/handoff.md et continue le développement.

Commandes utiles

Objectif : laisser Claude travailler sans interruption sur les opérations courantes, tout en bloquant les commandes dangereuses. La configuration se fait dans .claude/settings.json (partagé équipe) ou settings.local.json (personnel).

Configuration type

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(composer:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npx playwright test:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",          // jamais de suppression récursive
      "Bash(git push --force:*)",
      "Read(.env*)",             // secrets hors de portée
      "Read(**/credentials*)"
    ]
  }
}

Intégrer davantage Playwright dans nos développements. Claude est capable de lancer les tests Playwright lui-même, d'interpréter les échecs et de corriger — ce qui ferme la boucle développement → test → correction sans intervention manuelle.

Pourquoi Playwright avec Claude

> Implémente le formulaire de contact selon le plan validé.
  Critère de validation : npx playwright test contact.spec.ts
  doit passer, et la suite existante ne doit pas régresser.

Ne jamais transmettre à l'IA, quel que soit le canal (prompt, fichier, MCP) :

Être moteur sur le sujet : partager au maximum les outils, astuces, prompts, skills et fichiers utiles avec l'équipe. Tout ce qui fonctionne pour un développeur doit être versionné dans .claude/ (skills, commands, settings) pour profiter à tous — c'est le principe même de ce guide.