Guide ultime de la configuration de Claude Code : Hooks, Compétences et Actions

Claude Code transforme une base de code ordinaire en un membre d'équipe capable de lire, écrire, refactoriser et même gérer les tickets.

Que vous soyez développeur solo ou faisant partie d'une grande équipe, ce tutoriel vous fournit une configuration complète et pratique qui couvre :

• Mémoire de projet via CLAUDE.md
• Hooks d'exécution, variables d'environnement et restrictions de commandes
• “Compétences” réutilisables pour les motifs, les tests et l'architecture
• Serveurs MCP pour JIRA, GitHub, Slack…
• Intégration LSP pour diagnostics en temps réel
• Agents personnalisés et commandes slash
• Actions GitHub pour revues PR, contrôles qualité et tâches programmées

1. Pourquoi Claude Code?

Les assistants LLM traditionnels lisent souvent le code comme du texte brut. Claude Code change cela en :

Avec ces éléments, Claude devient un coéquipier fiable plutôt qu'un simple outil de génération de code.

2. Aperçu de la structure du projet

your‑project/
├── .claude/
│   ├── agents/          # Custom AI agents
│   ├── commands/        # Slash commands
│   ├── hooks/           # Hook scripts & rules
│   ├── skills/          # Domain‑specific knowledge
│   ├── settings.json    # Global hooks & env vars
│   └── settings.md      # Human‑readable docs
├── .mcp.json            # MCP server config (JIRA, GitHub, etc.)
├── .github/workflows/   # GitHub Actions
├── CLAUDE.md            # Project memory – top‑level
└── README.md

Astuce : Stockez les surcharges spécifiques à l'utilisateur dans un .claude/settings.local.json ou un CLAUDE.local.md personnel – ces fichiers doivent être ignorés par Git.

3. Démarrage rapide : Créer le gabarit

mkdir -p .claude/{agents,commands,hooks,skills}

# CLAUDE.md de base – modifiez selon votre pile
cat <<'EOF' > CLAUDE.md
# My Awesome Project

## Stack
- React
- TypeScript
- Node.js

## Key Directories
- src/components/  # UI
- src/api/         # API layer
- tests/           # Jest tests

## Code Style
- TypeScript strict mode
- Prefer interfaces over types
- No `any` – use `unknown`
EOF

# Basic settings.json with a simple PreToolUse hook
cat <<'EOF' > .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

Exécutez git add -A && git commit -m "Initial configuration Claude Code" pour enregistrer la structure.

4. Mémoire de projet : CLAUDE.md

CLAUDE.md est la mémoire persistante de Claude qui se charge à chaque session. Gardez-la concise mais complète :

• Pile & architecture – Vue d'ensemble rapide de la pile.
• Commandes clés – npm run test, npm run lint, npm run build.
• Directives de style de code – Toute règle de linting, strictesse de type.
• Répertoires critiques – Où se trouvent les composants, utilitaires ou tests.
• Contraintes spéciales – par ex., pas d'édition sur la branche main.

Claude lit ce fichier en premier, placez donc vos informations les plus importantes en haut.

5. Hooks & Environnement : .claude/settings.json

Les hooks vous permettent d'intercepter les appels d'outils ou les invites utilisateur. Une configuration type contiendra :

Exemple : Bloquer les edits sur main

"PreToolUse": [
  {"matcher": "Edit|Write", "hooks": ["if [ \"$(git branch --show-current)\" != \"main\" ]; then echo 'Allowed'; else echo 'Blocked'; fi"]}
]

Vous pouvez également ajouter des variables d'environnement pour les secrets (jetons API JIRA, etc.). Le fichier est engagé car les secrets sont référencés via des espaces réservés ${VAR} qui se chargent à l'exécution.

6. Compétences : Connaissances de domaine réutilisables

Les compétences sont des fichiers Markdown qui apprennent à Claude à écrire du code dans votre style. Chaque compétence se trouve sous .claude/skills/{skill-name}/SKILL.md.

Exemple de frontmatter de compétence

---
name: testing-patterns
description: Modèles de tests Jest pour ce projet. Utilisez lorsque vous écrivez des tests, créez des mocks ou suivez le workflow TDD.
---

Exemple de contenu de compétence

# Testing Patterns

## Arrange-Act-Assert

