Maîtrise de Claude Code — Architecture, Skills & Roadmap 4 semaines

🧠 1. Ce qu’est vraiment Claude Code

Claude Code n’est pas un chatbot amélioré. C’est un agent autonome qui exécute des tâches dans votre environnement réel : lire et écrire des fichiers, lancer des commandes, appeler des APIs, orchestrer d’autres agents. Sa puissance vient de la façon dont vous le configurez, pas de la façon dont vous lui parlez.

La différence entre un utilisateur qui « essaie Claude Code » et un utilisateur qui en tire un multiplicateur de productivité réel tient à une seule chose : l’architecture mise en place avant de travailler.

×10

Multiplicateur de productivité visé après 4 semaines

2–4h

Heures récupérées par semaine dès le premier skill automatisé

150

Limite d’instructions dans CLAUDE.md pour rester précis

5

Tests minimum avant de systématiser un skill

💡 Principe fondateur

Tester avant de systématiser. Systématiser avant de scénariser. Ne jamais automatiser ce qu’on ne maîtrise pas encore manuellement. Un skill créé trop tôt sur un processus mal compris produit des résultats incorrects à grande vitesse.

🧬 2. L’anatomie d’un copilote IA

Pour comprendre comment les composants s’articulent, MAGIPA propose une métaphore anatomique. Chaque élément de Claude Code correspond à une fonction biologique précise. C’est la meilleure grille de lecture pour décider quoi construire en premier.

🧠 Le cerveau

CLAUDE.md

Mémoire persistante et permanente. Définit qui est l’IA, comment elle pense, ses règles fondamentales. Lu à chaque session, en priorité absolue.

~/CLAUDE.md

💪 Les muscles

Skills

Workflows réutilisables activés par une commande /skill-name. Chaque skill est un protocole précis pour une tâche récurrente : audit, rédaction, analyse, déploiement.

~/.claude/skills/

⚡ Les réflexes

Hooks

Vérifications automatiques déclenchées avant/après chaque action. Ils protègent contre les erreurs, appliquent des standards sans y penser.

~/.claude/hooks/

🔌 Les sens

Serveurs MCP

Connexions vers le monde extérieur. Notion, Slack, HubSpot, Gmail, bases de données, APIs métier. L’IA perçoit et agit sur des systèmes tiers.

settings.json → mcpServers

🤝 Les membres

Subagents

Travailleurs délégués, chacun spécialisé dans un domaine. L’agent principal orchestre, les subagents exécutent en parallèle.

~/.claude/agents/

⚠ Ordre de construction

Ne pas tout construire en même temps. L’ordre optimal : CLAUDE.md d’abord (cerveau), puis 1 skill testé 5 fois (muscle), puis hooks (réflexes), puis MCP (sens), enfin subagents (membres) quand les bases sont solides.

📋 3. Le cerveau : CLAUDE.md

CLAUDE.md est le fichier le plus important de toute votre configuration. Il est lu en priorité absolue à chaque session. Ce qu’il contient conditionne tout le reste.

Ce que CLAUDE.md doit contenir

Qui vous êtes : rôle, secteur, contraintes spécifiques
Comment l’IA doit se comporter : ton, langue, niveau de détail, ce qu’elle ne doit jamais faire
Vos outils et conventions : stack technique, standards de nommage, chemins importants
Les règles métier non-négociables : sécurité, conformité, processus obligatoires

La règle des 150 instructions

🚫 Ne pas dépasser 150 instructions dans CLAUDE.md

Au-delà de 150 instructions, la précision chute. L’IA commence à « oublier » certaines règles au profit d’autres. Solution : utiliser des @imports pour déléguer les règles spécifiques à des fichiers modulaires. CLAUDE.md reste le noyau dur, les détails sont externalisés.

Structure recommandée avec @imports

CLAUDE.md

# Rôle et identité (5-10 lignes max)

Tu es mon copilote IA spécialisé en [domaine].

Tu travailles pour [contexte métier].

# Règles fondamentales (15-20 règles)

- Ne jamais [action interdite]

- Toujours [comportement attendu]

# Règles spécifiques externalisées

@rules/securite.md

@rules/style-redaction.md

@rules/conventions-code.md

