Rules, agents et hooks : à quoi ils servent et où les placer

Les rules, les agents et les hooks sont trois façons d'encadrer un agent de code sans retaper vos consignes à chaque session. Les rules disent comment travailler, les agents (ou sous-agents) délèguent une tâche à un assistant spécialisé, les hooks lancent vos propres commandes à des moments précis. Chaque outil les place à son endroit.

Les rules : des consignes qui restent

Une rule est un fichier de texte que l'agent lit au début du travail : conventions de code, commandes de test, choses à ne jamais modifier. Elle s'applique tout le temps, ou seulement pour certains fichiers.

• Claude Code : CLAUDE.md à la racine du projet (ou .claude/CLAUDE.md), ~/.claude/CLAUDE.md pour vos préférences personnelles, CLAUDE.local.md pour vos réglages locaux. Pour découper en plusieurs fichiers, utilisez le dossier .claude/rules/, dont les fichiers peuvent être limités à certains chemins.
• Cursor : fichiers .mdc dans .cursor/rules/. Un simple .md placé dans ce dossier est ignoré. L'en-tête du fichier fixe quand la rule s'applique : alwaysApply, globs (motif de fichiers) ou description (l'agent juge si elle est utile).
• Codex : AGENTS.md, global dans ~/.codex/, puis à la racine du dépôt et dans les sous-dossiers. Les fichiers les plus proches du dossier de travail passent en dernier et priment. Codex arrête la lecture à 32 Kio cumulés par défaut.

AGENTS.md sert de fichier commun : Cursor le lit à la racine et dans les sous-dossiers, et Claude Code le lit comme instructions de projet. Si votre dépôt a déjà un CLAUDE.md, ajoutez-y @AGENTS.md pour importer le fichier partagé, puis vos consignes propres à Claude en dessous.

Les agents : un assistant spécialisé

Un sous-agent est un assistant qui travaille dans son propre contexte, avec ses consignes et ses outils limités, puis ne renvoie qu'un résumé. Il évite d'encombrer la conversation principale avec des recherches ou des journaux. Vous en définissez un quand vous confiez souvent le même type de tâche (relecture, débogage, requêtes en lecture seule).

• Claude Code : un fichier Markdown avec en-tête YAML (name, description, souvent tools et model) dans .claude/agents/ pour le projet, ou ~/.claude/agents/ pour tous vos projets. Claude choisit de déléguer d'après la description : gardez-la courte et précise.
• Cursor : fichiers Markdown dans .cursor/agents/ ou ~/.cursor/agents/. Cursor lit aussi .claude/agents/, par compatibilité.
• Codex : fichiers TOML dans .codex/agents/ ou ~/.codex/agents/, avec name, description et developer_instructions. Codex délègue quand vous le demandez, ou quand un AGENTS.md ou une skill le prévoit.

Les hooks : vos commandes à des moments précis

Un hook exécute une action quand un événement se produit : avant ou après un outil, au démarrage d'une session, quand l'agent a fini de répondre. Il sert à bloquer une commande dangereuse, à lancer un formateur après chaque modification ou à journaliser ce que fait l'agent.

Dans Claude Code, les hooks se déclarent dans les fichiers de réglages : .claude/settings.json (projet, partageable), .claude/settings.local.json (local) ou ~/.claude/settings.json (tous vos projets). Exemple : bloquer certaines commandes Bash avec un script que vous écrivez et relisez.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh" }
        ]
      }
    ]
  }
}

Le script reçoit les données de l'événement en JSON sur son entrée standard. Il répond par son code de sortie : 0 ne s'oppose à rien, 2 bloque l'action et son message d'erreur est transmis à Claude. La commande /hooks liste ceux qui sont configurés.

Cursor lit .cursor/hooks.json (projet) ou ~/.cursor/hooks.json (utilisateur), avec des événements comme beforeShellExecution ou afterFileEdit. Pour Codex, reportez-vous à sa documentation officielle.

Quelle différence avec une skill ?

Une rule et une skill sont du texte que le modèle lit. Un hook, lui, est du code qui tourne à côté du modèle. Pour la même idée en détail, voyez Ressource ou simple prompt ? et le catalogue des rules.

Précautions avec les hooks

Un hook de commande s'exécute sur votre machine, avec vos droits, sans que vous le validiez à chaque fois. Traitez-le comme un script.

• Lisez la commande et le script en entier avant de l'activer, surtout s'ils viennent d'un tiers.
• Méfiez-vous des hooks de projet : ils sont versionnés avec le dépôt. Cursor le signale lui-même, ses hooks de projet s'exécutent dans tout espace de travail approuvé. Relisez .claude/settings.json et .cursor/hooks.json après avoir cloné un dépôt inconnu.
• Commencez par un hook qui ne fait que journaliser, puis ajoutez les blocages.
• Pour appliquer une interdiction stricte, préférez les règles de permissions de l'outil : la documentation de Claude Code précise que le filtrage d'un hook est approximatif.
• Les hooks de la même étape s'exécutent en parallèle. Un deny n'empêche pas les effets d'un autre hook.

Le catalogue n'accepte pas les ressources tierces qui livrent des scripts (seules les ressources maison de PalateKit en contiennent, écrits et relus par nous), et installer une ressource PalateKit ne lance rien. Pour le reste de la démarche, lisez Sécurité : lire une skill avant de l'installer.