# 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/`).

<table width="100%">
<tr>
<td><a href="../">← Retour à Claude Code Best Practice</a></td>
<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
</tr>
</table>

## Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Fonctionnalités globales uniquement](#fonctionnalités-globales-uniquement)
3. [Fonctionnalités à double portée](#fonctionnalités-à-double-portée)
4. [Priorité des paramètres](#priorité-des-paramètres)
5. [Comparaison de la structure de répertoires](#comparaison-de-la-structure-de-répertoires)
6. [Système de tâches](#système-de-tâches)
7. [Équipes d'agents](#équipes-dagents)
8. [Principes de conception](#principes-de-conception)
9. [Sources](#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

```bash
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

```json
// 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.

---

## Sources

- [Documentation des paramètres Claude Code](https://code.claude.com/docs/en/settings)
- [Orchestrer des équipes de sessions Claude Code](https://code.claude.com/docs/en/agent-teams)
- [What are Tasks in Claude Code - ClaudeLog](https://claudelog.com/faqs/what-are-tasks-in-claude-code/)
- [Claude Code Task Management - ClaudeFast](https://claudefa.st/blog/guide/development/task-management)
- [Claude Code Tasks Update - VentureBeat](https://venturebeat.com/orchestration/claude-codes-tasks-update-lets-agents-work-longer-and-coordinate-across)
- [Where Are Claude Code Global Settings - ClaudeLog](https://claudelog.com/faqs/where-are-claude-code-global-settings/)
- [Claude Opus 4.6 Agent Teams - VentureBeat](https://venturebeat.com/technology/anthropics-claude-opus-4-6-brings-1m-token-context-and-agent-teams-to-take)
- [How to Set Up Claude Code Agent Teams (Full Walkthrough) - r/ClaudeCode](https://www.reddit.com/r/ClaudeCode/comments/1qz8tyy/how_to_set_up_claude_code_agent_teams_full/)
- [Anthropic replaced Claude Code's old 'Todos' with Tasks - r/ClaudeAI](https://www.reddit.com/r/ClaudeAI/comments/1qkjznp/anthropic_replaced_claude_codes_old_todos_with/)