249 lines
12 KiB
Markdown
249 lines
12 KiB
Markdown
# 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/)
|