Le problème
Claude Code comporte cinq couches de contexte distinctes : CLAUDE.md, Rules, Skills, Agents et Hooks. Chacune répond à une question différente. Placez la connaissance dans la mauvaise couche et elle alourdit chaque session, est ignorée, ou ne se déclenche pas au moment voulu.
Cette boussole vous donne un modèle mental pour décider où placer quoi et pourquoi cette couche est la bonne.
Carte d'architecture
Suivez un prompt réel à travers les cinq couches. Nous utiliserons ShopFlow, une boutique e-commerce fictive, pour montrer à quoi ressemble chaque couche en pratique.
Un développeur demande à Claude d'ajouter une page de paiement Stripe...
Arbre de décision
Cliquez pour trouver la bonne couche pour votre connaissance.
J'ai une connaissance ou une consigne que je veux faire utiliser à Claude. De quel type s'agit-il ?
Les 5 couches
Chaque couche a un objectif, un test décisif et des anti-patterns. Dépliez une couche pour voir les détails.
Toujours. La première chose à créer.
L'identité du projet en moins de 200 lignes. Stack technique, commandes de build, structure des fichiers, conventions impossibles à déduire du code.
Définit le contexte de base de chaque session. C'est le README de Claude.
Vous devez encoder des patterns de mise en page, des références d'architecture, des préférences d'outils propres au projet (outils de migration, patterns de test…) ou des liens vers une documentation centrale, surtout dans les grands projets complexes.
Des fichiers .md modulaires dans .claude/rules/. Peuvent être ciblés par chemin via le frontmatter paths:. Peuvent référencer des docs d'architecture externes, des ADR, des pages wiki ou des conventions d'outils choisies pour ce projet.
Les rules relient Claude à votre base de connaissances élargie. Elles encodent les décisions structurelles propres au projet : comment le code est organisé, quels patterns et outils sont privilégiés ici, où trouver les références qui font autorité. Sans alourdir chaque session.
Vous avez une connaissance approfondie d'une technologie, d'un workflow ou d'un domaine que Claude doit consulter quand c'est pertinent.
Des fichiers SKILL.md avec frontmatter. Invoqués automatiquement par correspondance de description, ou manuellement via /nom-de-la-skill.
Chargées à la demande, pas à chaque session. Garde le contexte de base léger tout en rendant l'expertise pointue disponible.
Une tâche récurrente gagne à avoir un persona spécialisé, avec des outils restreints et des skills préchargées.
Des fichiers .md d'agent définissant le rôle, les outils autorisés, les skills préchargées et les consignes de comportement.
L'isolation. Un relecteur de code n'a pas besoin d'accès en écriture. Un chercheur n'a pas besoin d'Edit. Les agents limitent le contexte et les permissions à un rôle.
Vous avez besoin d'une exécution garantie et déterministe, pas d'une consigne consultative.
Des commandes shell déclenchées sur des événements du cycle de vie (PreToolUse, PostToolUse, SessionStart, etc.).
Les rules et CLAUDE.md sont consultatifs. Claude peut les ignorer. Les hooks sont du code qui s'exécute.
Tableau comparatif
Comparaison côte à côte des cinq couches.
| Couche | Portée | Se charge quand ? | Application | Contient |
|---|---|---|---|---|
CLAUDE.md | Projet | Toujours, à chaque session | Consultatif | Identité, conventions |
Rules | Projet / Utilisateur | Toujours ou selon le chemin | Consultatif | Structure, références d'architecture |
Skills | Marketplace | À la demande / auto-détection | Consultatif | Connaissance technique, workflows |
Agents | Marketplace | Quand on lui délègue | Imposé | Rôle, restrictions d'outils |
Hooks | Projet / Utilisateur | Sur événement du cycle de vie | Imposé | Commandes shell |
Projet
Toujours, à chaque session
Identité, conventions
Projet / Utilisateur
Toujours ou selon le chemin
Structure, références d'architecture
Marketplace
À la demande / auto-détection
Connaissance technique, workflows
Marketplace
Quand on lui délègue
Rôle, restrictions d'outils
Projet / Utilisateur
Sur événement du cycle de vie
Commandes shell
Consultatif vs Imposé
Consultatif
Claude devraitClaude les lit et les suit, la plupart du temps. Mais il peut choisir de s'en écarter s'il juge qu'autre chose est préférable.
Imposé
Claude doitIls s'exécutent mécaniquement. Les hooks tournent comme des commandes shell. Les restrictions d'outils des agents sont des limites strictes. Aucune marge d'appréciation.
Hiérarchie des portées
Cliquez sur une portée pour voir ce qu'elle contient. Les portées supérieures priment sur les inférieures.
Les portées supérieures priment sur les inférieures ↓
Skill vs Agent
Skill = le QUOI
La connaissance technologique. Comment fonctionne Playwright ? Quelles sont les bonnes pratiques pour la config Vite ? Comment structurer les pipelines GitLab CI ?
skill playwright : connaît les locators, les fixtures, le Page Object Model, les patterns d'exécution parallèle.
Agent = le QUI
Un spécialiste qui utilise cette connaissance. Il a un persona, des outils restreints et un état d'esprit spécifique. L'agent précharge les skills dont il a besoin.
agent test-writer : précharge la skill playwright + n'a accès en écriture qu'aux fichiers de test + raisonne en cas limites et en isolation.
Si c'est juste de la connaissance sans différence de permissions → Skill
Aide-mémoire de décision rapide
Documentation officielle
Fichiers CLAUDE.md, mémoire automatique, hiérarchie des fichiers et ordre de chargement
Rules ciblées par chemin, frontmatter, liens symboliques, rules au niveau utilisateur
Structure de SKILL.md, frontmatter, auto-invocation, fichiers annexes
Agents personnalisés, restrictions d'outils, préchargement de skills, isolation
Événements de cycle de vie, types de hooks, automatisation déterministe
Patterns pratiques et exemples de configuration des hooks
Permissions, variables d'environnement, hiérarchie des réglages
Distribuer des skills et des agents entre équipes
Patterns de travail pour tirer le meilleur de Claude Code