✔ Bonne pratique GiGaRuN

Commencer avec 5 à 10 règles seulement. Ajouter une règle uniquement quand un comportement indésirable s’est manifesté en pratique. Un CLAUDE.md de 200 lignes jamais testé vaut moins qu’un CLAUDE.md de 15 lignes affiné sur 3 mois d’usage réel.

💪 4. Les muscles : créer des skills efficaces

Un skill est un fichier Markdown qui décrit un workflow précis. Il s’active avec /nom-du-skill dans Claude Code. La qualité d’un skill se mesure à sa capacité à produire un résultat cohérent à chaque exécution, sans que vous ayez besoin de réexpliquer le contexte.

Le frontmatter obligatoire

SKILL.md — EN-TÊTE

---

name: /brief-client

description: Génère un brief client complet à partir d’un URL ou nom d’entreprise

tools: [WebSearch, Read, Write] # Whitelist sécurité

model: sonnet # sonnet (standard) ou opus (complexe)

---

⚠ Le champ description est critique

C’est lui qui détermine si Claude Code propose automatiquement le skill dans le bon contexte. Une description vague (« fait des trucs ») = skill jamais proposé spontanément. Une description précise = skill activé au bon moment.

Le framework en 5 blocs obligatoires

Tout skill efficace contient exactement ces 5 blocs, dans cet ordre :

INPUTS — Ce dont le skill a besoin Les informations obligatoires avant de démarrer. Si un input manque, le skill demande explicitement avant de continuer. Ex : URL du client, nom du projet, type de prestation.
STEPS — Les étapes numérotées Actions précises, dans l’ordre, vérifiables. Chaque étape doit être observable : soit ça produit un fichier, soit ça affiche un résultat, soit ça attend une confirmation.
OUTPUT — Le format exact attendu Spécifier le format de sortie : Markdown, JSON, tableau, PDF, email. La longueur, les sections, la langue. Sans format défini, chaque exécution donne un résultat différent.
SELF-CHECK — 3 à 5 critères de vérification L’IA vérifie elle-même son travail avant de livrer. Ex : « Le brief contient-il un budget estimé ? », « Tous les contacts identifiés sont-ils vérifiables ? »
DEFINITION OF DONE — La condition de fin Quand le skill est-il terminé ? Une condition claire évite les livraisons partielles et les boucles infinies. Ex : « Fichier brief-[client].md créé dans le dossier courant ».

Règles de création

Tester le skill minimum 5 fois avec des cas différents avant de le considérer stable
Un skill = une tâche. Ne pas essayer de tout faire dans un seul skill
Nommer les skills avec des verbes d’action : /audit-securite, /rediger-proposition, /analyser-logs
Si un skill prend > 5 minutes à exécuter, le découper en sous-skills chaînés

Où trouver des skills existants

Source	Description
`skillhub.club`	Plus de 7 000 skills classés par domaine
`ayclaude.com`	Skills curés par la communauté
`awesomeclaude.ai`	Ressources sélectionnées
`hesreallyhim/awesome-claude-code`	Repo GitHub, liste maintenue par la communauté
docs.anthropic.com/claude-code/skills	Documentation officielle Anthropic

⚡ 5. Les réflexes : hooks automatiques

Les hooks sont des scripts qui s’exécutent automatiquement avant ou après certaines actions de Claude Code. Ils fonctionnent indépendamment de l’IA — ce sont des gardes-fous système.

Les deux types de hooks

Type	Déclenchement	Usage typique
PreToolUse	Avant qu’un outil soit utilisé	Bloquer une suppression critique, valider un paramètre, demander confirmation
Stop	Après la fin d’une session	Analyser la session, générer un rapport, rappeler de faire un handoff

Exemple : hook de protection contre les suppressions

~/.claude/hooks/protect-delete.py — PreToolUse

# Bloquer rm -rf sur des dossiers critiques

import sys, json

data = json.load(sys.stdin)

cmd = data.get("tool_input", {}).get("command", "")

protected = ["~/.claude", "~/Exocortex", "/prod"]

if "rm -rf" in cmd and any(p in cmd for p in protected):

print(json.dumps({"decision": "block", "reason": "Dossier protégé"}))

