Files

T

2026-06-02 23:24:21 +02:00

12 KiB

Raw Permalink Blame History

Claude Code : Fonctionnalités globales vs au niveau projet

Une comparaison complète des fonctionnalités de Claude Code qui sont exclusivement globales (~/.claude/) par rapport à celles qui ont à la fois un équivalent global et un équivalent au niveau projet (.claude/).

← Retour à Claude Code Best Practice

Table des matières

Vue d'ensemble
Fonctionnalités globales uniquement
Fonctionnalités à double portée
Priorité des paramètres
Comparaison de la structure de répertoires
Système de tâches
Équipes d'agents
Principes de conception
Sources

Vue d'ensemble

Claude Code utilise une hiérarchie de portées où certaines fonctionnalités existent à la fois au niveau global (~/.claude/) et projet (.claude/), tandis que d'autres sont exclusivement globales. Le principe de conception : ce qui est état personnel ou coordination inter-projets vit globalement ; ce qui est config projet partageable en équipe peut vivre au niveau projet.

~/.claude/ est ton home au niveau utilisateur (global, tous projets)
.claude/ à l'intérieur d'un dépôt est ton home au niveau projet (limité à ce projet)

Fonctionnalités globales uniquement

Celles-ci vivent uniquement sous ~/.claude/ et ne peuvent être limitées à un projet :

Fonctionnalité	Emplacement	Objectif
Tâches	`~/.claude/tasks/`	Listes de tâches persistantes entre sessions et agents
Équipes d'agents	`~/.claude/teams/`	Configs de coordination multi-agents (expérimental, févr. 2026)
Auto-mémoire	`~/.claude/projects/<hash>/memory/`	Apprentissages auto-écrits par Claude par projet (personnels, jamais partagés)
Identifiants & OAuth	Trousseau système + `~/.claude.json`	Clés API, tokens OAuth (jamais dans les fichiers de projet)
Raccourcis clavier	`~/.claude/keybindings.json`	Raccourcis clavier personnalisés
Serveurs MCP utilisateur	`~/.claude.json` (clé `mcpServers`)	Serveurs MCP personnels sur tous les projets
Préférences/Cache	`~/.claude.json`	Thème, modèle, style de sortie, état de session

Fonctionnalités à double portée

Celles-ci existent aux deux niveaux, le niveau projet prenant le pas sur le global :

Fonctionnalité	Global (`~/.claude/`)	Projet (`.claude/`)	Priorité
CLAUDE.md	`~/.claude/CLAUDE.md`	`./CLAUDE.md` ou `.claude/CLAUDE.md`	Projet surcharge global
Paramètres	`~/.claude/settings.json`	`.claude/settings.json` + `.claude/settings.local.json`	Projet > Global
Règles	`~/.claude/rules/*.md`	`.claude/rules/*.md`	Projet surcharge
Agents/Sous-agents	`~/.claude/agents/*.md`	`.claude/agents/*.md`	Projet surcharge
Commandes	`~/.claude/commands/*.md`	`.claude/commands/*.md`	Les deux disponibles
Skills	`~/.claude/skills/`	`.claude/skills/`	Les deux disponibles
Hooks	`~/.claude/hooks/`	`.claude/hooks/`	Les deux s'exécutent
Serveurs MCP	`~/.claude.json` (portée utilisateur)	`.mcp.json` (portée projet)	Trois portées : local > projet > utilisateur

Priorité des paramètres

Les paramètres modifiables par l'utilisateur s'appliquent dans cet ordre de surcharge (du plus élevé au plus bas) :

Priorité	Emplacement	Portée	Versionné	Objectif
1	Drapeaux en ligne de commande	Session	N/A	Surcharges sur une seule session
2	`.claude/settings.local.json`	Projet	Non (git-ignored)	Personnel, spécifique au projet
3	`.claude/settings.json`	Projet	Oui (committé)	Paramètres partagés en équipe
4	`~/.claude/settings.local.json`	Utilisateur	N/A	Surcharges globales personnelles
5	`~/.claude/settings.json`	Utilisateur	N/A	Paramètres personnels globaux

Couche de politique : managed-settings.json est imposé par l'organisation et ne peut être surchargé par les fichiers locaux.

Important : les règles deny ont la priorité de sécurité la plus élevée et ne peuvent être surchargées par des règles allow/ask de priorité inférieure.

Comparaison de la structure de répertoires

Portée globale (`~/.claude/`)