```ts
// Arrange
const mockUser = getMockUser();

// Act
const result = login(mockUser);

// Assert
expect(result).toBeTruthy();

Mocking

Préférez les fonctions de fabrique aux mocks globaux pour garder les tests déterministes.

Ajouter une nouvelle compétence

1. Créez .claude/skills/{skill-name}/SKILL.md.
2. Rédigez une description concise.
3. Implémentez des exemples de code.
4. Mettez à jour skill-rules.json si nécessaire pour mapper les déclencheurs.
5. Ajoutez le répertoire de compétence à Git et engagez.

7. Hooks d’évaluation des compétences

Lorsqu'un utilisateur soumet une invite, le hook UserPromptSubmit exécute un petit moteur qui recherche :

• Mots-clés – par ex., write test.
• Motifs de chemin – par ex., src/components/*.
• Motifs d'intention – expressions régulières capturant les demandes courantes.
• Cartographie de répertoire – lier les chemins de fichiers aux noms de compétences.

Le hook produit un JSON spécifiant les compétences à activer, par ex. :

{"activate": ["testing-patterns", "react-ui-patterns"]}

Astuce : Gardez skill-rules.json léger – ajoutez de nouvelles règles à mesure que de nouveaux motifs apparaissent.

8. Serveurs MCP : Connexion aux outils externes

Les serveurs MCP (Modèle de Protocole de Contexte) donnent à Claude un accès direct aux services comme JIRA, GitHub, Slack, Sentry ou Postgres. Configurez-les dans .mcp.json.

Exemple : JIRA & GitHub

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-jira"],
      "env": {"JIRA_HOST": "${JIRA_HOST}", "JIRA_EMAIL": "${JIRA_EMAIL}", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    }
  }
}

Stockez les vrais jetons dans des variables d'environnement ou un fichier .env qui n'est pas engagé.

La commande /ticket

Une commande slash /ticket peut lire une issue JIRA, générer une branche, implémenter la fonctionnalité demandée et fermer automatiquement le ticket. Des instructions détaillées sont disponibles dans .claude/commands/ticket.md.

9. Support LSP

Ajoutez des plugins du protocole du serveur de langage pour donner à Claude des diagnostics en temps réel :

// .claude/settings.json
"enabledPlugins": {
  "typescript-lsp@claude-plugins-official": true,
  "pyright-lsp@claude-plugins-official": true
}

Assurez-vous que les binaires LSP sont installés (ex., npm i -g typescript-language-server). LSP confère à Claude :

• Diagnostics – erreurs de type à l'édition.
• Intellisense – signatures de fonctions et informations de type.
• Navigation – passer aux définitions.
• Complétion – suggestions contextuellement pertinentes.

10. Agents & Commandes

Agents

Les agents sont des assistants spécialisés. Un agent code-reviewer pourrait exécuter automatiquement une liste de contrôle et commenter les pull requests.

---
name: code-reviewer
description: Examine le code TypeScript pour le style, la sécurité et les tests.
model: opus
---

Commandes

Les commandes slash exécutent des flux de travail personnalisés. Par exemple, /pr-review étend une PR, examine les changements et laisse un commentaire.

---
description: Examiner la PR actuelle en utilisant la liste de contrôle standard.
allowed-tools: Bash(git:*), Read, Grep
---

Créez le fichier markdown sous .claude/commands/ et référencez-le dans vos Actions GitHub.

11. Automatisation des Actions GitHub

Automatisez les vérifications de qualité, la synchronisation des docs et les audits de dépendances avec des workflows situés dans .github/workflows/. Exemples typiques :

• Auto revue PR – déclenché sur les événements PR et exécute Claude code-reviewer.
• Synchronisation Docs programmée – s'exécute mensuellement pour assurer que les docs reflètent le code le plus récent.
• Qualité de code hebdomadaire – balayages aléatoires de répertoires avec auto‑correction.
• Audit de dépendances bi-hebdomadaire – mises à jour sécurisées avec vérification de test.

Un workflow minimal PR review :

name: PR - Claude Review
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-opus-4-5-20251101
          prompt: |
            Review this PR using .claude/agents/code-reviewer.md standards.
            Run `git diff origin/main...HEAD` to see changes.

Ajoutez ANTHROPIC_API_KEY aux Secrets du dépôt pour l'accès à l'API.

12. Bonnes pratiques

1. Commencez par CLAUDE.md – gardez-le bref mais complet.
2. Développez progressivement les compétences – concentrez-vous sur les motifs à fort impact.
3. Utilisez des hooks pour les tâches répétitives – évitez le linting manuel ou les échecs de test.
4. Créez des agents pour les workflows complexes – par ex., triage de bugs, résumeurs de pull‑requests.
5. Automatisez avec GitHub Actions – programmez des balayages de qualité et des synchronisations de docs.
6. Versionnez votre configuration – engagez tous les fichiers sauf les surcharges personnelles.
7. Sécurisez les données sensibles – utilisez des variables d'environnement et ne pas engager les secrets.
8. Mesurez le coût – exécutez un tableau d'estimation de coût pour maintenir l'utilisation prévisible.

13. Conclusion

Avec cette configuration, votre dépôt est désormais :

• Auto-conscient – Claude comprend la pile, le style et les conventions.
• Automatisé – le formatage de code, les tests et les contrôles qualité s'exécutent automatiquement.
• Connecté – les tickets, PRs et chats s'attachent directement au flux de travail de Claude.
• Extensible – de nouvelles compétences, agents et commandes peuvent être ajoutés en quelques minutes.

Commencez par cloner le dépôt, personnalisez les extraits selon votre pile et laissez Claude devenir le coéquipier que vous ne saviez pas avoir besoin.

Bon codage !