💡 Règle d’ordre

Installer les hooks après avoir maîtrisé les skills (semaine 3 dans la roadmap). Un hook mal configuré peut bloquer des actions légitimes. Les comprendre avant de les déployer.

🔌 6. Les sens : serveurs MCP

Les serveurs MCP (Model Context Protocol) connectent Claude Code à des systèmes externes. L’IA peut alors lire et écrire dans Notion, envoyer des emails via Gmail, requêter une base de données, appeler une API métier.

Configuration dans settings.json

~/.claude/settings.json

{

"mcpServers": {

"n8n": {

"command": "npx",

"args": ["-y", "n8n-mcp"],

"env": { "N8N_API_URL": "https://votre-n8n.example.com" }

}

Exemples d’intégrations utiles

MCP Server	Ce que ça permet	Pertinence GiGaRuN
`n8n-mcp`	Créer et gérer des workflows n8n depuis Claude Code	⭐ Haute
Ahrefs MCP	Analyse SEO, mots-clés, backlinks en temps réel	⭐ Haute
Microsoft 365 MCP	Lecture emails Outlook, calendrier, SharePoint	⭐ Haute
GitHub MCP	Issues, PRs, repos directement dans le workflow	⭐ Haute
PostgreSQL MCP	Requêtes SQL sur base de données	Moyenne
Slack MCP	Envoyer des messages, lire des canaux	Moyenne

🚨 Sécurité MCP — lire le code avant d’installer

Un serveur MCP tourne avec les droits de votre session. Il peut lire vos fichiers et vos clés API. Ne jamais installer un MCP tiers sans avoir lu son code source en entier. Voir le guide GitHub & Claude Code pour la procédure complète.

🤝 7. Les membres : subagents

Les subagents sont des agents spécialisés qui travaillent en parallèle, chacun dans son domaine. L’agent principal orchestre, les subagents exécutent. C’est ce qui permet de passer des tâches séquentielles aux tâches parallèles.

Structure d’un subagent

~/.claude/agents/analyste-securite.md

---

name: analyste-securite

description: Analyse les vulnérabilités et produit des rapports de sécurité

tools: [Bash, Read, Write] # Jamais de suppression

---

# Rôle

Tu es un analyste sécurité spécialisé en pentest applicatif.

# Scope (ce que tu NE fais PAS)

Tu n’exécutes jamais d’exploit sans validation explicite.

Tu ne supprimes aucun fichier.

⚠ Subagents : étape finale

Ne pas créer de subagents avant d’avoir des skills stables. Un subagent qui orchestre des skills non maîtrisés produit des résultats imprévisibles. Les subagents amplifient — le bon comme le mauvais.

🗺 8. Roadmap 4 semaines

Une progression structurée qui évite les erreurs classiques : partir trop vite, trop complexe, sans fondations solides.

🔹 Semaine 1 — Fondations

Lancer /init dans Claude Code
Créer CLAUDE.md avec 5–10 règles seulement
Identifier 3 tâches répétitives dans votre semaine
Construire et tester 1 skill (5 exécutions minimum)

🟢 Semaine 2 — Contexte

Organiser la hiérarchie mémoire
Créer des règles modulaires (@imports)
Connecter votre premier serveur MCP
Ajouter 1 ou 2 skills supplémentaires

🟠 Semaine 3 — Qualité

Activer un hook Stop (analyse de session)
Installer un hook PreToolUse (protection)
Chaîner deux skills existants
Adapter des skills communautaires à votre contexte

🟣 Semaine 4 — Composition

Activer /learn (auto-apprentissage)
Activer /review (contrôle qualité)
Dupliquer et adapter des skills éprouvés
Créer votre premier subagent

✔ Après 4 semaines

Vous devriez avoir : 5–10 skills opérationnels, 1–2 hooks actifs, 1 MCP connecté, et 2–4 heures par semaine récupérées. C’est la base sur laquelle le multiplicateur de productivité s’accumule.

❌ 9. Les 10 anti-patterns à éviter

Ces erreurs sont commises par la majorité des nouveaux utilisateurs. Les connaître à l’avance évite des semaines de frustration.

1

CLAUDE.md trop chargé Plus de 150 instructions = perte de précision. Moins c’est plus. Externaliser dans des fichiers modulaires via @imports.
2

Automatiser sans maîtriser le processus manuel Créer un skill sur un processus qu’on ne fait jamais manuellement. Résultat : des erreurs à grande vitesse, impossibles à détecter.
3

Skills sans format de sortie défini Sans spécification de l’output, chaque exécution donne un résultat différent. Un skill sans format n’est pas un skill, c’est un prompt.
4

Tester un skill une seule fois Un skill validé sur un seul cas peut échouer sur tous les autres. Tester minimum 5 fois avec des entrées variées avant de le considérer stable.
5

Installer des MCP sans lire le code Un serveur MCP malveillant peut exfiltrer vos clés API et vos fichiers. Lire le code source en entier, sans exception.
6

Construire les subagents avant les skills Les subagents amplifient ce qui est en dessous. Sans skills maîtrisés, ils amplifient le chaos.
7

Skills trop génériques Un skill /analyser qui fait tout ne fait rien bien. Plus le périmètre est précis, plus le résultat est fiable.
8

Copier-coller des skills sans les adapter Un skill créé pour un autre contexte métier ne fonctionnera pas dans le vôtre. Toujours adapter au moins le contexte, les exemples et le format de sortie.
9

Ignorer la hiérarchie mémoire Mettre toutes les informations dans CLAUDE.md alors qu’elles appartiennent à la mémoire de projet (.claude/) ou de session. Le bon niveau au bon endroit.
10

Construire sans mesurer Ajouter des skills, des hooks, des agents sans vérifier si ça change vraiment les résultats. Mesurer le temps récupéré chaque semaine pour savoir ce qui vaut vraiment le coup.

🔗 10. Ressources et références

Documentation officielle Anthropic

Page	Contenu
docs.anthropic.com/claude-code/skills	Création et structure des skills
docs.anthropic.com/claude-code/hooks	Configuration des hooks PreToolUse et Stop
docs.anthropic.com/claude-code/memory	Hiérarchie mémoire : session, projet, utilisateur
docs.anthropic.com/claude-code/sub-agents	Création et orchestration de subagents

Guides GiGaRuN complémentaires

Exocortex Bootstrap — Réinstallation complète sur nouvelle machine
GitHub & Claude Code — Évaluer et installer des repos sans risque
Multi-Agents & Ollama — Architecture multi-agents 100 % locale
Exocortex IA — Guide complet du copilote métier

Source de ce guide

Ce guide est une adaptation du travail pédagogique de MAGIPA. La source originale, avec les templates téléchargeables (playbook PDF 4 semaines) et les options de coaching, est disponible sur claudecode.magipa.fr. GiGaRuN a enrichi le contenu de son propre retour d’expérience terrain (Exocortex, lab-test, déploiements clients).

Claude Code CLAUDE.md Skills Hooks MCP Servers Subagents Roadmap Productivité

Maîtriser Claude Code

📋 Sommaire

🧠 1. Ce qu’est vraiment Claude Code

🧬 2. L’anatomie d’un copilote IA

CLAUDE.md

Skills

Hooks

Serveurs MCP

Subagents

📋 3. Le cerveau : CLAUDE.md

Ce que CLAUDE.md doit contenir

La règle des 150 instructions

Structure recommandée avec @imports

💪 4. Les muscles : créer des skills efficaces

Le frontmatter obligatoire

Le framework en 5 blocs obligatoires

Règles de création

Où trouver des skills existants

⚡ 5. Les réflexes : hooks automatiques

Les deux types de hooks

Exemple : hook de protection contre les suppressions

🔌 6. Les sens : serveurs MCP

Configuration dans settings.json

Exemples d’intégrations utiles

🤝 7. Les membres : subagents

Structure d’un subagent

🗺 8. Roadmap 4 semaines

🔹 Semaine 1 — Fondations

🟢 Semaine 2 — Contexte

🟠 Semaine 3 — Qualité

🟣 Semaine 4 — Composition

❌ 9. Les 10 anti-patterns à éviter

🔗 10. Ressources et références

Documentation officielle Anthropic

Guides GiGaRuN complémentaires

Source de ce guide