~/.claude/
├── settings.json              # Paramètres au niveau utilisateur (tous projets)
├── settings.local.json        # Surcharges personnelles
├── CLAUDE.md                  # Mémoire utilisateur (tous projets)
├── agents/                    # Sous-agents utilisateur (disponibles pour tous les projets)
│   └── *.md
├── rules/                     # Règles modulaires au niveau utilisateur
│   └── *.md
├── commands/                  # Commandes au niveau utilisateur
│   └── *.md
├── skills/                    # Skills au niveau utilisateur
│   └── */SKILL.md
├── tasks/                     # GLOBAL UNIQUEMENT : Listes de tâches
│   └── {task-list-id}/
├── teams/                     # GLOBAL UNIQUEMENT : Configs d'équipes d'agents
│   └── {team-name}/
│       └── config.json
├── projects/                  # GLOBAL UNIQUEMENT : Auto-mémoire par projet
│   └── {project-hash}/
│       └── memory/
│           ├── MEMORY.md
│           └── *.md
├── keybindings.json           # GLOBAL UNIQUEMENT : Raccourcis clavier
└── hooks/                     # Hooks au niveau utilisateur
    ├── scripts/
    └── config/

~/.claude.json                 # GLOBAL UNIQUEMENT : Serveurs MCP, OAuth, préférences, caches

Portée projet (`.claude/`)

.claude/
├── settings.json              # Paramètres partagés en équipe
├── settings.local.json        # Surcharges projet personnelles (git-ignored)
├── CLAUDE.md                  # Mémoire projet (alternative à ./CLAUDE.md)
├── agents/                    # Sous-agents projet
│   └── *.md
├── rules/                     # Règles modulaires au niveau projet
│   └── *.md
├── commands/                  # Commandes slash personnalisées
│   └── *.md
├── skills/                    # Skills personnalisés
│   └── {skill-name}/
│       ├── SKILL.md
│       └── supporting-files/
├── hooks/                     # Hooks au niveau projet
│   ├── scripts/
│   └── config/
└── plugins/                   # Plugins installés

.mcp.json                      # Serveurs MCP de portée projet (racine du dépôt)

Système de tâches

Introduit dans Claude Code v2.1.16 (22 janvier 2026), remplaçant le système TodoWrite déprécié.

Stockage

Les tâches sont stockées dans ~/.claude/tasks/ sur le système de fichiers local (pas dans une base de données cloud). Cela rend l'état des tâches auditable, versionnable et récupérable après crash.

Outils

Outil	Objectif
TaskCreate	Créer une nouvelle tâche avec `subject`, `description` et `activeForm`
TaskGet	Récupérer les détails complets d'une tâche spécifique par ID
TaskUpdate	Changer le statut, définir le propriétaire, ajouter des dépendances ou supprimer
TaskList	Lister toutes les tâches avec leur statut actuel

Cycle de vie d'une tâche

pending  →  in_progress  →  completed

Gestion des dépendances

Les tâches peuvent en bloquer d'autres via addBlockedBy/addBlocks, créant des graphes de dépendances qui empêchent une exécution prématurée.

Collaboration multi-session

CLAUDE_CODE_TASK_LIST_ID=my-project-tasks claude

Toutes les sessions partageant le même ID voient les mises à jour de tâches en temps réel, permettant des flux de travail parallèles et la reprise de session.

Différences clés avec les anciens Todos

Fonctionnalité	Anciens Todos	Nouvelles Tâches
Portée	Session unique	Inter-session, inter-agent
Dépendances	Aucune	Graphe de dépendances complet
Stockage	En mémoire uniquement	Système de fichiers (`~/.claude/tasks/`)
Persistance	Perdue à la fin de session	Survit aux redémarrages et crashs
Multi-session	Impossible	Via `CLAUDE_CODE_TASK_LIST_ID`

Équipes d'agents

Annoncées le 5 février 2026 comme fonctionnalité expérimentale. Les équipes d'agents permettent à plusieurs sessions Claude Code de se coordonner sur un travail partagé.

Activation

// Dans ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Configuration

Les configs d'équipe vivent dans ~/.claude/teams/{team-name}/ et supportent des modes :

Mode	Description	Prérequis
In-process (défaut)	Tous les coéquipiers tournent dans ton terminal	Aucun
Panneaux divisés	Chaque coéquipier obtient son propre panneau	tmux ou iTerm2 (pas le terminal VS Code)

Principes de conception

Le partage globales-uniquement vs double-portée suit un schéma clair :

Catégorie	Portée	Justification
État de coordination (tâches, équipes)	Global uniquement	Doit persister au-delà de tout projet unique
État de sécurité (identifiants, OAuth)	Global uniquement	Empêche les commits accidentels dans le versioning
Apprentissage personnel (auto-mémoire)	Global uniquement	Propre à l'utilisateur, non partageable en équipe
Préférences de saisie (raccourcis clavier)	Global uniquement	Mémoire musculaire de l'utilisateur, non spécifique au projet
Configuration (paramètres, règles, agents)	Les deux niveaux	Les équipes ont besoin de partager un comportement spécifique au projet
Définitions de workflow (commandes, skills)	Les deux niveaux	Peuvent être personnelles ou partagées en équipe

L'auto-mémoire (~/.claude/projects/<hash>/memory/) est un hybride notable : elle est à propos d'un projet spécifique mais stockée globalement car elle représente un apprentissage personnel plutôt qu'une configuration partageable en équipe.

12 KiB Raw Permalink Blame History