traduction
This commit is contained in:
@@ -0,0 +1,420 @@
|
||||
# Patterns d'usage avancé des outils de Claude
|
||||
|
||||
Fonctionnalités au niveau API (désormais GA) qui réduisent la consommation de tokens, la latence et améliorent la précision des outils. Sorties avec Opus/Sonnet 4.6.
|
||||
|
||||
<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. [Appels d'outils programmatiques (PTC)](#appels-doutils-programmatiques-ptc)
|
||||
3. [Filtrage dynamique pour Web Search/Fetch](#filtrage-dynamique-pour-web-searchfetch)
|
||||
4. [Outil de recherche d'outils (Tool Search Tool)](#outil-de-recherche-doutils-tool-search-tool)
|
||||
5. [Exemples d'usage d'outils (Tool Use Examples)](#exemples-dusage-doutils-tool-use-examples)
|
||||
6. [Pertinence pour Claude Code](#pertinence-pour-claude-code)
|
||||
|
||||
---
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
| Fonctionnalité | Problème résolu | Économie de tokens | Disponibilité |
|
||||
|---------|---------------|---------------|--------------|
|
||||
| Appels d'outils programmatiques | Les boucles d'agent multi-étapes brûlent des tokens en allers-retours | ~37% de réduction | API, Foundry (GA) |
|
||||
| Filtrage dynamique | Les résultats de web search/fetch gonflent le contexte de contenu non pertinent | ~24% de tokens d'entrée en moins | API, Foundry (GA) |
|
||||
| Tool Search Tool | Trop de définitions d'outils gonflent le contexte | ~85% de réduction | API, Foundry (GA) |
|
||||
| Tool Use Examples | Le schéma seul ne peut exprimer les patterns d'usage | 72% → 90% de précision | API, Foundry (GA) |
|
||||
|
||||
Toutes les fonctionnalités sont **disponibles en général (GA)** depuis le 18 février 2026.
|
||||
|
||||
**Empilement stratégique** — commence par ton plus gros goulot d'étranglement :
|
||||
- Gonflement du contexte par les définitions d'outils → Tool Search Tool
|
||||
- Gros résultats intermédiaires → Appels d'outils programmatiques
|
||||
- Bruit de web search → Filtrage dynamique
|
||||
- Erreurs de paramètres → Tool Use Examples
|
||||
|
||||
---
|
||||
|
||||
## Appels d'outils programmatiques (PTC)
|
||||
|
||||
<img src="../../reports/assets/programmatic-tool-calling-diagram.svg" alt="Diagramme PTC — Appels d'outils traditionnels vs programmatiques" width="100%" />
|
||||
|
||||
### Le changement de paradigme
|
||||
|
||||
**Avant (appels d'outils traditionnels) :**
|
||||
```
|
||||
Prompt utilisateur → Claude → Appel d'outil 1 → Réponse 1 → Claude → Appel d'outil 2 → Réponse 2 → Claude → Appel d'outil 3 → Réponse 3 → Claude → Réponse finale
|
||||
```
|
||||
Chaque appel d'outil requiert un aller-retour complet du modèle. 3 outils = 3 passes d'inférence.
|
||||
|
||||
**Après (appels d'outils programmatiques) :**
|
||||
```
|
||||
Prompt utilisateur → Claude → écrit un script Python → Le script appelle Outil 1, Outil 2, Outil 3 en interne → stdout → Claude → Réponse finale
|
||||
```
|
||||
Claude écrit du code qui orchestre tous les outils. Seul le `stdout` final entre dans la fenêtre de contexte. 3 outils = 1 passe d'inférence.
|
||||
|
||||
### Comment ça fonctionne
|
||||
|
||||
1. Tu définis des outils avec `allowed_callers: ["code_execution_20250825"]`
|
||||
2. Claude écrit du Python qui appelle ces outils comme des fonctions async dans un sandbox
|
||||
3. Quand une fonction d'outil est appelée, le sandbox se met en pause et l'API renvoie un bloc `tool_use`
|
||||
4. Tu fournis le résultat de l'outil — il va au **code en cours d'exécution**, pas au contexte de Claude
|
||||
5. Le code reprend, traite les résultats, appelle d'autres outils si besoin
|
||||
6. Seul le `stdout` de l'exécution finale atteint Claude
|
||||
|
||||
### Configuration clé
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "code_execution_20250825",
|
||||
"name": "code_execution"
|
||||
},
|
||||
{
|
||||
"name": "query_database",
|
||||
"description": "Execute a SQL query. Returns rows as JSON objects with fields: id (str), name (str), revenue (float).",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"sql": { "type": "string", "description": "SQL query to execute" }
|
||||
},
|
||||
"required": ["sql"]
|
||||
},
|
||||
"allowed_callers": ["code_execution_20250825"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Le champ `allowed_callers`
|
||||
|
||||
| Valeur | Comportement |
|
||||
|-------|----------|
|
||||
| `["direct"]` | Appels d'outils traditionnels uniquement (défaut si omis) |
|
||||
| `["code_execution_20250825"]` | Appelable uniquement depuis le sandbox Python |
|
||||
| `["direct", "code_execution_20250825"]` | Les deux modes disponibles |
|
||||
|
||||
**Recommandation :** Choisis un seul mode par outil, pas les deux. Cela donne à Claude un guidage plus clair.
|
||||
|
||||
### Le champ `caller` dans les réponses
|
||||
|
||||
Chaque bloc d'usage d'outil inclut un champ `caller` pour que tu saches comment il a été invoqué :
|
||||
|
||||
```json
|
||||
// Direct (traditionnel)
|
||||
{ "caller": { "type": "direct" } }
|
||||
|
||||
// Programmatique (depuis l'exécution de code)
|
||||
{ "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc123" } }
|
||||
```
|
||||
|
||||
### Patterns avancés
|
||||
|
||||
**Traitement par lots** — traiter N éléments en 1 passe d'inférence :
|
||||
```python
|
||||
regions = ["West", "East", "Central", "North", "South"]
|
||||
results = {}
|
||||
for region in regions:
|
||||
data = await query_database(f"SELECT SUM(revenue) FROM sales WHERE region='{region}'")
|
||||
results[region] = data[0]["revenue"]
|
||||
|
||||
top = max(results.items(), key=lambda x: x[1])
|
||||
print(f"Top region: {top[0]} with ${top[1]:,}")
|
||||
```
|
||||
|
||||
**Terminaison anticipée** — s'arrêter dès que les critères de succès sont remplis :
|
||||
```python
|
||||
endpoints = ["us-east", "eu-west", "apac"]
|
||||
for endpoint in endpoints:
|
||||
status = await check_health(endpoint)
|
||||
if status == "healthy":
|
||||
print(f"Found healthy endpoint: {endpoint}")
|
||||
break
|
||||
```
|
||||
|
||||
**Sélection conditionnelle d'outil :**
|
||||
```python
|
||||
file_info = await get_file_info(path)
|
||||
if file_info["size"] < 10000:
|
||||
content = await read_full_file(path)
|
||||
else:
|
||||
content = await read_file_summary(path)
|
||||
print(content)
|
||||
```
|
||||
|
||||
**Filtrage de données** — réduire ce que Claude voit :
|
||||
```python
|
||||
logs = await fetch_logs(server_id)
|
||||
errors = [log for log in logs if "ERROR" in log]
|
||||
print(f"Found {len(errors)} errors")
|
||||
for error in errors[-10:]:
|
||||
print(error)
|
||||
```
|
||||
|
||||
### Compatibilité des modèles
|
||||
|
||||
| Modèle | Supporté |
|
||||
|-------|-----------|
|
||||
| Claude Opus 4.6 | Oui |
|
||||
| Claude Sonnet 4.6 | Oui |
|
||||
| Claude Sonnet 4.5 | Oui |
|
||||
| Claude Opus 4.5 | Oui |
|
||||
|
||||
### Contraintes
|
||||
|
||||
| Contrainte | Détail |
|
||||
|-----------|--------|
|
||||
| **Pas sur Bedrock/Vertex** | API et Foundry uniquement |
|
||||
| **Pas d'outils MCP** | Les outils de connecteur MCP ne peuvent être appelés programmatiquement |
|
||||
| **Pas de web search/fetch** | Les outils web ne sont pas supportés en PTC |
|
||||
| **Pas de sorties structurées** | Outils `strict: true` incompatibles |
|
||||
| **Pas de choix d'outil forcé** | `tool_choice` ne peut forcer le PTC |
|
||||
| **Durée de vie du conteneur** | ~4,5 minutes avant expiration |
|
||||
| **ZDR** | Non couvert par le Zero Data Retention |
|
||||
| **Résultats d'outils sous forme de chaînes** | Valide les résultats externes contre les risques d'injection de code |
|
||||
|
||||
### Quand utiliser le PTC
|
||||
|
||||
| Bons cas d'usage | Moins idéal |
|
||||
|----------------|------------|
|
||||
| Traiter de grands jeux de données nécessitant des agrégats | Appels d'outil unique avec réponses simples |
|
||||
| 3+ appels d'outils dépendants en séquence | Outils nécessitant un retour utilisateur immédiat |
|
||||
| Filtrer/transformer les résultats avant que Claude ne les voie | Opérations très rapides (surcoût > bénéfice) |
|
||||
| Opérations parallèles sur de nombreux éléments | |
|
||||
| Logique conditionnelle basée sur des résultats intermédiaires | |
|
||||
|
||||
### Efficacité en tokens
|
||||
|
||||
- Les résultats d'outils issus d'appels programmatiques ne sont **pas ajoutés au contexte de Claude** — seul le `stdout` final
|
||||
- Le traitement intermédiaire se passe dans le code, pas en tokens de modèle
|
||||
- 10 outils en programmatique ≈ 1/10ᵉ des tokens de 10 appels directs
|
||||
|
||||
---
|
||||
|
||||
## Filtrage dynamique pour Web Search/Fetch
|
||||
|
||||
### Le problème
|
||||
|
||||
Les outils de web search et fetch déversent des pages HTML complètes dans la fenêtre de contexte de Claude. La majeure partie de ce contenu est non pertinente — navigation, pubs, boilerplate. Claude raisonne ensuite sur tout cela, gaspillant des tokens et réduisant la précision.
|
||||
|
||||
### La solution
|
||||
|
||||
Claude **écrit et exécute désormais du code Python pour filtrer les résultats web** avant qu'ils n'entrent dans la fenêtre de contexte. Au lieu de raisonner sur du HTML brut, Claude filtre, parse et extrait uniquement le contenu pertinent dans un sandbox.
|
||||
|
||||
### Comment ça fonctionne
|
||||
|
||||
**Avant :**
|
||||
```
|
||||
Requête → Résultats de recherche → Récupérer le HTML complet × N pages → Tout le contenu entre en contexte → Claude raisonne sur tout
|
||||
```
|
||||
|
||||
**Après :**
|
||||
```
|
||||
Requête → Résultats de recherche → Claude écrit du code de filtrage → Le code extrait uniquement le contenu pertinent → Les résultats filtrés entrent en contexte
|
||||
```
|
||||
|
||||
### Configuration API
|
||||
|
||||
Utilise des versions de type d'outil mises à jour avec un en-tête beta :
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "claude-opus-4-6",
|
||||
"max_tokens": 4096,
|
||||
"tools": [
|
||||
{
|
||||
"type": "web_search_20260209",
|
||||
"name": "web_search"
|
||||
},
|
||||
{
|
||||
"type": "web_fetch_20260209",
|
||||
"name": "web_fetch"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**En-tête requis :** `anthropic-beta: code-execution-web-tools-2026-02-09`
|
||||
|
||||
**Activé par défaut** en utilisant les nouvelles versions de type d'outil avec Sonnet 4.6 et Opus 4.6.
|
||||
|
||||
### Résultats de benchmark
|
||||
|
||||
**BrowseComp** (trouver des informations spécifiques sur des sites web) :
|
||||
|
||||
| Modèle | Sans filtrage | Avec filtrage | Amélioration |
|
||||
|-------|-------------------|----------------|-------------|
|
||||
| Sonnet 4.6 | 33,3% | **46,6%** | +13,3 pp |
|
||||
| Opus 4.6 | 45,3% | **61,6%** | +16,3 pp |
|
||||
|
||||
**DeepsearchQA** (recherche multi-étapes, score F1) :
|
||||
|
||||
| Modèle | Sans filtrage | Avec filtrage | Amélioration |
|
||||
|-------|-------------------|----------------|-------------|
|
||||
| Sonnet 4.6 | 52,6% | **59,4%** | +6,8 pp |
|
||||
| Opus 4.6 | 69,8% | **77,3%** | +7,5 pp |
|
||||
|
||||
**Efficacité en tokens :** En moyenne 24% de tokens d'entrée en moins. Sonnet 4.6 voit une réduction de coût ; Opus 4.6 peut augmenter légèrement à cause d'un code de filtrage plus complexe.
|
||||
|
||||
### Cas d'usage
|
||||
|
||||
- Passer au crible de la documentation technique
|
||||
- Vérifier des citations sur plusieurs sources
|
||||
- Recouper des résultats de recherche
|
||||
- Requêtes de recherche multi-étapes
|
||||
- Trouver des données spécifiques enfouies dans de grandes pages
|
||||
|
||||
---
|
||||
|
||||
## Outil de recherche d'outils (Tool Search Tool)
|
||||
|
||||
### Le problème
|
||||
|
||||
Charger toutes les définitions d'outils d'emblée gaspille du contexte. Si tu as 50 outils MCP à ~1,5K tokens chacun, c'est 75K tokens avant même que l'utilisateur ne pose une question.
|
||||
|
||||
### La solution
|
||||
|
||||
Marque les outils peu utilisés avec `defer_loading: true`. Ils sont exclus du contexte initial. Claude les découvre à la demande via un Tool Search Tool.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "mcp_toolset",
|
||||
"mcp_server_name": "google-drive",
|
||||
"default_config": { "defer_loading": true },
|
||||
"configs": {
|
||||
"search_files": { "defer_loading": false }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Bonnes pratiques
|
||||
|
||||
- Garde les 3-5 outils les plus utilisés toujours chargés, diffère le reste
|
||||
- Écris des noms et descriptions d'outils clairs et descriptifs (la recherche s'appuie dessus)
|
||||
- Documente les capacités disponibles dans le system prompt
|
||||
|
||||
### Quand l'utiliser
|
||||
|
||||
- Définitions d'outils consommant > 10K tokens
|
||||
- 10+ outils disponibles
|
||||
- Plusieurs serveurs MCP
|
||||
- Problèmes de précision de sélection d'outil dus à trop d'options
|
||||
|
||||
### Économie de tokens
|
||||
|
||||
~85% de réduction des tokens de définition d'outils (77K → 8,7K dans les benchmarks d'Anthropic).
|
||||
|
||||
### Équivalent Claude Code
|
||||
|
||||
Claude Code dispose du **mode auto de recherche d'outils MCP** (activé par défaut depuis v2.1.7). Quand les descriptions d'outils MCP dépassent 10% du contexte, elles sont différées et découvertes via `MCPSearch`. Configure le seuil avec `ENABLE_TOOL_SEARCH=auto:N` où N est le pourcentage de contexte (0-100).
|
||||
|
||||
---
|
||||
|
||||
## Exemples d'usage d'outils (Tool Use Examples)
|
||||
|
||||
### Le problème
|
||||
|
||||
Les schémas JSON définissent la structure mais ne peuvent exprimer :
|
||||
- Quand inclure des paramètres optionnels
|
||||
- Quelles combinaisons de paramètres ont du sens
|
||||
- Les conventions de format (formats de date, patterns d'ID)
|
||||
- L'usage de structures imbriquées
|
||||
|
||||
### La solution
|
||||
|
||||
Ajoute `input_examples` aux définitions d'outils — des patterns d'usage concrets au-delà du schéma.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "create_ticket",
|
||||
"description": "Create a support ticket",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"title": { "type": "string" },
|
||||
"priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
|
||||
"assignee": { "type": "string" },
|
||||
"labels": { "type": "array", "items": { "type": "string" } }
|
||||
},
|
||||
"required": ["title"]
|
||||
},
|
||||
"input_examples": [
|
||||
{
|
||||
"title": "Login page returns 500 error",
|
||||
"priority": "critical",
|
||||
"assignee": "oncall-team",
|
||||
"labels": ["bug", "auth", "production"]
|
||||
},
|
||||
{
|
||||
"title": "Add dark mode support",
|
||||
"priority": "low",
|
||||
"labels": ["feature-request", "ui"]
|
||||
},
|
||||
{
|
||||
"title": "Update API docs for v2 endpoints"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Bonnes pratiques
|
||||
|
||||
- Utilise des **données réalistes**, pas des chaînes placeholder comme « example_value »
|
||||
- Montre de la **variété** : spécifications minimale, partielle et complète
|
||||
- Reste concis : **1-5 exemples par outil**
|
||||
- Concentre-toi sur la résolution d'ambiguïté — vise la clarté comportementale plutôt que la complétude du schéma
|
||||
- Montre les corrélations de paramètres (par ex. `priority: "critical"` a tendance à avoir un `assignee`)
|
||||
|
||||
### Résultats
|
||||
|
||||
72% → 90% de précision sur la gestion de paramètres complexes dans les benchmarks d'Anthropic.
|
||||
|
||||
---
|
||||
|
||||
## Pertinence pour Claude Code
|
||||
|
||||
### Ce qui s'applique directement aux utilisateurs de Claude Code
|
||||
|
||||
| Fonctionnalité | Statut Claude Code | Action |
|
||||
|---------|-------------------|--------|
|
||||
| Tool Search | Intégré depuis v2.1.7 comme mode auto MCPSearch | Règle `ENABLE_TOOL_SEARCH=auto:N` si tu as beaucoup d'outils MCP |
|
||||
| Filtrage dynamique | Non disponible en CLI (outils web au niveau API) | Pertinent pour les utilisateurs de l'Agent SDK faisant de la recherche web |
|
||||
| PTC | Non disponible en CLI | Pertinent pour les utilisateurs de l'Agent SDK construisant des agents personnalisés |
|
||||
| Tool Use Examples | Non configurable en CLI | Pertinent pour les auteurs de serveurs MCP personnalisés |
|
||||
|
||||
### Pour les développeurs Agent SDK
|
||||
|
||||
Si tu construis des agents avec `@anthropic-ai/claude-agent-sdk`, le PTC est immédiatement actionnable :
|
||||
|
||||
1. Ajoute `code_execution_20250825` à ton tableau d'outils
|
||||
2. Définis `allowed_callers` sur les outils qui bénéficient du batching/filtrage
|
||||
3. Implémente la boucle de résultat d'outil (pause → fournir le résultat → reprendre)
|
||||
4. Renvoie des données structurées (JSON) depuis les outils pour un parsing programmatique plus facile
|
||||
|
||||
### Pour les auteurs de serveurs MCP
|
||||
|
||||
Si tu construis des serveurs MCP personnalisés, les Tool Use Examples peuvent améliorer la façon dont Claude utilise tes outils :
|
||||
- Ajoute `input_examples` aux schémas d'outils
|
||||
- Documente clairement les formats de retour dans les descriptions (le PTC doit les parser)
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Anthropic Engineering: Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use)
|
||||
- [Documentation Programmatic Tool Calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
|
||||
- [Documentation Code Execution Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
|
||||
- [Improved Web Search with Dynamic Filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)
|
||||
@@ -0,0 +1,210 @@
|
||||
# Agents vs Commandes vs Skills — Quand utiliser quoi
|
||||
|
||||
Une comparaison des trois mécanismes d'extension de Claude Code : sous-agents, commandes et skills.
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## En un coup d'œil
|
||||
|
||||
| | Agent | Commande | Skill |
|
||||
|---|---|---|---|
|
||||
| **Emplacement** | `.claude/agents/<name>.md` | `.claude/commands/<name>.md` | `.claude/skills/<name>/SKILL.md` |
|
||||
| **Contexte** | Processus de sous-agent séparé | Inline (conversation principale) | Inline (conversation principale) |
|
||||
| **Invocable par l'utilisateur** | Pas de menu `/` — invoqué par Claude ou via l'outil Agent | Oui — `/command-name` | Oui — `/skill-name` (sauf `user-invocable: false`) |
|
||||
| **Auto-invoqué par Claude** | Oui — via le champ `description` | Non | Oui — via le champ `description` (sauf `disable-model-invocation: true`) |
|
||||
| **Accepte des arguments** | Via le paramètre `prompt` | `$ARGUMENTS`, `$0`, `$1` | `$ARGUMENTS`, `$0`, `$1` |
|
||||
| **Injection de contexte dynamique** | Non | Oui — `` !`command` `` | Oui — `` !`command` `` |
|
||||
| **Fenêtre de contexte propre** | Oui — isolée | Non — partage la principale | Non — partage la principale (sauf `context: fork`) |
|
||||
| **Surcharge de modèle** | Frontmatter `model:` | Frontmatter `model:` | Frontmatter `model:` |
|
||||
| **Restrictions d'outils** | `tools:` / `disallowedTools:` | `allowed-tools:` | `allowed-tools:` |
|
||||
| **Hooks** | Frontmatter `hooks:` | — | Frontmatter `hooks:` |
|
||||
| **Mémoire** | Frontmatter `memory:` (user/project/local) | — | — |
|
||||
| **Peut précharger des skills** | Oui — frontmatter `skills:` | — | — |
|
||||
| **Serveurs MCP** | Frontmatter `mcpServers:` | — | — |
|
||||
|
||||
---
|
||||
|
||||
## Quand utiliser chacun
|
||||
|
||||
### Utilise un Agent quand :
|
||||
|
||||
- La tâche est **autonome et multi-étapes** — l'agent doit explorer, décider et agir sans guidage constant
|
||||
- Tu as besoin d'**isolation de contexte** — le travail ne doit pas polluer la fenêtre de conversation principale
|
||||
- L'agent a besoin de **mémoire persistante** entre les sessions (par ex. un relecteur de code qui apprend des patterns)
|
||||
- Tu veux **précharger de la connaissance de domaine** via des skills sans encombrer le contexte principal
|
||||
- La tâche bénéficie d'une **exécution en arrière-plan** ou dans un **worktree git**
|
||||
- Tu as besoin de **restrictions d'outils** ou d'un **mode de permissions différent** (par ex. `acceptEdits`, `plan`)
|
||||
|
||||
**Exemple** : `weather-agent` — récupère de façon autonome les données météo via son skill préchargé `weather-fetcher`, tourne dans un contexte séparé avec des outils restreints.
|
||||
|
||||
### Utilise une Commande quand :
|
||||
|
||||
- Tu as besoin d'un **point d'entrée initié par l'utilisateur** — un workflow que l'utilisateur déclenche explicitement
|
||||
- Le workflow implique d'**orchestrer** d'autres agents ou skills
|
||||
- Tu veux **garder le contexte léger** — le contenu de la commande n'est pas injecté dans le contexte de session tant que l'utilisateur ne la déclenche pas
|
||||
|
||||
**Exemple** : `weather-orchestrator` — l'utilisateur le déclenche, il demande la préférence C/F, invoque l'agent, puis invoque le skill SVG.
|
||||
|
||||
### Utilise un Skill quand :
|
||||
|
||||
- Tu veux que **Claude auto-invoque** selon l'intention de l'utilisateur — les descriptions de skills sont injectées dans le contexte de session pour une correspondance sémantique
|
||||
- La tâche est une **procédure réutilisable** invocable depuis plusieurs endroits (commandes, agents, ou Claude lui-même)
|
||||
- Tu as besoin de **préchargement d'agent** — intégrer de la connaissance de domaine dans un agent spécifique au démarrage
|
||||
|
||||
**Exemple** : `weather-svg-creator` — Claude l'auto-invoque quand l'utilisateur demande une carte météo ; aussi appelable depuis des commandes.
|
||||
|
||||
---
|
||||
|
||||
## L'architecture Commande → Agent → Skill
|
||||
|
||||
Ce dépôt démontre un pattern d'orchestration en couches :
|
||||
|
||||
```
|
||||
L'utilisateur déclenche /command
|
||||
↓
|
||||
La commande orchestre le workflow
|
||||
↓
|
||||
La commande invoque l'Agent (contexte séparé, autonome)
|
||||
↓
|
||||
L'Agent utilise le Skill préchargé (connaissance de domaine)
|
||||
↓
|
||||
La commande invoque le Skill (inline, pour la génération de sortie)
|
||||
```
|
||||
|
||||
**Exemple concret** — le système météo :
|
||||
|
||||
```
|
||||
/weather-orchestrator (commande — point d'entrée, demande C/F)
|
||||
↓
|
||||
weather-agent (agent — récupère la température de façon autonome)
|
||||
├── weather-fetcher (skill d'agent — instructions API préchargées)
|
||||
↓
|
||||
weather-svg-creator (skill — crée le SVG inline)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparaison des frontmatters
|
||||
|
||||
### Frontmatter d'Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-agent
|
||||
description: Use this agent PROACTIVELY when...
|
||||
tools: Read, Write, Edit, Bash
|
||||
model: sonnet
|
||||
maxTurns: 10
|
||||
permissionMode: acceptEdits
|
||||
memory: user
|
||||
skills:
|
||||
- my-skill
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter de Commande
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Do something useful
|
||||
argument-hint: [issue-number]
|
||||
allowed-tools: Read, Edit, Bash(gh *)
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter de Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: Do something when the user asks for...
|
||||
argument-hint: [file-path]
|
||||
disable-model-invocation: false
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Grep, Glob
|
||||
model: sonnet
|
||||
context: fork
|
||||
agent: general-purpose
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distinctions clés
|
||||
|
||||
### Auto-invocation
|
||||
|
||||
| Mécanisme | Claude peut-il auto-invoquer ? | Comment l'empêcher |
|
||||
|-----------|------------------------|----------------|
|
||||
| Agent | Oui — via `description` (utilise « PROACTIVELY » pour l'encourager) | Retire ou adoucis la description |
|
||||
| Commande | Non — toujours initiée par l'utilisateur via `/` | N/A |
|
||||
| Skill | Oui — via `description` | Mets `disable-model-invocation: true` |
|
||||
|
||||
### Visibilité dans le menu `/`
|
||||
|
||||
| Mécanisme | Apparaît dans le menu `/` ? | Comment masquer |
|
||||
|-----------|---------------------|-------------|
|
||||
| Agent | Non | N/A |
|
||||
| Commande | Oui — toujours | Ne peut être masquée |
|
||||
| Skill | Oui — par défaut | Mets `user-invocable: false` |
|
||||
|
||||
### Isolation de contexte
|
||||
|
||||
| Mécanisme | Tourne dans son propre contexte ? | Comment configurer |
|
||||
|-----------|---------------------|-----------------|
|
||||
| Agent | Toujours | Comportement intégré |
|
||||
| Commande | Jamais | N/A |
|
||||
| Skill | Optionnel | Mets `context: fork` |
|
||||
|
||||
---
|
||||
|
||||
## Exemple traité : « Quelle est l'heure actuelle ? »
|
||||
|
||||
Ce dépôt a les trois mécanismes définis pour la même tâche — afficher l'heure actuelle en PKT. Voici ce qui se passe quand un utilisateur tape **« What is the current time? »** sans invoquer explicitement une commande `/` :
|
||||
|
||||
| Mécanisme | Va-t-il se déclencher ? | Pourquoi / Pourquoi pas |
|
||||
|-----------|--------------|---------------|
|
||||
| `time-command` | Non | Les commandes ne sont **jamais auto-invoquées**. L'utilisateur devrait taper explicitement `/time-command` pour l'exécuter. Les commandes n'ont pas de voie d'auto-découverte — elles sont strictement initiées par l'utilisateur. |
|
||||
| `time-agent` | **Oui** (possible) | La `description` de l'agent dit *« Use this agent to display the current time in Pakistan Standard Time »*. Claude la met en correspondance avec l'intention de l'utilisateur et peut l'instancier via l'outil Agent. Cependant, les agents tournent dans une **fenêtre de contexte séparée**, les rendant plus lourds que nécessaire pour cette tâche simple. |
|
||||
| `time-skill` | **Oui** (le plus probable) | La `description` du skill dit *« Display the current time in Pakistan Standard Time (PKT, UTC+5). Use when the user asks for the current time, Pakistan time, or PKT. »* Claude la met en correspondance et l'invoque via l'outil Skill. Comme il tourne **inline** sans surcoût de contexte, c'est la correspondance la plus efficace. |
|
||||
|
||||
### Ordre de résolution
|
||||
|
||||
Quand plusieurs mécanismes correspondent à la même intention, Claude préfère l'**option la plus légère** qui satisfait la requête :
|
||||
|
||||
```
|
||||
1. Skill (inline, sans surcoût de contexte) ← préféré
|
||||
2. Agent (contexte séparé, autonome) ← utilisé si le skill est indisponible ou la tâche complexe
|
||||
3. Commande (jamais — requiert un / explicite) ← uniquement si l'utilisateur tape /time-command
|
||||
```
|
||||
|
||||
### Et si `disable-model-invocation: true` était défini sur le skill ?
|
||||
|
||||
Alors Claude **ne peut pas** auto-invoquer le skill. L'agent devient la seule option auto-invocable, donc Claude instancierait `time-agent` à la place — au prix d'une fenêtre de contexte séparée pour une commande bash d'une ligne.
|
||||
|
||||
### Et si skill et agent avaient tous deux l'auto-invocation désactivée ?
|
||||
|
||||
Alors **rien ne se déclenche automatiquement**. Claude se rabattrait sur sa propre connaissance générale et lancerait probablement juste `TZ='Asia/Karachi' date` directement — aucun mécanisme d'extension impliqué. L'utilisateur devrait taper explicitement `/time-command` ou `/time-skill` pour en utiliser un.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Skills Claude Code — Documentation](https://code.claude.com/docs/en/skills)
|
||||
- [Sous-agents Claude Code — Documentation](https://code.claude.com/docs/en/sub-agents)
|
||||
- [Commandes slash Claude Code — Documentation](https://code.claude.com/docs/en/slash-commands)
|
||||
- [Bonnes pratiques — Skills](../best-practice/claude-skills.md)
|
||||
- [Bonnes pratiques — Commandes](../best-practice/claude-commands.md)
|
||||
- [Bonnes pratiques — Sous-agents](../best-practice/claude-subagents.md)
|
||||
@@ -0,0 +1,108 @@
|
||||
# Claude Code : Frontmatter de mémoire d'agent
|
||||
|
||||
Mémoire persistante pour les sous-agents — permettre aux agents d'apprendre, de se souvenir et de construire de la connaissance entre les sessions.
|
||||
|
||||
<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>
|
||||
|
||||
---
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Introduit dans **Claude Code v2.1.33** (février 2026), le champ de frontmatter `memory` donne à chaque sous-agent son propre magasin de connaissances persistant basé sur markdown. Avant cela, chaque invocation d'agent repartait de zéro.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews code for quality and best practices
|
||||
tools: Read, Write, Edit, Bash
|
||||
model: sonnet
|
||||
memory: user
|
||||
---
|
||||
|
||||
You are a code reviewer. As you review code, update your agent memory with
|
||||
patterns, conventions, and recurring issues you discover.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Portées de mémoire
|
||||
|
||||
| Portée | Emplacement de stockage | Versionné | Partagé | Idéal pour |
|
||||
|-------|-----------------|-------------------|--------|----------|
|
||||
| `user` | `~/.claude/agent-memory/<agent-name>/` | Non | Non | Connaissance inter-projets (défaut recommandé) |
|
||||
| `project` | `.claude/agent-memory/<agent-name>/` | Oui | Oui | Connaissance spécifique au projet que l'équipe devrait partager |
|
||||
| `local` | `.claude/agent-memory-local/<agent-name>/` | Non (git-ignored) | Non | Connaissance spécifique au projet mais personnelle |
|
||||
|
||||
Ces portées reflètent la hiérarchie des paramètres (`~/.claude/settings.json` → `.claude/settings.json` → `.claude/settings.local.json`).
|
||||
|
||||
---
|
||||
|
||||
## Comment ça fonctionne
|
||||
|
||||
1. **Au démarrage** : les 200 premières lignes de `MEMORY.md` sont injectées dans le system prompt de l'agent
|
||||
2. **Accès aux outils** : `Read`, `Write`, `Edit` sont auto-activés pour que l'agent puisse gérer sa mémoire
|
||||
3. **Pendant l'exécution** : l'agent lit/écrit librement dans son répertoire de mémoire
|
||||
4. **Curation** : si `MEMORY.md` dépasse 200 lignes, l'agent déplace les détails dans des fichiers spécifiques à un sujet
|
||||
|
||||
```
|
||||
~/.claude/agent-memory/code-reviewer/ # exemple de portée user
|
||||
├── MEMORY.md # Fichier principal (200 premières lignes chargées)
|
||||
├── react-patterns.md # Fichier spécifique à un sujet
|
||||
└── security-checklist.md # Fichier spécifique à un sujet
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mémoire d'agent vs autres systèmes de mémoire
|
||||
|
||||
| Système | Qui écrit | Qui lit | Portée |
|
||||
|--------|-----------|-----------|-------|
|
||||
| **CLAUDE.md** | Toi (manuellement) | Claude principal + tous les agents | Projet |
|
||||
| **Auto-mémoire** | Claude principal (auto) | Claude principal uniquement | Par projet par utilisateur |
|
||||
| **Commande `/memory`** | Toi (via éditeur) | Claude principal uniquement | Par projet par utilisateur |
|
||||
| **Mémoire d'agent** | L'agent lui-même | Cet agent spécifique uniquement | Configurable (user/project/local) |
|
||||
|
||||
Ces systèmes sont **complémentaires** — un agent lit à la fois CLAUDE.md (contexte projet) et sa propre mémoire (connaissance propre à l'agent).
|
||||
|
||||
---
|
||||
|
||||
## Exemple pratique
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: api-developer
|
||||
description: Implement API endpoints following team conventions
|
||||
tools: Read, Write, Edit, Bash
|
||||
model: sonnet
|
||||
memory: project
|
||||
skills:
|
||||
- api-conventions
|
||||
- error-handling-patterns
|
||||
---
|
||||
|
||||
Implement API endpoints. Follow the conventions from your preloaded skills.
|
||||
As you work, save architectural decisions and patterns to your memory.
|
||||
```
|
||||
|
||||
Cela combine les **skills** (connaissance statique au démarrage) avec la **mémoire** (connaissance dynamique construite au fil du temps).
|
||||
|
||||
---
|
||||
|
||||
## Astuces
|
||||
|
||||
- **Prompter l'usage de la mémoire** — Inclure des instructions explicites : `"Before starting, review your memory. After completing, update your memory with what you learned."`
|
||||
- **Demander des vérifications de mémoire** en invoquant des agents : `"Review this PR, and check your memory for patterns you've seen before."`
|
||||
- **Choisir la bonne portée** — `user` pour inter-projets, `project` pour partagé en équipe, `local` pour personnel
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Créer des sous-agents personnalisés — Documentation Claude Code](https://code.claude.com/docs/en/sub-agents)
|
||||
- [Gérer la mémoire de Claude — Documentation Claude Code](https://code.claude.com/docs/en/memory)
|
||||
- [Notes de version Claude Code v2.1.33](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
|
||||
@@ -0,0 +1,340 @@
|
||||
# Claude Agent SDK vs Claude CLI : System prompts et cohérence de sortie
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Résumé exécutif
|
||||
|
||||
En envoyant le même message (par ex. « What is the capital of Norway? ») via le **Claude Agent SDK** versus le **Claude CLI (Claude Code)**, les system prompts accompagnant ces messages sont fondamentalement différents. Le CLI utilise une **architecture de system prompt modulaire** (~269 tokens de base avec du contexte additionnel chargé conditionnellement selon les fonctionnalités), tandis que le SDK utilise un prompt minimal par défaut. **Il n'y a aucune garantie de sortie identique entre les deux**, même avec des configurations correspondantes, en raison de l'absence d'un paramètre seed et du non-déterminisme inhérent à l'architecture de Claude.
|
||||
|
||||
---
|
||||
|
||||
## 1. Comparaison des system prompts
|
||||
|
||||
### Claude CLI (Claude Code)
|
||||
|
||||
Le Claude CLI utilise une **architecture de system prompt modulaire** avec un prompt de base de ~269 tokens, du contexte additionnel étant chargé conditionnellement :
|
||||
|
||||
| Composant | Description | Chargement |
|
||||
|-----------|-------------|---------|
|
||||
| **System prompt de base** | Instructions et comportement de base | Toujours (~269 tokens) |
|
||||
| **Instructions d'outils** | 18+ outils intégrés (Write, Read, Edit, Bash, TodoWrite, etc.) | Toujours |
|
||||
| **Directives de code** | Style de code, règles de formatage, pratiques de sécurité | Toujours |
|
||||
| **Règles de sécurité** | Règles de refus, défense contre l'injection, prévention des dommages | Toujours |
|
||||
| **Style de réponse** | Ton, verbosité, profondeur d'explication, usage d'emoji | Toujours |
|
||||
| **Contexte d'environnement** | Répertoire de travail, git status, infos de plateforme | Toujours |
|
||||
| **Contexte de projet** | Contenu CLAUDE.md, paramètres, configuration des hooks | Conditionnel |
|
||||
| **Prompts de sous-agents** | Mode plan, agent Explore, agent Task | Conditionnel |
|
||||
| **Revue de sécurité** | Instructions de sécurité étendues (~2 610 tokens) | Conditionnel |
|
||||
|
||||
**Caractéristiques clés :**
|
||||
- **Architecture modulaire** avec 110+ chaînes de system prompt chargées conditionnellement
|
||||
- Le prompt de base est modeste (~269 tokens), le total varie selon les fonctionnalités activées
|
||||
- Inclut des couches étendues de sécurité et de défense contre l'injection
|
||||
- Charge automatiquement les fichiers CLAUDE.md dans le répertoire de travail
|
||||
- Contexte persistant en session en mode interactif
|
||||
|
||||
### Claude Agent SDK
|
||||
|
||||
L'Agent SDK utilise un **system prompt minimal par défaut** contenant :
|
||||
|
||||
| Composant | Description | Impact en tokens |
|
||||
|-----------|-------------|--------------|
|
||||
| **Instructions d'outils essentielles** | Uniquement les outils explicitement fournis | Minimal |
|
||||
| **Sécurité de base** | Instructions de sécurité minimales | Minimal |
|
||||
|
||||
**Caractéristiques clés :**
|
||||
- Aucune directive de code ni préférence de style par défaut
|
||||
- Aucun contexte de projet sauf configuration explicite
|
||||
- Aucune description d'outils étendue
|
||||
- Requiert une configuration explicite pour correspondre au comportement du CLI
|
||||
|
||||
---
|
||||
|
||||
## 2. Ce que chaque interface envoie
|
||||
|
||||
### Exemple : « What is the capital of Norway? »
|
||||
|
||||
#### Via le Claude CLI
|
||||
|
||||
```
|
||||
System Prompt : [modulaire, ~269+ tokens de base]
|
||||
├── System prompt de base (~269 tokens)
|
||||
├── Instructions d'outils (Write, Read, Edit, Bash, Grep, Glob, etc.)
|
||||
├── Protocoles de sécurité git
|
||||
├── Directives de référence de code
|
||||
├── Instructions d'objectivité professionnelle
|
||||
├── Règles de sécurité et de défense contre l'injection
|
||||
├── Contexte d'environnement (OS, répertoire, date)
|
||||
├── Contenu CLAUDE.md (si présent) [conditionnel]
|
||||
├── Descriptions d'outils MCP (si configurés) [conditionnel]
|
||||
├── Prompts de mode Plan/Explore [conditionnel]
|
||||
└── Contexte de session/conversation
|
||||
|
||||
Message utilisateur : "What is the capital of Norway?"
|
||||
```
|
||||
|
||||
#### Via le Claude Agent SDK (par défaut)
|
||||
|
||||
```
|
||||
System Prompt : [minimal]
|
||||
├── Instructions d'outils essentielles (si des outils sont fournis)
|
||||
└── Contexte opérationnel de base
|
||||
|
||||
Message utilisateur : "What is the capital of Norway?"
|
||||
```
|
||||
|
||||
#### Via l'Agent SDK (avec le preset `claude_code`)
|
||||
|
||||
```typescript
|
||||
const response = await query({
|
||||
prompt: "What is the capital of Norway?",
|
||||
options: {
|
||||
systemPrompt: {
|
||||
type: "preset",
|
||||
preset: "claude_code"
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
```
|
||||
System Prompt : [modulaire, correspond au CLI]
|
||||
├── System prompt Claude Code complet
|
||||
├── Instructions d'outils
|
||||
├── Directives de code
|
||||
└── Règles de sécurité
|
||||
|
||||
// NOTE : N'inclut TOUJOURS PAS CLAUDE.md sauf si settingSources est configuré
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Méthodes de personnalisation
|
||||
|
||||
### Personnalisation du Claude CLI
|
||||
|
||||
| Méthode | Commande | Effet |
|
||||
|--------|---------|--------|
|
||||
| **Ajouter au prompt** | `claude -p "..." --append-system-prompt "..."` | Ajoute des instructions en préservant les défauts |
|
||||
| **Remplacer le prompt** | `claude -p "..." --system-prompt "..."` | Remplace entièrement le system prompt |
|
||||
| **Contexte de projet** | Fichier CLAUDE.md | Chargé automatiquement, persistant |
|
||||
| **Styles de sortie** | `/output-style [name]` | Applique des styles de réponse prédéfinis |
|
||||
|
||||
### Personnalisation de l'Agent SDK
|
||||
|
||||
| Méthode | Configuration | Effet |
|
||||
|--------|---------------|--------|
|
||||
| **Prompt personnalisé** | `systemPrompt: "..."` | Remplace entièrement le défaut (perd les outils) |
|
||||
| **Preset avec ajout** | `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }` | Préserve la fonctionnalité CLI + instructions personnalisées |
|
||||
| **Chargement de CLAUDE.md** | `settingSources: ["project"]` | Charge les instructions au niveau projet |
|
||||
| **Styles de sortie** | `settingSources: ["user"]` ou `settingSources: ["project"]` | Charge les styles de sortie enregistrés |
|
||||
|
||||
### Tableau comparatif de configuration
|
||||
|
||||
| Fonctionnalité | CLI par défaut | SDK par défaut | SDK avec preset |
|
||||
|---------|-------------|-------------|-----------------|
|
||||
| Instructions d'outils | ✅ Complètes | ❌ Minimales | ✅ Complètes |
|
||||
| Directives de code | ✅ Oui | ❌ Non | ✅ Oui |
|
||||
| Règles de sécurité | ✅ Oui | ❌ De base | ✅ Oui |
|
||||
| Auto-chargement CLAUDE.md | ✅ Oui | ❌ Non | ❌ Non* |
|
||||
| Contexte de projet | ✅ Automatique | ❌ Non | ❌ Non* |
|
||||
|
||||
*Requiert une configuration explicite `settingSources: ["project"]`
|
||||
|
||||
---
|
||||
|
||||
## 4. Garanties de cohérence de sortie
|
||||
|
||||
### Constat critique : AUCUN déterminisme garanti
|
||||
|
||||
**L'API Messages de Claude ne fournit pas de paramètre seed pour la reproductibilité.** C'est une limitation architecturale fondamentale.
|
||||
|
||||
### Facteurs empêchant une sortie identique
|
||||
|
||||
| Facteur | Description | Contrôlable ? |
|
||||
|--------|-------------|---------------|
|
||||
| **System prompts différents** | CLI vs SDK ont des défauts différents | ✅ Oui (avec configuration) |
|
||||
| **Arithmétique en virgule flottante** | Particularités du matériel parallèle | ❌ Non |
|
||||
| **Routage MoE** | Variations de l'architecture Mixture-of-Experts | ❌ Non |
|
||||
| **Batching/ordonnancement** | Différences d'infrastructure cloud | ❌ Non |
|
||||
| **Précision numérique** | Variations du moteur d'inférence | ❌ Non |
|
||||
| **Snapshots de modèle** | Mises à jour/changements de version | ❌ Non |
|
||||
|
||||
### Température et échantillonnage
|
||||
|
||||
Même avec `temperature=0.0` (décodage glouton) :
|
||||
- Le déterminisme complet **N'EST PAS garanti**
|
||||
- Des variations mineures peuvent quand même survenir à cause de facteurs d'infrastructure
|
||||
- Bug connu : [le Claude CLI produit une sortie non déterministe pour des entrées identiques](https://github.com/anthropics/claude-code/issues/3370)
|
||||
|
||||
---
|
||||
|
||||
## 5. Atteindre une cohérence maximale
|
||||
|
||||
Pour obtenir les sorties identiques **les plus proches possibles** entre SDK et CLI :
|
||||
|
||||
### Configuration de l'Agent SDK
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic();
|
||||
|
||||
// Option 1 : Utiliser le preset claude_code
|
||||
const response = await client.messages.create({
|
||||
model: "claude-sonnet-4-20250514",
|
||||
max_tokens: 1024,
|
||||
// Faire correspondre le system prompt du CLI au plus près
|
||||
system: "Your exact system prompt matching CLI",
|
||||
messages: [
|
||||
{ role: "user", content: "What is the capital of Norway?" }
|
||||
],
|
||||
// Utiliser le décodage glouton pour une cohérence maximale
|
||||
temperature: 0
|
||||
});
|
||||
|
||||
// Option 2 : Avec la fonction query de l'Agent SDK
|
||||
import { query } from "@anthropic-ai/agent-sdk";
|
||||
|
||||
for await (const message of query({
|
||||
prompt: "What is the capital of Norway?",
|
||||
options: {
|
||||
systemPrompt: {
|
||||
type: "preset",
|
||||
preset: "claude_code"
|
||||
},
|
||||
temperature: 0,
|
||||
model: "claude-sonnet-4-20250514",
|
||||
// Charger le contexte de projet comme le fait le CLI
|
||||
settingSources: ["project"]
|
||||
}
|
||||
})) {
|
||||
// Traiter la réponse
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration du CLI
|
||||
|
||||
```bash
|
||||
# Faire correspondre la configuration du SDK au plus près
|
||||
claude -p "What is the capital of Norway?" \
|
||||
--model claude-sonnet-4-20250514 \
|
||||
--temperature 0
|
||||
```
|
||||
|
||||
### Toujours pas garanti
|
||||
|
||||
Même avec des configurations parfaitement correspondantes :
|
||||
- La sortie peut différer entre exécutions
|
||||
- La sortie peut différer entre SDK et CLI
|
||||
- Aucun paramètre seed n'existe pour forcer la reproductibilité
|
||||
|
||||
---
|
||||
|
||||
## 6. Implications pratiques
|
||||
|
||||
### Quand utiliser chaque interface
|
||||
|
||||
| Cas d'usage | Interface recommandée | Raison |
|
||||
|----------|----------------------|--------|
|
||||
| Développement interactif | Claude CLI | Suite d'outils complète, contexte de projet |
|
||||
| Intégration programmatique | Agent SDK | Contrôle fin, embarquement |
|
||||
| Réponses API cohérentes | Agent SDK + prompt personnalisé | Plus de contrôle sur le system prompt |
|
||||
| Traitement par lots | Agent SDK | Meilleur pour les pipelines d'automatisation |
|
||||
| Tâches ponctuelles | Claude CLI | Mise en place plus rapide, contexte immédiat |
|
||||
|
||||
### Recommandations de conception
|
||||
|
||||
1. **Ne te fie pas à une reproductibilité au bit près**
|
||||
- Construis des applications robustes aux variations mineures de sortie
|
||||
- Utilise des sorties structurées et de la validation
|
||||
|
||||
2. **Pour les pipelines de production exigeant de la cohérence :**
|
||||
- Mets en cache les résultats quand possible
|
||||
- Utilise des sorties structurées avec validation par schéma JSON
|
||||
- Combine avec de la logique déterministe et de la validation
|
||||
- Envisage plusieurs générations avec consensus
|
||||
|
||||
3. **Pour faire correspondre le comportement du CLI dans le SDK :**
|
||||
```typescript
|
||||
systemPrompt: {
|
||||
type: "preset",
|
||||
preset: "claude_code",
|
||||
append: "Your additional instructions"
|
||||
},
|
||||
settingSources: ["project", "user"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Impact en tokens du system prompt
|
||||
|
||||
| Configuration | Architecture | Notes |
|
||||
|---------------|-------------|-------|
|
||||
| SDK (minimal) | Défaut minimal | Uniquement les instructions d'outils essentielles |
|
||||
| SDK (preset claude_code) | Modulaire (~269+ de base) | Correspond au CLI, varie selon les fonctionnalités |
|
||||
| CLI (par défaut) | Modulaire (~269+ de base) | Contexte additionnel chargé conditionnellement |
|
||||
| CLI (avec outils MCP) | Modulaire + MCP | Les descriptions d'outils MCP ajoutent beaucoup de tokens |
|
||||
|
||||
**Note :** Claude Code utilise une architecture modulaire avec 110+ chaînes de system prompt. Le prompt de base fait ~269 tokens, les composants individuels allant de 18 à 2 610 tokens selon les fonctionnalités activées.
|
||||
|
||||
**Implication :** Le défaut minimal du SDK te donne plus de contexte pour ta tâche réelle, mais au prix des capacités complètes de Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## 8. Tableau récapitulatif
|
||||
|
||||
| Aspect | Claude CLI | Agent SDK (par défaut) | Agent SDK (preset) |
|
||||
|--------|------------|--------------------|--------------------|
|
||||
| **System prompt** | Modulaire (~269+ de base) | Minimal | Modulaire (correspond au CLI) |
|
||||
| **Outils inclus** | 18+ intégrés | Seulement si fournis | 18+ intégrés |
|
||||
| **Auto-chargement CLAUDE.md** | Oui | Non | Non (nécessite config) |
|
||||
| **Directives de code** | Oui | Non | Oui |
|
||||
| **Règles de sécurité** | Complètes | De base | Complètes |
|
||||
| **Contrôle de température** | Oui | Oui | Oui |
|
||||
| **Garantie de déterminisme** | Non | Non | Non |
|
||||
| **Sorties identiques ?** | N/A | Non (vs CLI) | Plus proches, mais non |
|
||||
|
||||
---
|
||||
|
||||
## 9. Conclusion
|
||||
|
||||
**Q : Quels system prompts accompagnent le même message en SDK vs CLI ?**
|
||||
|
||||
Le CLI utilise une **architecture de system prompt modulaire** avec un prompt de base de ~269 tokens et 110+ composants chargés conditionnellement (instructions d'outils, directives de code, règles de sécurité, contexte de projet). Le SDK utilise un **défaut minimal** avec seulement les instructions d'outils essentielles, bien qu'il puisse être configuré pour correspondre au comportement du CLI via le preset `claude_code`.
|
||||
|
||||
**Q : Y a-t-il une garantie de sortie identique ?**
|
||||
|
||||
**Non.** Même avec des system prompts correspondants, des entrées identiques et `temperature=0`, il n'y a aucune garantie de sortie identique en raison de :
|
||||
- L'absence d'un paramètre seed dans l'API de Claude
|
||||
- Les variations d'arithmétique en virgule flottante
|
||||
- Le non-déterminisme au niveau de l'infrastructure
|
||||
- Les variations de routage de l'architecture du modèle (Mixture-of-Experts)
|
||||
|
||||
**Recommandation :** Conçois les systèmes pour être robustes aux variations de sortie plutôt que de te fier à un comportement déterministe. Pour les applications critiques en cohérence, utilise des sorties structurées, du caching et des couches de validation.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Modifying System Prompts - Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk#modifying-system-prompts)
|
||||
- [Référence CLI Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/cli)
|
||||
- [Mode Headless Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/headless)
|
||||
- [Bonnes pratiques Claude Code - Anthropic Engineering](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
- [Référence de l'API Messages de Claude](https://docs.anthropic.com/en/api/messages)
|
||||
- [GitHub Issue #3370 : Sortie non déterministe](https://github.com/anthropics/claude-code/issues/3370)
|
||||
- [Dépôt des system prompts de Claude Code](https://github.com/Piebald-AI/claude-code-system-prompts) - Analyse de l'architecture de prompt modulaire
|
||||
- [Why Deterministic Output from LLMs is Nearly Impossible](https://unstract.com/blog/understanding-why-deterministic-output-from-llms-is-nearly-impossible/)
|
||||
|
||||
---
|
||||
|
||||
*Ce rapport a été généré par Claude Code avec le modèle Opus 4.5 le 3 février 2026.*
|
||||
@@ -0,0 +1,248 @@
|
||||
# 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/)
|
||||
@@ -0,0 +1,345 @@
|
||||
# Rapport de comparaison complet des MCP d'automatisation de navigateur
|
||||
|
||||
<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>
|
||||
|
||||
## Résumé exécutif
|
||||
|
||||
Sur la base d'une recherche approfondie, j'ai analysé les deux outils de tes captures d'écran plus un troisième concurrent majeur. Voici mon décryptage complet pour t'aider à choisir la meilleure option pour le test automatisé de ton travail.
|
||||
|
||||
---
|
||||
|
||||
## 1. Les trois concurrents
|
||||
|
||||
### **A. Chrome DevTools MCP** (Ta capture d'écran nº1)
|
||||
- **Source :** Équipe officielle Google Chrome
|
||||
- **Sortie :** Aperçu public septembre 2025
|
||||
- **Architecture :** Construit sur le Chrome DevTools Protocol (CDP) + Puppeteer
|
||||
- **Usage de tokens :** ~19,0k tokens (9,5% du contexte)
|
||||
- **Outils :** 26 outils spécialisés répartis en 6 catégories
|
||||
|
||||
### **B. Claude in Chrome** (Ta capture d'écran nº2)
|
||||
- **Source :** Extension officielle Anthropic
|
||||
- **Sortie :** Bêta, déploiement sur tous les plans payants (Pro, Max, Team, Enterprise)
|
||||
- **Architecture :** Extension de navigateur avec capacités computer-use
|
||||
- **Usage de tokens :** ~15,4k tokens (7,7% du contexte)
|
||||
- **Outils :** 16 outils incluant des capacités computer use
|
||||
|
||||
### **C. Playwright MCP** (Alternative solide)
|
||||
- **Source :** Microsoft (officiel + implémentations communautaires)
|
||||
- **Architecture :** Automatisation basée sur l'arbre d'accessibilité
|
||||
- **Usage de tokens :** ~13,7k tokens (6,8% du contexte)
|
||||
- **Outils :** 21 outils
|
||||
|
||||
---
|
||||
|
||||
## 2. Comparaison détaillée des fonctionnalités
|
||||
|
||||
| Fonctionnalité | Chrome DevTools MCP | Claude in Chrome | Playwright MCP |
|
||||
|---------|---------------------|------------------|----------------|
|
||||
| **Objectif principal** | Débogage & performance | Automatisation générale de navigateur | Test UI & E2E |
|
||||
| **Support de navigateur** | Chrome uniquement | Chrome uniquement | Chromium, Firefox, WebKit |
|
||||
| **Efficacité en tokens** | 19,0k (9,5%) | 15,4k (7,7%) | 13,7k (6,8%) |
|
||||
| **Sélection d'éléments** | Sélecteurs CSS/XPath | Visuel + DOM | Arbre d'accessibilité (sémantique) |
|
||||
| **Traces de performance** | ✅ Excellentes | ❌ Non | ⚠️ Limitées |
|
||||
| **Inspection réseau** | ✅ Analyse approfondie | ⚠️ Basique | ⚠️ Basique |
|
||||
| **Logs de console** | ✅ Accès complet | ✅ Accès complet | ⚠️ Limité |
|
||||
| **Multi-navigateur** | ❌ Non | ❌ Non | ✅ Oui |
|
||||
| **Intégration CI/CD** | ✅ Excellente | ❌ Faible (requiert login) | ✅ Excellente |
|
||||
| **Mode headless** | ✅ Oui | ❌ Non | ✅ Oui |
|
||||
| **Authentification** | Requiert configuration | Utilise ta session | Requiert configuration |
|
||||
| **Tâches planifiées** | ❌ Non | ✅ Oui | ❌ Non |
|
||||
| **Coût** | Gratuit | Requiert un plan payant | Gratuit |
|
||||
| **Mise en place locale** | Node.js requis | Extension de navigateur | Node.js requis |
|
||||
|
||||
---
|
||||
|
||||
## 3. Décomposition des outils
|
||||
|
||||
### Chrome DevTools MCP (26 outils)
|
||||
|
||||
```
|
||||
AUTOMATISATION D'ENTRÉE (8): click, drag, fill, fill_form, handle_dialog,
|
||||
hover, press_key, upload_file
|
||||
|
||||
NAVIGATION (6): close_page, list_pages, navigate_page,
|
||||
new_page, select_page, wait_for
|
||||
|
||||
ÉMULATION (2): emulate, resize_page
|
||||
|
||||
PERFORMANCE (3): performance_analyze_insight,
|
||||
performance_start_trace, performance_stop_trace
|
||||
|
||||
RÉSEAU (2): get_network_request, list_network_requests
|
||||
|
||||
DÉBOGAGE (5): evaluate_script, get_console_message,
|
||||
list_console_messages, take_screenshot,
|
||||
take_snapshot
|
||||
```
|
||||
|
||||
### Claude in Chrome (16 outils)
|
||||
|
||||
```
|
||||
CONTRÔLE NAVIGATEUR: navigate, read_page, find, computer
|
||||
(click, type, scroll)
|
||||
|
||||
INTERACTION FORMULAIRE: form_input, javascript_tool
|
||||
|
||||
MÉDIA: upload_image, get_page_text, gif_creator
|
||||
|
||||
GESTION ONGLETS: tabs_context_mcp, tabs_create_mcp
|
||||
|
||||
DÉVELOPPEMENT: read_console_messages, read_network_requests
|
||||
|
||||
UTILITAIRES: shortcuts_list, shortcuts_execute,
|
||||
resize_window, update_plan
|
||||
```
|
||||
|
||||
### Playwright MCP (21 outils)
|
||||
|
||||
```
|
||||
NAVIGATION: navigate, goBack, goForward, reload
|
||||
|
||||
INTERACTION: click, fill, select, hover, press,
|
||||
drag, uploadFile
|
||||
|
||||
REQUÊTES D'ÉLÉMENTS: getElement, getElements, waitForSelector
|
||||
|
||||
ASSERTIONS: assertVisible, assertText, assertTitle
|
||||
|
||||
ÉTAT DE PAGE: screenshot, getAccessibilityTree,
|
||||
evaluateScript
|
||||
|
||||
GESTION NAVIGATEUR: newPage, closePage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Analyse des cas d'usage pour le test automatisé
|
||||
|
||||
### **Chrome DevTools MCP est le MEILLEUR pour :**
|
||||
|
||||
✅ **Test de performance**
|
||||
- Enregistrement de traces de performance avec les Core Web Vitals
|
||||
- Identification des goulots de rendu et des décalages de mise en page
|
||||
- Détection de fuites mémoire et profilage CPU
|
||||
|
||||
✅ **Débogage approfondi**
|
||||
- Inspection des requêtes réseau (en-têtes, payloads, timing)
|
||||
- Analyse des erreurs de console et stack traces
|
||||
- Inspection du DOM en temps réel
|
||||
|
||||
✅ **Pipelines CI/CD**
|
||||
- Support de l'exécution headless
|
||||
- Automatisation stable, basée sur des scripts
|
||||
- Aucune dépendance à l'état d'authentification
|
||||
|
||||
**Workflow idéal :** « Trouve pourquoi cette page est lente » ou « Débogue cet appel API »
|
||||
|
||||
---
|
||||
|
||||
### **Claude in Chrome est le MEILLEUR pour :**
|
||||
|
||||
✅ **Assistance au test manuel**
|
||||
- Tester en étant connecté à tes comptes
|
||||
- Test exploratoire avec contexte visuel
|
||||
- Enregistrer des workflows que tu peux rejouer
|
||||
|
||||
✅ **Vérification rapide**
|
||||
- Vérification de design (comparer Figma à la sortie)
|
||||
- Contrôle ponctuel de nouvelles fonctionnalités
|
||||
- Lecture des erreurs de console pendant le développement
|
||||
|
||||
✅ **Tâches de navigateur récurrentes**
|
||||
- Vérifications automatisées planifiées
|
||||
- Gestion de workflows multi-onglets
|
||||
- Apprentissage à partir de tes actions enregistrées
|
||||
|
||||
**Workflow idéal :** « Vérifie si mes changements ont l'air corrects » ou « Teste ce formulaire avec mon login »
|
||||
|
||||
---
|
||||
|
||||
### **Playwright MCP est le MEILLEUR pour :**
|
||||
|
||||
✅ **Automatisation de tests E2E**
|
||||
- Test multi-navigateur (Chrome, Firefox, Safari)
|
||||
- Génération de scripts de test réutilisables
|
||||
- Génération de Page Object Model
|
||||
|
||||
✅ **Test UI fiable**
|
||||
- Arbre d'accessibilité = pas de sélecteurs instables
|
||||
- Interactions déterministes
|
||||
- Moins sujet à la casse lors de changements d'UI
|
||||
|
||||
✅ **Intégration CI/CD**
|
||||
- Mode headless pour les pipelines
|
||||
- Génère des fichiers de test Playwright depuis le langage naturel
|
||||
- Intégration avec les outils de gestion de tests
|
||||
|
||||
**Workflow idéal :** « Écris des tests E2E pour ce parcours utilisateur » ou « Teste ceci sur plusieurs navigateurs »
|
||||
|
||||
---
|
||||
|
||||
## 5. Analyse de l'efficacité en tokens
|
||||
|
||||
| Outil | Usage de tokens | % du contexte | Note d'efficacité |
|
||||
|------|-------------|--------------|-------------------|
|
||||
| Playwright MCP | ~13,7k | 6,8% | ⭐⭐⭐⭐⭐ Meilleur |
|
||||
| Claude in Chrome | ~15,4k | 7,7% | ⭐⭐⭐⭐ Bon |
|
||||
| Chrome DevTools MCP | ~19,0k | 9,5% | ⭐⭐⭐ Acceptable |
|
||||
|
||||
**Impact :** Avec un contexte de 200k tokens :
|
||||
- Playwright laisse 186,3k tokens pour ton travail
|
||||
- Claude in Chrome laisse 184,6k tokens
|
||||
- Chrome DevTools laisse 181k tokens
|
||||
|
||||
La différence de ~5,3k tokens entre Playwright et Chrome DevTools peut compter pour des sessions complexes avec beaucoup de contexte de code.
|
||||
|
||||
---
|
||||
|
||||
## 6. Considérations de sécurité
|
||||
|
||||
### Chrome DevTools MCP
|
||||
- ✅ Profil de navigateur isolé par défaut
|
||||
- ✅ Aucune dépendance cloud
|
||||
- ✅ Contrôle local complet
|
||||
- ⚠️ Sécurité du port de débogage distant (utilise des profils isolés)
|
||||
|
||||
### Claude in Chrome
|
||||
- ⚠️ **Taux de succès d'attaque de 23,6%** sans mitigations (réduit à 11,2% avec défenses)
|
||||
- ⚠️ Utilise ta session de navigateur réelle (risque d'exposition de cookies)
|
||||
- ⚠️ Bloqué des sites financiers/adultes/piratés
|
||||
- ⚠️ Toujours en bêta avec des vulnérabilités connues
|
||||
|
||||
### Playwright MCP
|
||||
- ✅ Contextes de navigateur isolés
|
||||
- ✅ Aucune dépendance cloud
|
||||
- ✅ Modèle de sécurité mature (soutien de Microsoft)
|
||||
- ✅ Peut gérer l'authentification en sécurité
|
||||
|
||||
---
|
||||
|
||||
## 7. Commandes d'installation
|
||||
|
||||
### Chrome DevTools MCP
|
||||
|
||||
```bash
|
||||
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
|
||||
```
|
||||
|
||||
### Claude in Chrome
|
||||
|
||||
```
|
||||
Installer depuis le Chrome Web Store (requiert un plan Pro/Max/Team/Enterprise)
|
||||
```
|
||||
|
||||
### Playwright MCP (Recommandé)
|
||||
|
||||
```bash
|
||||
# D'abord, installer les navigateurs
|
||||
npx playwright install
|
||||
|
||||
# Puis ajouter à Claude Code (portée user = tous les projets)
|
||||
claude mcp add playwright -s user -- npx @playwright/mcp@latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Recommandations
|
||||
|
||||
### **Pour ton workflow de test automatisé :**
|
||||
|
||||
#### 🥇 **Outil principal : Playwright MCP**
|
||||
|
||||
**À utiliser pour :** Test E2E au quotidien, vérification multi-navigateur, génération de scripts de test
|
||||
|
||||
**Pourquoi :**
|
||||
- Usage de tokens le plus faible (plus de contexte pour ton code)
|
||||
- Support multi-navigateur (Chrome, Firefox, Safari)
|
||||
- Approche par arbre d'accessibilité = sélecteurs plus fiables
|
||||
- Excellente intégration CI/CD
|
||||
- Peut générer de vrais fichiers de test Playwright
|
||||
- Gratuit, aucun abonnement requis
|
||||
|
||||
#### 🥈 **Outil secondaire : Chrome DevTools MCP**
|
||||
|
||||
**À utiliser pour :** Débogage de performance, analyse réseau, Core Web Vitals
|
||||
|
||||
**Pourquoi :**
|
||||
- Inégalé pour les traces de performance et le débogage
|
||||
- Inspection approfondie des requêtes réseau
|
||||
- Outillage officiel Google avec support long terme
|
||||
- Essentiel quand tu dois répondre à « pourquoi est-ce lent ? »
|
||||
|
||||
#### 🥉 **Selon la situation : Claude in Chrome**
|
||||
|
||||
**À utiliser pour :** Vérification manuelle rapide en étant connecté, test exploratoire, vérification de design
|
||||
|
||||
**Pourquoi :**
|
||||
- Bon pour des contrôles visuels rapides pendant le développement
|
||||
- Peut lire ton état connecté
|
||||
- Utile pour la vérification « est-ce que ça a l'air correct ? »
|
||||
- À éviter pour le CI/CD ou l'automatisation de tests sérieuse
|
||||
|
||||
---
|
||||
|
||||
## 9. Configuration recommandée
|
||||
|
||||
```bash
|
||||
# Installer à la fois Playwright et Chrome DevTools MCP
|
||||
npx playwright install
|
||||
claude mcp add playwright -s user -- npx @playwright/mcp@latest
|
||||
claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest
|
||||
```
|
||||
|
||||
### Workflow suggéré
|
||||
|
||||
```
|
||||
1. DÉVELOPPER → Claude Code (terminal)
|
||||
2. TESTER → Playwright MCP (E2E, multi-navigateur)
|
||||
3. DÉBOGUER → Chrome DevTools MCP (performance, réseau)
|
||||
4. VÉRIFIER → Claude in Chrome (contrôles visuels rapides)
|
||||
5. CI/CD → Playwright MCP (headless, automatisé)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Verdict final
|
||||
|
||||
| Si tu as besoin de... | Utilise ceci |
|
||||
|----------------|----------|
|
||||
| Tests E2E multi-navigateur | **Playwright MCP** |
|
||||
| Analyse de performance | **Chrome DevTools MCP** |
|
||||
| Débogage réseau | **Chrome DevTools MCP** |
|
||||
| Vérification visuelle rapide | **Claude in Chrome** |
|
||||
| Automatisation CI/CD | **Playwright MCP** |
|
||||
| Génération de scripts de test | **Playwright MCP** |
|
||||
| Usage de tokens le plus faible | **Playwright MCP** |
|
||||
| Test de session connectée | **Claude in Chrome** |
|
||||
| Débogage de logs de console | **Chrome DevTools MCP** |
|
||||
|
||||
### **Recommandation TL;DR :**
|
||||
|
||||
**Installe à la fois Playwright MCP et Chrome DevTools MCP.** Utilise Playwright comme outil de test principal (plus économe en tokens, multi-navigateur, et meilleur pour l'E2E). Utilise Chrome DevTools quand tu as besoin d'une analyse de performance approfondie ou d'un débogage réseau. Utilise Claude in Chrome uniquement pour des vérifications manuelles rapides où tu as besoin de ta session connectée.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Chrome DevTools MCP - GitHub](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
- [Anthropic - Piloting Claude in Chrome](https://claude.com/blog/claude-for-chrome)
|
||||
- [Centre d'aide Claude in Chrome](https://support.claude.com/en/articles/12012173-getting-started-with-claude-in-chrome)
|
||||
- [Playwright MCP - GitHub](https://github.com/microsoft/playwright-mcp)
|
||||
- [Simon Willison - Using Playwright MCP with Claude Code](https://til.simonwillison.net/claude-code/playwright-mcp-claude-code)
|
||||
- [Testomat.io - Playwright MCP Claude Code](https://testomat.io/blog/playwright-mcp-claude-code/)
|
||||
- [MCP Integration Guide - Scrapeless](https://www.scrapeless.com/en/blog/mcp-integration-guide)
|
||||
- [Chrome DevTools MCP Guide - Vladimir Siedykh](https://vladimirsiedykh.com/blog/chrome-devtools-mcp-ai-browser-debugging-complete-guide-2025)
|
||||
- [Addy Osmani - Give your AI eyes](https://addyosmani.com/blog/devtools-mcp/)
|
||||
|
||||
---
|
||||
|
||||
*Ce rapport a été généré par Claude Code avec le modèle Opus 4.5 le 19 décembre 2025.*
|
||||
@@ -0,0 +1,158 @@
|
||||
# Comprendre la découverte des skills Claude dans les grands monorepos
|
||||
|
||||
Quand tu travailles avec Claude Code dans un monorepo, comprendre comment les skills sont découverts et chargés en contexte est crucial pour organiser efficacement les capacités propres à ton projet.
|
||||
|
||||
<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>
|
||||
|
||||
## Différence importante avec CLAUDE.md
|
||||
|
||||
**Les skills N'ONT PAS le même comportement de chargement que les fichiers CLAUDE.md.** Alors que les fichiers CLAUDE.md remontent l'arborescence (chargement des ancêtres), les skills utilisent un mécanisme de découverte différent, centré sur les répertoires imbriqués au sein de ton projet.
|
||||
|
||||
## Comment les skills sont découverts
|
||||
|
||||
### 1. Emplacements de skills standard
|
||||
|
||||
Les skills sont chargés depuis ces emplacements fixes selon la portée :
|
||||
|
||||
| Emplacement | Chemin | S'applique à |
|
||||
|----------|------|------------|
|
||||
| Entreprise | Managed settings | Tous les utilisateurs de l'organisation |
|
||||
| Personnel | `~/.claude/skills/<skill-name>/SKILL.md` | Tous tes projets |
|
||||
| Projet | `.claude/skills/<skill-name>/SKILL.md` | Ce projet uniquement |
|
||||
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Là où le plugin est activé |
|
||||
|
||||
### 2. Découverte automatique depuis les répertoires imbriqués
|
||||
|
||||
Quand tu travailles sur des fichiers dans des sous-répertoires, Claude Code découvre automatiquement les skills depuis les répertoires `.claude/skills/` imbriqués. Par exemple, si tu édites un fichier dans `packages/frontend/`, Claude Code cherche aussi des skills dans `packages/frontend/.claude/skills/`.
|
||||
|
||||
Cela supporte les configurations de monorepo où les packages ont leurs propres skills.
|
||||
|
||||
## Exemple de structure de monorepo
|
||||
|
||||
Considère un monorepo typique avec des packages séparés :
|
||||
|
||||
```
|
||||
/mymonorepo/
|
||||
├── .claude/
|
||||
│ └── skills/
|
||||
│ └── shared-conventions/SKILL.md # Skill au niveau projet
|
||||
├── packages/
|
||||
│ ├── frontend/
|
||||
│ │ ├── .claude/
|
||||
│ │ │ └── skills/
|
||||
│ │ │ └── react-patterns/SKILL.md # Skill spécifique au frontend
|
||||
│ │ └── src/
|
||||
│ │ └── App.tsx
|
||||
│ ├── backend/
|
||||
│ │ ├── .claude/
|
||||
│ │ │ └── skills/
|
||||
│ │ │ └── api-design/SKILL.md # Skill spécifique au backend
|
||||
│ │ └── src/
|
||||
│ └── shared/
|
||||
│ ├── .claude/
|
||||
│ │ └── skills/
|
||||
│ │ └── utils-patterns/SKILL.md # Skill d'utilitaires partagés
|
||||
│ └── src/
|
||||
```
|
||||
|
||||
## Scénario 1 : Claude vient de démarrer à la racine (aucun fichier édité)
|
||||
|
||||
Quand tu lances Claude Code depuis `/mymonorepo/` et n'as encore édité aucun fichier :
|
||||
|
||||
```bash
|
||||
cd /mymonorepo
|
||||
claude
|
||||
# Vient de démarrer - aucun fichier édité pour l'instant
|
||||
```
|
||||
|
||||
| Skill | En contexte ? | Raison |
|
||||
|-------|-------------|--------|
|
||||
| `shared-conventions` | **Oui** | Skill au niveau projet dans `.claude/skills/` racine |
|
||||
| `react-patterns` | **Non** | Non découvert - tu n'as pas travaillé avec des fichiers de `packages/frontend/` |
|
||||
| `api-design` | **Non** | Non découvert - tu n'as pas travaillé avec des fichiers de `packages/backend/` |
|
||||
| `utils-patterns` | **Non** | Non découvert - tu n'as pas travaillé avec des fichiers de `packages/shared/` |
|
||||
|
||||
## Scénario 2 : Après avoir édité des fichiers dans un package
|
||||
|
||||
Après que tu as demandé à Claude d'éditer `packages/frontend/src/App.tsx` :
|
||||
|
||||
| Skill | En contexte ? | Raison |
|
||||
|-------|-------------|--------|
|
||||
| `shared-conventions` | **Oui** | Skill au niveau projet dans `.claude/skills/` racine |
|
||||
| `react-patterns` | **Oui** | Découvert en éditant des fichiers de `packages/frontend/` |
|
||||
| `api-design` | **Non** | Toujours pas découvert - tu n'as pas travaillé avec des fichiers de `packages/backend/` |
|
||||
| `utils-patterns` | **Non** | Toujours pas découvert - tu n'as pas travaillé avec des fichiers de `packages/shared/` |
|
||||
|
||||
**Idée clé** : les skills imbriqués sont découverts **à la demande** quand tu travailles avec des fichiers dans ces répertoires. Ils ne sont pas préchargés au début de la session.
|
||||
|
||||
## Comportement clé : Description vs contenu complet
|
||||
|
||||
Les descriptions de skills sont chargées en contexte pour que Claude sache ce qui est disponible, mais **le contenu complet du skill ne se charge qu'à l'invocation**. C'est une optimisation importante :
|
||||
|
||||
- **Descriptions** : toujours en contexte (dans la limite de caractères)
|
||||
- **Contenu complet** : chargé à la demande quand le skill est invoqué
|
||||
|
||||
> Note : les sous-agents avec skills préchargés fonctionnent différemment — le contenu complet du skill est injecté au démarrage.
|
||||
|
||||
## Ordre de priorité (quand des skills partagent un nom)
|
||||
|
||||
Quand des skills partagent le même nom entre niveaux, les emplacements de plus haute priorité l'emportent :
|
||||
|
||||
| Priorité | Emplacement | Portée |
|
||||
|----------|----------|-------|
|
||||
| 1 (la plus haute) | Entreprise | Toute l'organisation |
|
||||
| 2 | Personnel (`~/.claude/skills/`) | Tous tes projets |
|
||||
| 3 (la plus basse) | Projet (`.claude/skills/`) | Ce projet uniquement |
|
||||
|
||||
Les skills de plugin utilisent un espace de noms `plugin-name:skill-name`, ils ne peuvent donc pas entrer en conflit avec les autres niveaux.
|
||||
|
||||
## Pourquoi ce design fonctionne pour les monorepos
|
||||
|
||||
- **Les skills propres à un package restent isolés** — Les développeurs frontend travaillant dans `packages/frontend/` obtiennent les skills frontend sans que les skills backend encombrent le contexte.
|
||||
|
||||
- **La découverte automatique réduit la configuration** — Pas besoin d'enregistrer explicitement les skills au niveau package ; ils sont découverts quand tu travailles dans ces répertoires.
|
||||
|
||||
- **Le contexte est optimisé** — Seules les descriptions de skills se chargent initialement, et les skills imbriqués sont découverts à la demande.
|
||||
|
||||
- **Les équipes peuvent maintenir leurs propres skills** — Chaque équipe de package peut définir des skills propres à son domaine sans se coordonner avec les autres équipes.
|
||||
|
||||
## Considérations sur la limite de caractères
|
||||
|
||||
Les descriptions de skills sont chargées en contexte jusqu'à une limite de caractères (défaut 15 000 caractères). Dans les grands monorepos avec de nombreux packages et skills, tu peux atteindre cette limite.
|
||||
|
||||
- Lance `/context` pour voir les avertissements concernant les skills exclus
|
||||
- Définis la variable d'environnement `SLASH_COMMAND_TOOL_CHAR_BUDGET` pour augmenter la limite
|
||||
|
||||
## Bonnes pratiques
|
||||
|
||||
1. **Mets les workflows partagés dans `.claude/skills/` racine** — Conventions valables pour tout le dépôt, workflows de commit et patterns partagés.
|
||||
|
||||
2. **Mets les skills propres à un package dans le `.claude/skills/` du package** — Patterns propres au framework, conventions de composants, utilitaires de test uniques à ce package.
|
||||
|
||||
3. **Utilise `disable-model-invocation: true` pour les skills dangereux** — Les skills de déploiement ou destructeurs devraient requérir une invocation explicite de l'utilisateur.
|
||||
|
||||
4. **Garde les descriptions de skills concises** — Les descriptions sont toujours en contexte (dans la limite de caractères), donc des descriptions verbeuses gaspillent de l'espace de contexte.
|
||||
|
||||
5. **Utilise des espaces de noms dans les noms de skills** — Envisage de préfixer avec les noms de packages (par ex. `frontend-review`, `backend-deploy`) pour éviter la confusion.
|
||||
|
||||
## Comparaison : chargement Skills vs CLAUDE.md
|
||||
|
||||
| Comportement | CLAUDE.md | Skills |
|
||||
|----------|-----------|--------|
|
||||
| Chargement des ancêtres (vers le HAUT de l'arborescence) | Oui | Non |
|
||||
| Découverte imbriquée/descendante (vers le BAS de l'arborescence) | Oui (paresseux) | Oui (découverte automatique) |
|
||||
| Emplacement global | `~/.claude/CLAUDE.md` | `~/.claude/skills/` |
|
||||
| Emplacement projet | `.claude/` ou racine du dépôt | `.claude/skills/` |
|
||||
| Chargement du contenu | Contenu complet | Description seule (complet à l'invocation) |
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Documentation Claude Code - Étendre Claude avec les skills](https://code.claude.com/docs/en/skills)
|
||||
- [Documentation Claude Code - Découverte automatique depuis les répertoires imbriqués](https://code.claude.com/docs/en/skills#automatic-discovery-from-nested-directories)
|
||||
@@ -0,0 +1,111 @@
|
||||
# Claude Code : Le spinner
|
||||
|
||||
Les mots qui tournent et les astuces affichés sous le spinner de Claude Code. Extraits de `~/.local/share/claude/versions/2.1.121`.
|
||||
|
||||
> **Note :** les verbes et astuces ci-dessous sont les **chaînes d'interface réelles** affichées par le CLI (en anglais). Ils sont conservés tels quels pour refléter fidèlement ce que le produit montre.
|
||||
|
||||
<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>
|
||||
|
||||
## Mots du spinner
|
||||
|
||||
| # | Verbe | # | Verbe | # | Verbe | # | Verbe |
|
||||
|---:|---|---:|---|---:|---|---:|---|
|
||||
| 1 | Accomplishing | 48 | Discombobulating | 95 | Levitating | 142 | Sketching |
|
||||
| 2 | Actioning | 49 | Doing | 96 | Lollygagging | 143 | Slithering |
|
||||
| 3 | Actualizing | 50 | Doodling | 97 | Manifesting | 144 | Smooshing |
|
||||
| 4 | Architecting | 51 | Drizzling | 98 | Marinating | 145 | Sock-hopping |
|
||||
| 5 | Baking | 52 | Ebbing | 99 | Meandering | 146 | Spelunking |
|
||||
| 6 | Beaming | 53 | Effecting | 100 | Metamorphosing | 147 | Spinning |
|
||||
| 7 | Beboppin' | 54 | Elucidating | 101 | Misting | 148 | Sprouting |
|
||||
| 8 | Befuddling | 55 | Embellishing | 102 | Moonwalking | 149 | Stewing |
|
||||
| 9 | Billowing | 56 | Enchanting | 103 | Moseying | 150 | Sublimating |
|
||||
| 10 | Blanching | 57 | Envisioning | 104 | Mulling | 151 | Swirling |
|
||||
| 11 | Bloviating | 58 | Evaporating | 105 | Mustering | 152 | Swooping |
|
||||
| 12 | Boogieing | 59 | Fermenting | 106 | Musing | 153 | Symbioting |
|
||||
| 13 | Boondoggling | 60 | Fiddle-faddling | 107 | Nebulizing | 154 | Synthesizing |
|
||||
| 14 | Booping | 61 | Finagling | 108 | Nesting | 155 | Tempering |
|
||||
| 15 | Bootstrapping | 62 | Flambéing | 109 | Newspapering | 156 | Thinking |
|
||||
| 16 | Brewing | 63 | Flibbertigibbeting | 110 | Noodling | 157 | Thundering |
|
||||
| 17 | Bunning | 64 | Flowing | 111 | Nucleating | 158 | Tinkering |
|
||||
| 18 | Burrowing | 65 | Flummoxing | 112 | Orbiting | 159 | Tomfoolering |
|
||||
| 19 | Calculating | 66 | Fluttering | 113 | Orchestrating | 160 | Topsy-turvying |
|
||||
| 20 | Canoodling | 67 | Forging | 114 | Osmosing | 161 | Transfiguring |
|
||||
| 21 | Caramelizing | 68 | Forming | 115 | Perambulating | 162 | Transmuting |
|
||||
| 22 | Cascading | 69 | Frolicking | 116 | Percolating | 163 | Twisting |
|
||||
| 23 | Catapulting | 70 | Frosting | 117 | Perusing | 164 | Undulating |
|
||||
| 24 | Cerebrating | 71 | Gallivanting | 118 | Philosophising | 165 | Unfurling |
|
||||
| 25 | Channeling | 72 | Galloping | 119 | Photosynthesizing | 166 | Unravelling |
|
||||
| 26 | Channelling | 73 | Garnishing | 120 | Pollinating | 167 | Vibing |
|
||||
| 27 | Choreographing | 74 | Generating | 121 | Pondering | 168 | Waddling |
|
||||
| 28 | Churning | 75 | Gesticulating | 122 | Pontificating | 169 | Wandering |
|
||||
| 29 | Clauding | 76 | Germinating | 123 | Pouncing | 170 | Warping |
|
||||
| 30 | Coalescing | 77 | Gitifying | 124 | Precipitating | 171 | Whatchamacalliting |
|
||||
| 31 | Cogitating | 78 | Grooving | 125 | Prestidigitating | 172 | Whirlpooling |
|
||||
| 32 | Combobulating | 79 | Gusting | 126 | Processing | 173 | Whirring |
|
||||
| 33 | Composing | 80 | Harmonizing | 127 | Proofing | 174 | Whisking |
|
||||
| 34 | Computing | 81 | Hashing | 128 | Propagating | 175 | Wibbling |
|
||||
| 35 | Concocting | 82 | Hatching | 129 | Puttering | 176 | Working |
|
||||
| 36 | Considering | 83 | Herding | 130 | Puzzling | 177 | Wrangling |
|
||||
| 37 | Contemplating | 84 | Honking | 131 | Quantumizing | 178 | Zesting |
|
||||
| 38 | Cooking | 85 | Hullaballooing | 132 | Razzle-dazzling | 179 | Zigzagging |
|
||||
| 39 | Crafting | 86 | Hyperspacing | 133 | Razzmatazzing | | |
|
||||
| 40 | Creating | 87 | Ideating | 134 | Recombobulating | | |
|
||||
| 41 | Crunching | 88 | Imagining | 135 | Reticulating | | |
|
||||
| 42 | Crystallizing | 89 | Improvising | 136 | Roosting | | |
|
||||
| 43 | Cultivating | 90 | Incubating | 137 | Ruminating | | |
|
||||
| 44 | Deciphering | 91 | Inferring | 138 | Sautéing | | |
|
||||
| 45 | Deliberating | 92 | Infusing | 139 | Scampering | | |
|
||||
| 46 | Determining | 93 | Ionizing | 140 | Schlepping | | |
|
||||
| 47 | Dilly-dallying | 94 | Jitterbugging | 141 | Scurrying | | |
|
||||
|
||||
## Astuces (tips)
|
||||
|
||||
| ID | Texte |
|
||||
|---|---|
|
||||
| new-user-warmup | Start with small features or bug fixes, tell Claude to propose a plan, and verify its suggested edits |
|
||||
| default-permission-mode-config | Use /config to change your default permission mode (including Plan Mode) |
|
||||
| git-worktrees | Use git worktrees to run multiple Claude sessions in parallel. |
|
||||
| color-when-multi-clauding | Running multiple Claude sessions? Use /color and /rename to tell them apart at a glance. |
|
||||
| memory-command | Use /memory to view and manage Claude memory |
|
||||
| theme-command | Use /theme to change the color theme |
|
||||
| colorterm-truecolor | Try setting environment variable COLORTERM=truecolor for richer colors |
|
||||
| powershell-tool-env | Set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to enable the PowerShell tool (preview) |
|
||||
| status-line | Use /statusline to set up a custom status line that will display beneath the input box |
|
||||
| prompt-queue | Hit Enter to queue up additional messages while Claude is working. |
|
||||
| enter-to-steer-in-relatime | Send messages to Claude while it works to steer Claude in real-time |
|
||||
| todo-list | Ask Claude to create a todo list when working on complex tasks to track progress and remain on track |
|
||||
| ide-upsell-external-terminal | Connect Claude to your IDE · /ide |
|
||||
| install-github-app | Run /install-github-app to tag @claude right from your Github issues and PRs |
|
||||
| install-slack-app | Run /install-slack-app to use Claude in Slack |
|
||||
| permissions | Use /permissions to pre-approve and pre-deny bash, edit, and MCP tools |
|
||||
| drag-and-drop-images | Did you know you can drag and drop image files into your terminal? |
|
||||
| paste-images-mac | Paste images into Claude Code using control+v (not cmd+v!) |
|
||||
| double-esc | Double-tap esc to rewind the conversation to a previous point in time |
|
||||
| double-esc-code-restore | Double-tap esc to rewind the code and/or conversation to a previous point in time |
|
||||
| continue | Run claude --continue or claude --resume to resume a conversation |
|
||||
| rename-conversation | Name your conversations with /rename to find them easily in /resume later |
|
||||
| custom-commands | Create skills by adding .md files to .claude/skills/ in your project or ~/.claude/skills/ for skills that work in any project |
|
||||
| custom-agents | Use /agents to optimize specific tasks. Eg. Software Architect, Code Writer, Code Reviewer |
|
||||
| agent-flag | Use --agent <agent_name> to directly start a conversation with a subagent |
|
||||
| desktop-app | Run Claude Code locally or remotely using the Claude desktop app: clau.de/desktop |
|
||||
| web-app | Run tasks in the cloud while you keep coding locally · clau.de/web |
|
||||
| voice-mode | Use /voice to enable push-to-talk dictation |
|
||||
| no-flicker | Try flicker-free rendering, now with mouse support · /tui fullscreen |
|
||||
| team-artifacts | Surfaces team artifact suggestions from team-discovery state |
|
||||
| plan-mode-for-complex-tasks | Use Plan Mode to prepare for a complex request before making changes. Press <cycle-mode key> |
|
||||
| terminal-setup | Run /terminal-setup to enable convenient terminal integration like Option+Enter for new line and more |
|
||||
| shift-enter | Press Option+Enter (Apple Terminal) or Shift+Enter to send a multi-line message |
|
||||
| shift-enter-setup | Run /terminal-setup to enable Option+Enter (Apple Terminal) or Shift+Enter for new lines |
|
||||
| vscode-command-install | Open the Command Palette (Cmd+Shift+P) and run "Shell Command: Install '<editor>' command in PATH" to enable IDE integration |
|
||||
| shift-tab | Hit <cycle-mode key> to switch chat modes |
|
||||
| image-paste | Use <image-paste key> to paste images |
|
||||
| desktop-shortcut | Continue your session in Claude Code Desktop with <suggested shortcut> |
|
||||
| remote-control | Pair this session to your phone via remote control |
|
||||
| push-notif | Get pinged on your phone when long tasks finish — enable push notifications in <settings menu> |
|
||||
| opusplan-mode-reminder | Your default model setting is Opus Plan Mode. Press <cycle-mode key> |
|
||||
| frontend-design-plugin | Working with HTML/CSS? Install the frontend-design plugin |
|
||||
@@ -0,0 +1,108 @@
|
||||
# Claude Code : Usage, limites de débit & usage supplémentaire
|
||||
|
||||
Comprendre comment fonctionnent les limites d'usage dans Claude Code et comment continuer à travailler quand tu les atteins.
|
||||
|
||||
<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>
|
||||
|
||||
---
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Claude Code sur les plans par abonnement (Pro, Max 5x, Max 20x) a des limites d'usage qui se réinitialisent sur une fenêtre glissante. Trois commandes slash intégrées t'aident à surveiller et gérer l'usage :
|
||||
|
||||
| Commande | Description | Disponible pour |
|
||||
|---------|-------------|--------------|
|
||||
| `/usage` | Vérifier les limites du plan et le statut de la limite de débit | Pro, Max 5x, Max 20x |
|
||||
| `/extra-usage` | Configurer le dépassement à la consommation quand les limites sont atteintes | Pro, Max 5x, Max 20x |
|
||||
| `/cost` | Afficher l'usage de tokens et la dépense pour la session courante | Utilisateurs avec clé API |
|
||||
|
||||
---
|
||||
|
||||
## `/usage` — Vérifier tes limites
|
||||
|
||||
Affiche les limites d'usage de ton plan actuel et le statut de la limite de débit. Utile pour vérifier combien de capacité il te reste avant d'atteindre une limite.
|
||||
|
||||
---
|
||||
|
||||
## `/extra-usage` — Continuer au-delà des limites
|
||||
|
||||
La commande `/extra-usage` configure une **facturation de dépassement à la consommation** pour que Claude Code continue à travailler de façon transparente quand tu atteins les limites de débit de ton plan, au lieu de te bloquer.
|
||||
|
||||
### Comment ça fonctionne
|
||||
|
||||
1. Tu atteins la limite de débit de ton plan (les limites se réinitialisent toutes les 5 heures)
|
||||
2. Si l'usage supplémentaire est activé avec des fonds disponibles, Claude Code continue sans interruption
|
||||
3. Les tokens de dépassement sont facturés au **tarif API standard**, séparément de ton abonnement
|
||||
|
||||
### Mise en place
|
||||
|
||||
La commande `/extra-usage` dans le CLI te guide dans la configuration. Tu peux aussi la configurer sur le web dans **Settings > Usage** sur claude.ai :
|
||||
|
||||
1. Active l'usage supplémentaire
|
||||
2. Ajoute un moyen de paiement
|
||||
3. Définis un **plafond de dépense mensuel** (ou choisis illimité)
|
||||
4. Optionnellement, ajoute des **fonds prépayés** avec rechargement automatique quand le solde descend sous un seuil
|
||||
|
||||
### Détails clés
|
||||
|
||||
| Détail | Valeur |
|
||||
|--------|-------|
|
||||
| Limite de consommation quotidienne | 2 000 $/jour |
|
||||
| Facturation | Séparée de l'abonnement, au tarif API standard |
|
||||
| Fenêtre de réinitialisation des limites | Toutes les 5 heures |
|
||||
|
||||
### Problème connu
|
||||
|
||||
En février 2026, la commande CLI `/extra-usage` est [non documentée](https://github.com/anthropics/claude-code/issues/12396) et peut ouvrir une fenêtre de connexion sans options de configuration claires. Configurer via l'**interface web claude.ai** est la voie la plus fiable pour l'instant.
|
||||
|
||||
---
|
||||
|
||||
## `/cost` — Dépense de session (utilisateurs API)
|
||||
|
||||
Pour les utilisateurs s'authentifiant avec une clé API (pas un plan par abonnement), `/cost` affiche :
|
||||
|
||||
- Le coût total de la session courante
|
||||
- La durée API et le temps mur
|
||||
- La répartition de l'usage de tokens
|
||||
- Les changements de code effectués
|
||||
|
||||
Cette commande n'est pas pertinente pour les abonnés Pro/Max.
|
||||
|
||||
---
|
||||
|
||||
## Mode Fast et usage supplémentaire
|
||||
|
||||
Le mode fast (`/fast`) utilise Claude Opus 4.6 avec une sortie plus rapide. Il a une relation de facturation particulière avec l'usage supplémentaire :
|
||||
|
||||
- L'usage du mode fast est **toujours facturé à l'usage supplémentaire** dès le premier token
|
||||
- Cela s'applique même s'il te reste de l'usage sur ton plan par abonnement
|
||||
- Le mode fast ne consomme pas les limites de débit incluses de ton plan
|
||||
|
||||
Cela signifie que tu dois avoir l'usage supplémentaire activé et approvisionné pour utiliser `/fast`.
|
||||
|
||||
---
|
||||
|
||||
## Drapeaux de démarrage du CLI
|
||||
|
||||
Deux drapeaux de démarrage concernent les budgets d'usage (utilisateurs avec clé API uniquement, mode print) :
|
||||
|
||||
| Drapeau | Description |
|
||||
|------|-------------|
|
||||
| `--max-budget-usd <AMOUNT>` | Montant maximum en dollars pour les appels API avant arrêt |
|
||||
| `--max-turns <NUMBER>` | Limiter le nombre de tours agentiques |
|
||||
|
||||
Voir la [Référence des drapeaux de démarrage du CLI](../best-practice/claude-cli-startup-flags.md) pour la liste complète.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Usage supplémentaire pour les plans Claude payants — Centre d'aide Claude](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)
|
||||
- [Utiliser Claude Code avec ton plan Pro ou Max — Centre d'aide Claude](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
|
||||
- [La commande slash /extra-usage est non documentée — GitHub Issue #12396](https://github.com/anthropics/claude-code/issues/12396)
|
||||
- [Référence CLI Claude Code](https://code.claude.com/docs/en/cli-reference)
|
||||
@@ -0,0 +1,262 @@
|
||||
# Parcours d'apprentissage — Plan de refonte du Weather Reporter
|
||||
|
||||
← Retour au [README](../README.md)
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Refondre toutes les slides à partir de la slide 7 autour d'un seul exemple fil rouge : l'**agent reporter météo** (weather reporter agent). L'arc narratif suit l'ordre visible de la TOC (Agents → Skills → Context → CLAUDE.md → Commands+Workflow), permettant à l'audience de rencontrer d'abord le reporter météo, puis de comprendre ce qu'il sait, comment il pense, quelles règles il suit, et enfin comment le déclencher avec une seule commande.
|
||||
|
||||
---
|
||||
|
||||
## 1. Correspondance section actuelle → nouvelle
|
||||
|
||||
| Section actuelle | Slides actuelles | Action | Nouvelle position |
|
||||
|---|---|---|---|
|
||||
| Topic 1 : Context | 7-11 (section en 7) | Déplacer vers Topic 3 | slides 17-21 |
|
||||
| Topic 2 : CLAUDE.md | 12-17 (section en 12) | Déplacer vers Topic 4 | slides 22-27 |
|
||||
| Topic 3 : Agents | 18-23 (section en 18) | Déplacer vers Topic 1 | slides 7-12 |
|
||||
| Topic 4 : Skills | 24-29 (section en 24) | Déplacer vers Topic 2 | slides 13-18 |
|
||||
| Topic 5 : Commands | 30-32 (section en 30) | Fusionner avec Workflow dans Topic 5 | slides 28-32 |
|
||||
| Topic 6 : Workflow | 33-36 (section en 33) | Fusionné dans la section Commands | (pas de slide de section séparée) |
|
||||
| Slide de clôture | 37 | Conserver, mettre à jour le sous-titre | slide 33 |
|
||||
|
||||
**Nouveau total : 33 slides** (identique aux 37 actuelles moins la slide de section Workflow et 3 slides de contenu Workflow qui fusionnent dans la section Commands, laquelle grossit de ces 3 slides).
|
||||
|
||||
Attends — recomptons :
|
||||
|
||||
Actuel : slides 7-37 = 31 slides.
|
||||
- Section Agents : 6 slides (18-23) → devient Topic 1 (7-12)
|
||||
- Section Skills : 6 slides (24-29) → devient Topic 2 (13-18)
|
||||
- Section Context : 5 slides (7-11) → devient Topic 3 (19-23)
|
||||
- Section CLAUDE.md : 6 slides (12-17) → devient Topic 4 (24-29)
|
||||
- Commands+Workflow fusionnées : 3 + 1 section + 4 contenu = Commands (3) + Workflow (1 section + 3 contenu) = 7 slides → devient Topic 5 (30-36)
|
||||
- Clôture : 1 slide (37)
|
||||
|
||||
**Nouveau total : 37 slides.** (Aucune slide n'est supprimée ; la slide de section Workflow devient partie de la section fusionnée Commands+Workflow — on la garde comme sous-section ou on retire son `data-level` pour éviter un second séparateur de section.)
|
||||
|
||||
**Décision** : Conserver les 37 slides. Retirer `data-level` sur l'ancien séparateur de section Workflow (slide 33) pour qu'il soit traité comme slide de contenu, pas comme séparateur de section. La section Commands couvre 30-36. Le séparateur de section Workflow devient un « en-tête de chapitre » visuel à l'intérieur de la section Commands.
|
||||
|
||||
En fait, plus simple : garder le séparateur de section Workflow comme slide de contenu sans `data-level`. La barre de parcours reste au niveau `commands`. Le texte de numéro de section passe de « Topic 6 » à un simple sous-titre.
|
||||
|
||||
---
|
||||
|
||||
## 2. Nouvelle carte LEVELS (aucun changement de clés ni de couleurs)
|
||||
|
||||
Le nouvel ordre de section est : **Agents → Skills → Context → CLAUDE.md → Commands**. La clé de niveau `workflow` est retirée de l'usage `data-level` (le séparateur de section perd `data-level`). La carte `LEVELS` porte toujours `workflow` pour l'affichage de l'historique de la barre de parcours, mais aucune slide ne le déclenche.
|
||||
|
||||
**Approche révisée** : Retirer entièrement le niveau `workflow` de la carte LEVELS puisqu'aucune slide ne porte `data-level="workflow"`. La barre de parcours plafonne à `commands` (83%). C'est correct — la section Workflow est présentée comme l'apogée *à l'intérieur* de la section Commands, pas un sujet séparé.
|
||||
|
||||
En fait, une barre de parcours qui se remplit à 83% plutôt que 100% pour une section de clôture est insatisfaisant. Meilleur plan : **fusionner Commands+Workflow en une seule section appelée « Commands & Workflow »** avec `data-level="commands"`. Garder le niveau `workflow` dans LEVELS à 100% et assigner `data-level="workflow"` à l'*ancienne* slide-séparateur de section Workflow — elle devient une transition visuelle dans la section Commands. Ainsi la barre se remplit à 100% aux slides Workflow.
|
||||
|
||||
**Décision finale** : Garder à la fois `commands` (83%) et `workflow` (100%) dans LEVELS. Assigner `data-level="commands"` au séparateur de section Commands et `data-level="workflow"` à la slide de sous-section Workflow. Les graduations de parcours restent telles quelles. Cela correspond exactement à la structure actuelle — seules les slides de contenu sont réordonnées.
|
||||
|
||||
---
|
||||
|
||||
## 3. Plan de contenu slide par slide
|
||||
|
||||
### Slides 1-6 (inchangées)
|
||||
|
||||
Slides 1 (titre), 2 (GIF Boris), 3 (Vibe→Agentic), 4 (Qu'est-ce que le Vibe Coding), 5 (Bons vs mauvais prompts), 6 (TOC — mettre à jour uniquement les cibles goToSlide).
|
||||
|
||||
**Mises à jour TOC sur la slide 6 :**
|
||||
- Ligne Agents : `goToSlide(7)` (était 18)
|
||||
- Ligne Skills : `goToSlide(13)` (était 24)
|
||||
- Ligne Context : `goToSlide(19)` (était 7)
|
||||
- Ligne CLAUDE.md : `goToSlide(25)` (était 12)
|
||||
- Ligne Commands : `goToSlide(30)` (était 30 — pas de changement)
|
||||
|
||||
---
|
||||
|
||||
### Section 1 : Agents (slides 7-12) — « La personne »
|
||||
|
||||
**Slide 7** — Séparateur de section (`data-level="agents"`, Topic 1)
|
||||
- Titre : « Agents — Le reporter météo »
|
||||
- Desc : « Un agent est Claude jouant un rôle spécifique. Voici le reporter météo — un spécialiste embauché pour récupérer et rapporter les données météo de Dubaï. »
|
||||
|
||||
**Slide 8** — « La cuisine du restaurant » (slide actuelle 19)
|
||||
- Contenu : même analogie (prompting simple = crier dans une cuisine au hasard ; agent = spécialiste précis)
|
||||
- Mettre à jour l'exemple d'agent pour utiliser le cadrage « reporter météo » partout
|
||||
- Garder la carte deux colonnes comparant prompting simple vs weather-agent
|
||||
|
||||
**Slide 9** — « Prompting vs. Agent — Côte à côte » (slide actuelle 20)
|
||||
- Garder la table intacte. Utilise déjà bien l'exemple météo.
|
||||
|
||||
**Slide 10** — « Les agents ont leur propre cerveau » (slide actuelle 21)
|
||||
- Garder l'astuce de Thariq. La relier à : « le reporter météo travaille dans son propre cerveau — toute cette récupération web reste en dehors du tien. »
|
||||
|
||||
**Slide 11** — « Comment créer ton propre agent » (slide actuelle 22)
|
||||
- Garder le pattern how-to `/agents`
|
||||
- Mettre à jour le bloc de code pour montrer le vrai chemin `weather-agent.md`
|
||||
|
||||
**Slide 12** — « Champs de config d'agent » (slide actuelle 23)
|
||||
- Garder la table des lignes de champs. Ajouter un encadré montrant le champ `skills: [weather-fetcher]` en contexte.
|
||||
|
||||
---
|
||||
|
||||
### Section 2 : Skills (slides 13-18) — « Ce que le reporter sait »
|
||||
|
||||
**Slide 13** — Séparateur de section (`data-level="skills"`, Topic 2)
|
||||
- Titre : « Skills — Ce que le reporter météo sait »
|
||||
- Desc : « Les skills sont les choses précises que le reporter a été entraîné à faire. Notre reporter en a deux : récupérer les données, et les rendre sous forme de carte. »
|
||||
|
||||
**Slide 14** — « Le manuel de formation » (slide actuelle 25)
|
||||
- Recadrer : le reporter météo a deux skills : weather-fetcher (va chercher la température) et weather-svg-creator (crée la carte visuelle).
|
||||
- Remplacer l'exemple « Shayan » par les deux skills du reporter météo.
|
||||
|
||||
**Slide 15** — « Quand transformer quelque chose en skill » (slide actuelle 26)
|
||||
- Garder l'astuce de Boris. Ajouter weather-fetcher et weather-svg-creator comme deux des exemples.
|
||||
|
||||
**Slide 16** — « Pourquoi séparer agents et skills ? » (slide actuelle 27)
|
||||
- Garder le deux colonnes. Mettre à jour pour souligner : weather-agent = la personne, weather-fetcher = sa formation.
|
||||
|
||||
**Slide 17** — « Comment créer ton propre skill » (slide actuelle 28)
|
||||
- Garder. Le bloc de code montre déjà le vrai contenu de `weather-fetcher` SKILL.md — parfait.
|
||||
|
||||
**Slide 18** — « Champs de config de skill » (slide actuelle 29)
|
||||
- Garder. Ajouter une note : `user-invocable: false` est défini sur weather-fetcher car il est réservé à l'agent.
|
||||
|
||||
---
|
||||
|
||||
### Section 3 : Context (slides 19-23) — « Le cerveau du reporter »
|
||||
|
||||
**Slide 19** — Séparateur de section (`data-level="context"`, Topic 3)
|
||||
- Titre : « Context — Le cerveau du reporter »
|
||||
- Desc : « Maintenant que tu as rencontré le reporter et connais ses skills, comprenons ce qu'il peut réellement garder en tête à la fois. »
|
||||
|
||||
**Slide 20** — « Le cerveau de Claude » (slide actuelle 8)
|
||||
- Garder. Ajouter une phrase reliant au reporter météo : « Quand le weather-agent est dépêché, il obtient son propre cerveau neuf — et weather-fetcher y est épinglé au démarrage. »
|
||||
- Garder les deux diagrammes (context-window.jpeg reste ici).
|
||||
|
||||
**Slide 21** — « Ce qui se charge au début de session » (slide actuelle 9)
|
||||
- Garder. Relier au reporter météo : « Au démarrage, Claude connaît *l'existence* de weather-fetcher (description seule). Quand la commande s'exécute, le contenu complet du skill est chargé dans le cerveau de l'agent. »
|
||||
- Garder context.jpg ici.
|
||||
|
||||
**Slide 22** — « Garder le cerveau clair » (slide actuelle 10)
|
||||
- Garder la table des points de branchement.
|
||||
|
||||
**Slide 23** — « Comment gérer ton contexte » (slide actuelle 11)
|
||||
- Garder le how-to `/context`, `/compact`, `/clear`.
|
||||
|
||||
---
|
||||
|
||||
### Section 4 : CLAUDE.md (slides 24-29) — « Le règlement de poche »
|
||||
|
||||
**Slide 24** — Séparateur de section (`data-level="claude-md"`, Topic 4)
|
||||
- Titre : « CLAUDE.md — Le règlement de poche du reporter »
|
||||
- Desc : « Le reporter le consulte au début de chaque service — même si son cerveau se réinitialise pendant la nuit. »
|
||||
|
||||
**Slide 25** — « Le manuel de l'employé » (slide actuelle 13)
|
||||
- Garder. Mettre à jour vers le cadrage reporter-météo : CLAUDE.md est le règlement que le reporter lit avant de passer à l'antenne — « toujours rapporter en Celsius sauf demande, toujours citer la source. »
|
||||
|
||||
**Slide 26** — « Comment créer ton CLAUDE.md » (slide actuelle 14)
|
||||
- Garder le how-to `/init`.
|
||||
|
||||
**Slide 27** — « Faire grandir CLAUDE.md à chaque erreur » (slide actuelle 15)
|
||||
- Garder l'astuce de Boris.
|
||||
|
||||
**Slide 28** — « Ce qui va dans CLAUDE.md » (slide actuelle 16)
|
||||
- Garder le bloc de code. Touche reporter météo : ajouter un commentaire montrant des règles spécifiques à la météo.
|
||||
|
||||
**Slide 29** — « Comment CLAUDE.md se charge » (slide actuelle 17)
|
||||
- Garder.
|
||||
|
||||
---
|
||||
|
||||
### Section 5 : Commands + Workflow (slides 30-36) — « Le déclencheur »
|
||||
|
||||
**Slide 30** — Séparateur de section (`data-level="commands"`, Topic 5)
|
||||
- Titre : « Commands — Le déclencheur »
|
||||
- Desc : « Un mot lance toute la chaîne. `/weather-orchestrator` → agent → skill → carte SVG. »
|
||||
|
||||
**Slide 31** — « Commands — Le point d'entrée » (slide actuelle 31)
|
||||
- Garder. Bonne intro. Référence déjà weather-orchestrator.
|
||||
|
||||
**Slide 32** — « Comment créer ta propre commande » (slide actuelle 32)
|
||||
- Garder. Le bloc de code montre déjà weather-orchestrator.md.
|
||||
|
||||
**Slide 33** — Sous-section Workflow (était slide 33, `data-level="workflow"`)
|
||||
- Changer le texte de numéro de section de « Topic 6 » à « Putting It All Together »
|
||||
- Garder `data-level="workflow"` pour que la barre se remplisse à 100%.
|
||||
- Mettre à jour le titre vers : « Workflow — Les cinq pièces ensemble »
|
||||
- Desc : « Regarde l'exemple du reporter météo s'exécuter d'une frappe de touche jusqu'à la sortie de carte SVG. »
|
||||
|
||||
**Slide 34** — « Command → Agent → Skill » (slide actuelle 34)
|
||||
- Garder le diagramme de flux en bloc de code. Il est déjà parfait.
|
||||
|
||||
**Slide 35** — « Deux façons d'utiliser les skills » (slide actuelle 35)
|
||||
- Garder le deux colonnes comparant préchargement vs invocation directe.
|
||||
|
||||
**Slide 36** — « Comment câbler ton propre workflow » (slide actuelle 36)
|
||||
- Garder. Utilise déjà le workflow météo comme exemple.
|
||||
|
||||
**Slide 37** — Clôture (slide actuelle 37)
|
||||
- Garder. Mettre à jour le sous-titre vers : « Cinq concepts, un seul exemple fil rouge »
|
||||
- Mettre à jour le texte du corps pour référencer l'arc du reporter météo.
|
||||
|
||||
---
|
||||
|
||||
## 4. Inventaire de réutilisation des assets
|
||||
|
||||
| Asset | Emplacement actuel | Nouvel emplacement | Action |
|
||||
|---|---|---|---|
|
||||
| `context-window.jpeg` | Slide 8 (Le cerveau de Claude) | Slide 20 (même contenu, renumérotée) | Survit — aucun changement nécessaire |
|
||||
| `context.jpg` | Slide 9 (Ce qui se charge au début de session) | Slide 21 (même contenu, renumérotée) | Survit — aucun changement nécessaire |
|
||||
| `../../!/claude-jumping.svg` | Slides 1, en-tête | Inchangé | Aucune action |
|
||||
| `../../!/root/boris-slider.gif` | Slide 2 | Inchangé | Aucune action |
|
||||
|
||||
Les deux diagrammes de contexte sont préservés exactement où ils sont — les slides qui les contiennent sont simplement renumérotées (8→20, 9→21).
|
||||
|
||||
---
|
||||
|
||||
## 5. Impact sur la comptabilité
|
||||
|
||||
### Nouvelles positions de séparateurs de section et assignations `data-level`
|
||||
|
||||
| Slide | Topic | `data-level` |
|
||||
|---|---|---|
|
||||
| 7 | Agents | `agents` |
|
||||
| 13 | Skills | `skills` |
|
||||
| 19 | Context | `context` |
|
||||
| 25 | CLAUDE.md | `claude-md` |
|
||||
| 30 | Commands | `commands` |
|
||||
| 33 | Sous-section Workflow | `workflow` |
|
||||
|
||||
### Cibles `goToSlide` de la TOC sur la slide 6
|
||||
|
||||
| Ligne | Topic | Ancienne cible | Nouvelle cible |
|
||||
|---|---|---|---|
|
||||
| Ligne 1 | Agents | 18 | 7 |
|
||||
| Ligne 2 | Skills | 24 | 13 |
|
||||
| Ligne 3 | Context | 7 | 19 |
|
||||
| Ligne 4 | CLAUDE.md | 12 | 25 |
|
||||
| Ligne 5 | Commands | 30 | 30 |
|
||||
|
||||
### Graduations de parcours (aucun changement)
|
||||
|
||||
Le rail de graduations de parcours est déjà ordonné de haut en bas comme : Workflow, Commands, Skills, Agents, CLAUDE.md, Context. C'est l'*inverse* de l'ordre de l'arc (haut = niveau le plus élevé = atteint en dernier). Aucun changement nécessaire.
|
||||
|
||||
### Carte LEVELS (aucun changement)
|
||||
|
||||
Les 6 clés de niveau (`context`, `claude-md`, `agents`, `skills`, `commands`, `workflow`) restent. Aucune clé ajoutée ou retirée.
|
||||
|
||||
---
|
||||
|
||||
## 6. Approche d'implémentation
|
||||
|
||||
Le HTML est un seul gros fichier. Les slides sont dans le mauvais ordre pour le nouvel arc. L'implémentation la plus propre est de :
|
||||
|
||||
1. Couper les divs de slides et les coller dans le nouvel ordre (7-12 = anciennes 18-23, 13-18 = anciennes 24-29, 19-23 = anciennes 7-11, 24-29 = anciennes 12-17, 30-37 inchangées).
|
||||
2. Renuméroter séquentiellement tous les attributs `data-slide`.
|
||||
3. Mettre à jour les attributs `data-level` des slides de section.
|
||||
4. Mettre à jour le texte de numéro de section et le h1 sur les séparateurs de section.
|
||||
5. Mettre à jour les cibles `goToSlide` de la TOC sur la slide 6.
|
||||
6. Mettre à jour le texte de numéro de section de la slide de section Workflow (ancienne 33).
|
||||
7. Faire des éditions de contenu ciblées vers le cadrage reporter-météo là où c'est requis.
|
||||
|
||||
Nombre total de slides : **37** (inchangé).
|
||||
|
||||
---
|
||||
|
||||
## 7. Ambiguïtés — aucune décisive
|
||||
|
||||
Toutes les ambiguïtés ont été résolues ci-dessus. On passe directement à l'implémentation.
|
||||
@@ -0,0 +1,360 @@
|
||||
# Dégradation quotidienne des LLM : mythe vs réalité
|
||||
|
||||
La performance d'un LLM déployé peut-elle changer d'un jour à l'autre alors même que les poids du modèle sont figés ? Une plongée en profondeur dans les causes avérées, les bugs d'infrastructure et les facteurs psychologiques.
|
||||
|
||||
<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 width="100%">
|
||||
<tr>
|
||||
<td width="50%"><a href="https://x.com/nicksdot/status/2029520949176049704"><img src="../../reports/assets/llm-degradation.png" alt="Utilisateurs Twitter rapportant une dégradation quotidienne de la qualité de Claude" width="100%" /></a></td>
|
||||
<td width="50%"><a href="https://x.com/levelsio/status/2029369159893569680"><img src="../../reports/assets/llm-degradation-2.png" alt="Utilisateurs Twitter rapportant une dégradation quotidienne de la qualité de Claude" width="100%" /></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
# 🔥 Analyse Claude Code Opus 4.6. High Reasoning
|
||||
|
||||
Quand Anthropic lance un modèle comme Opus 4.6, les **poids du modèle** — des milliards de paramètres appris — sont figés. L'entraînement est énormément coûteux (des millions de dollars, des semaines de calcul). Personne ne réentraîne le modèle du jour au lendemain.
|
||||
|
||||
Mais les poids ne sont qu'une couche d'un système bien plus large. La recherche révèle au moins **7 mécanismes distincts** pouvant causer des changements de qualité réels ou perçus, même quand les poids du modèle sont figés.
|
||||
|
||||
| Question | Réponse |
|
||||
|----------|--------|
|
||||
| Les poids du modèle changent-ils après le lancement ? | **Non** — confirmé par tous les fournisseurs |
|
||||
| Le modèle peut-il se comporter différemment au quotidien ? | **Oui** — prouvé avec une variance de ±8-14% |
|
||||
| Est-ce un « nerfing » intentionnel ? | **Non** — aucune preuve de dégradation délibérée |
|
||||
| Les bugs d'infrastructure sont-ils réels ? | **Oui** — Anthropic a confirmé 3 bugs affectant jusqu'à 16% des requêtes |
|
||||
| Une partie est-elle psychologique ? | **Oui** — le biais de confirmation et les effets lune de miel sont réels |
|
||||
| Les system prompts / le post-entraînement peuvent-ils changer ? | **Oui** — documenté chez les fournisseurs |
|
||||
| Les utilisateurs devraient-ils se fier à leur perception ? | **En partie** — des causes réelles existent, mais la perception les amplifie |
|
||||
|
||||
---
|
||||
|
||||
## La pile d'inférence complète
|
||||
|
||||
Les poids du modèle sont figés, mais **neuf couches au-dessus d'eux** peuvent indépendamment affecter ce que tu vis :
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ CONTEXTE DE TA SESSION │ ← Se dégrade en session
|
||||
│ (erreurs accumulées, longues conversations) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ SYSTEM PROMPT │ ← Mis à jour régulièrement
|
||||
│ (règles de sécurité, instructions de compo.) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ POST-ENTRAÎNEMENT (RLHF / Fine-tuning) │ ← Peut être mis à jour discrètement
|
||||
│ (suivi d'instructions, alignement sécurité) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ PARAMÈTRES D'ÉCHANTILLONNAGE │ ← Ajustables côté serveur
|
||||
│ (temperature, top-p, top-k) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ DÉCODAGE SPÉCULATIF │ ← Qualité du draft model variable
|
||||
│ (prédictions du draft model + vérification) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ ROUTAGE MoE / COMPOSITION DE BATCH │ ← variance ±8-14% prouvée
|
||||
│ (quels experts s'activent par requête) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ ROUTAGE MATÉRIEL │ ← TPU vs GPU vs Trainium
|
||||
│ (quel cluster sert ta requête) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ NIVEAU DE QUANTIFICATION │ ← Peut varier sous charge
|
||||
│ (précision FP16 vs INT8 vs INT4) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ COMPILATEUR & RUNTIME │ ← bugs XLA prouvés réels
|
||||
│ (XLA:TPU, CUDA, code spécifique au matériel) │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ POIDS DU MODÈLE (FIGÉS) │ ← Ceux-ci NE changent PAS
|
||||
│ (des milliards de paramètres appris) │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Le modèle mental clé : **poids figés ≠ comportement figé**. C'est comme dire « même moteur = même expérience de conduite » en ignorant les pneus, l'état de la route, la qualité du carburant et la fatigue du conducteur.
|
||||
|
||||
---
|
||||
|
||||
## Causes avérées : bugs d'infrastructure
|
||||
|
||||
### Le postmortem d'Anthropic de septembre 2025
|
||||
|
||||
En septembre 2025, Anthropic a publié un postmortem détaillé révélant **trois bugs d'infrastructure distincts** qui ont dégradé la qualité de Claude entre août et septembre 2025. Leur déclaration officielle :
|
||||
|
||||
> « Nous ne réduisons jamais la qualité du modèle en raison de la demande, de l'heure de la journée ou de la charge serveur. Les problèmes rapportés par nos utilisateurs étaient dus uniquement à des bugs d'infrastructure. »
|
||||
|
||||
### Bug nº1 — Erreur de routage de fenêtre de contexte
|
||||
|
||||
Des requêtes Sonnet 4 étaient accidentellement routées vers des serveurs configurés pour des fenêtres de contexte de 1M tokens au lieu de serveurs standard.
|
||||
|
||||
- **Chronologie** : Introduit le 5 août, aggravé le 29 août après un changement d'équilibrage de charge
|
||||
- **Impact maximal** : 16% des requêtes Sonnet 4 affectées à la pire heure (31 août)
|
||||
- **Impact utilisateur** : ~30% des utilisateurs de Claude Code ont eu au moins un message dégradé
|
||||
- **Détail insidieux** : Le routage était « collant » — une fois sur un mauvais serveur, les requêtes suivantes y restaient
|
||||
- **Corrigé** : 4–18 septembre (déployé sur les plateformes)
|
||||
|
||||
### Bug nº2 — Corruption de sortie TPU
|
||||
|
||||
Une mauvaise configuration sur les serveurs TPU causait des erreurs durant la génération de tokens, assignant une forte probabilité à des tokens qui devraient rarement apparaître.
|
||||
|
||||
- **Symptômes** : Caractères thaï ou chinois apparaissant au milieu d'une réponse en anglais, erreurs évidentes de syntaxe de code
|
||||
- **Affectés** : Opus 4.1 et Opus 4 (25–28 août), Sonnet 4 (25 août–2 septembre)
|
||||
- **Portée** : API Claude uniquement ; plateformes tierces non affectées
|
||||
- **Corrigé** : Rollback le 2 septembre
|
||||
|
||||
### Bug nº3 — Mauvaise compilation XLA:TPU (le plus vicieux)
|
||||
|
||||
Un changement de code destiné à corriger des problèmes de précision a accidentellement exposé un **bug de compilateur latent** dans le XLA:TPU de Google.
|
||||
|
||||
- **Cause racine** : L'opération approximate top-k (utilisée pour choisir les tokens suivants les plus probables) « renvoyait parfois des résultats complètement faux, mais uniquement pour certaines tailles de batch et configurations de modèle »
|
||||
- **Pourquoi il était difficile à trouver** : Il changeait de comportement selon les opérations exécutées avant ou après, et selon que les outils de débogage étaient activés ou non
|
||||
- **Caché pendant des mois** : Un contournement précédent de décembre 2024 avait accidentellement masqué ce bug plus profond
|
||||
- **Affectés** : Haiku 3.5 confirmé ; sous-ensemble de Sonnet 4 et Opus 3 suspectés
|
||||
- **Résolution** : Passage de l'approximate top-k à l'exact top-k ; « impact mineur d'efficacité » accepté car « La qualité du modèle est non négociable »
|
||||
|
||||
### Pourquoi la détection était difficile
|
||||
|
||||
Les évaluations automatisées d'Anthropic n'ont pas détecté la dégradation rapportée par les utilisateurs, « en partie parce que Claude se remet souvent bien des erreurs isolées ». Chaque bug produisait des symptômes différents sur différentes plateformes à des taux différents, créant « un mélange déroutant de rapports ne pointant vers aucune cause unique ».
|
||||
|
||||
Contexte clé : Claude tourne sur **trois plateformes matérielles différentes** (AWS Trainium, GPU NVIDIA, TPU Google), chacune avec des modes de défaillance, compilateurs et comportements de précision différents. Ta requête peut atterrir sur du matériel différent selon les jours.
|
||||
|
||||
---
|
||||
|
||||
## Causes avérées : variance de routage MoE
|
||||
|
||||
Les grands modèles modernes utilisent souvent une architecture **Mixture-of-Experts (MoE)**, où seul un sous-ensemble des paramètres du modèle (les « experts ») s'active pour chaque entrée. Un routeur appris décide quels experts utiliser.
|
||||
|
||||
La recherche de Scale AI a révélé un constat critique :
|
||||
|
||||
> « La combinaison de MoE sparse et d'inférence par batch crée des résultats imprévisibles car la composition d'un batch peut déterminer vers quel expert ta requête est routée, et le mélange de requêtes d'autres utilisateurs dans le même batch n'est pas déterministe. »
|
||||
|
||||
### Variance quotidienne mesurée chez les fournisseurs
|
||||
|
||||
| Fournisseur | Variance de score quotidienne |
|
||||
|----------|--------------------------|
|
||||
| OpenAI (variantes GPT-4) | ±10–12% |
|
||||
| Anthropic (variantes Claude) | ±8–11% |
|
||||
| Google (variantes Gemini) | ±9–14% |
|
||||
|
||||
Exemple concret : le même modèle a obtenu **77% de résistance au jailbreak un jour et 63% le lendemain**. Même modèle, mêmes poids, même test — 14 points de pourcentage d'écart dus à l'infrastructure seule.
|
||||
|
||||
Cela signifie que même avec zéro bug et zéro changement, le même modèle peut produire des sorties de qualité sensiblement différentes selon les jours, purement à cause de la façon dont les requêtes sont batchées et routées. Un test A/B ne peut détecter de façon fiable un signal de qualité de 5% quand le bruit quotidien est de 10–15%.
|
||||
|
||||
---
|
||||
|
||||
## Causes avérées : mises à jour du system prompt & du post-entraînement
|
||||
|
||||
### Changements de system prompt
|
||||
|
||||
Les poids du modèle ne changent pas, mais le **system prompt** qui enveloppe ces poids peut être mis à jour à tout moment. L'analyse de l'évolution du system prompt de Claude montre des dizaines d'itérations, avec des « hot-fixes » — courtes instructions ajoutées pour corriger un comportement indésirable — ajoutés et retirés régulièrement.
|
||||
|
||||
Le system prompt de Claude 3.7 contenait plusieurs instructions hot-fix ciblant des « pièges » courants des LLM. Le system prompt de Claude 4.0 les a tous retirés, les comportements étant traités pendant le post-entraînement via l'apprentissage par renforcement à la place.
|
||||
|
||||
### La théorie du post-entraînement
|
||||
|
||||
La théorie la plus plausible pour les changements de qualité inexpliqués : les entreprises peuvent mettre à jour le **fine-tuning et le RLHF** (apprentissage par renforcement à partir de retours humains) sans changer les poids du modèle de base. Cela rendrait techniquement vrai de dire « le modèle n'a pas changé » tout en altérant le comportement via des garde-fous de sécurité mis à jour et des ajustements de suivi d'instructions.
|
||||
|
||||
---
|
||||
|
||||
## Causes avérées : remplacements silencieux de modèle
|
||||
|
||||
OpenAI a été documenté à plusieurs reprises changeant silencieusement le modèle avec lequel les utilisateurs interagissent :
|
||||
|
||||
- Retrait du sélecteur de modèle du jour au lendemain, forçant les utilisateurs de GPT-4o vers GPT-5
|
||||
- Transformation de GPT-4o en « modèle hérité » caché nécessitant un toggle manuel dans les réglages, sans notification in-app
|
||||
- Un bug d'« autoswitcher » routant les utilisateurs vers de mauvais modèles
|
||||
- En plus, des abonnés ont rapporté des modèles basculant vers une « version restreinte » sans consentement
|
||||
|
||||
Sam Altman a reconnu que le déploiement était « un peu plus cahoteux qu'espéré ». Des fils Reddit ont reçu des milliers d'upvotes qualifiant le nouveau modèle de « désastre » et de « régression ».
|
||||
|
||||
Cela démontre que les remplacements de modèle **se produisent bel et bien** dans l'industrie — parfois intentionnellement (décisions produit) et parfois accidentellement (bugs de routage).
|
||||
|
||||
---
|
||||
|
||||
## Facteurs contributifs
|
||||
|
||||
### Quantification sous charge
|
||||
|
||||
Pour servir des millions d'utilisateurs de façon rentable, les entreprises peuvent servir des versions **quantifiées** des modèles — réduisant la précision de FP16 à INT8 ou INT4. Cela peut réduire l'usage mémoire de 2–4× et accélérer l'inférence, mais introduit une perte de qualité subtile. Que les fournisseurs basculent dynamiquement les niveaux de quantification sous charge est débattu, mais la capacité technique existe et est bien documentée dans les frameworks de serving comme vLLM et TensorRT.
|
||||
|
||||
### Décodage spéculatif
|
||||
|
||||
Les piles de serving modernes utilisent un plus petit modèle « draft » pour prédire plusieurs tokens à l'avance, puis font vérifier ceux-ci par le vrai modèle. Théoriquement cela préserve la même distribution de sortie, mais en pratique les taux d'acceptation varient selon le domaine et le contexte. Les draft models prêts à l'emploi peuvent bien fonctionner dans certains cas mais peinent souvent sur les tâches propres à un domaine ou les contextes très longs.
|
||||
|
||||
### Pollution de la fenêtre de contexte
|
||||
|
||||
Dans une longue session de code, les erreurs antérieures s'accumulent dans le contexte. Le modèle voit ses propres erreurs et peut les perpétuer. C'est la cause la plus courante de « Claude est devenu plus bête » au sein d'une même session — ce n'est pas le modèle qui se dégrade, c'est la contamination du contexte.
|
||||
|
||||
**Astuce pratique** : Utilise `/compact` ou démarre de nouvelles sessions quand la qualité semble en baisse. C'est la chose la plus actionnable que tu puisses faire.
|
||||
|
||||
---
|
||||
|
||||
## L'étude de Stanford — et pourquoi c'est compliqué
|
||||
|
||||
L'étude marquante de 2023 de Stanford et UC Berkeley (Chen, Zaharia, Zou) — « How is ChatGPT's Behavior Changing Over Time? » — est fréquemment citée comme preuve que les LLM se dégradent. Le constat phare :
|
||||
|
||||
> La précision de GPT-4 sur « Ce nombre est-il premier ? Réfléchis étape par étape » est tombée de **97,6% à 2,4%** entre mars et juin 2023.
|
||||
|
||||
### Ce que l'étude a prouvé
|
||||
|
||||
- Le comportement du « même » service LLM **peut changer substantiellement** sur une courte période
|
||||
- Différentes capacités peuvent évoluer en sens opposés (GPT-4 s'est dégradé en maths, GPT-3.5 s'est amélioré)
|
||||
- La qualité de génération de code a chuté (code exécutable GPT-4 : 52% → 10%)
|
||||
- L'étude a inventé le terme **« LLM drift »** (dérive des LLM)
|
||||
|
||||
### Critiques méthodologiques
|
||||
|
||||
- La version de mars utilisait **temperature 0,0** tandis que celle de juin utilisait **temperature 1,0** — une variable confondante fondamentale qui augmente l'aléatoire
|
||||
- Seulement **500 requêtes par tâche** — trop peu pour des affirmations statistiques définitives
|
||||
- Les « questions de maths » étaient en réalité des questions oui/non où le motif de devinette du modèle a changé, pas sa capacité mathématique
|
||||
- Les changements reflétaient probablement des **mises à jour de sécurité de post-entraînement** intentionnelles, pas une dégradation
|
||||
|
||||
L'étude a prouvé quelque chose d'important — le comportement des LLM change avec le temps — mais le mécanisme était probablement des mises à jour intentionnelles, pas une dégradation involontaire.
|
||||
|
||||
---
|
||||
|
||||
## La psychologie
|
||||
|
||||
### Biais de confirmation
|
||||
|
||||
Une fois que quelqu'un tweete « Claude est bête aujourd'hui », tu commences à remarquer chaque erreur. Les jours où personne ne se plaint, tu balaies les mêmes erreurs. Les réseaux sociaux amplifient cet effet.
|
||||
|
||||
### L'effet lune de miel
|
||||
|
||||
Les utilisateurs vivent une période de lune de miel initiale avec les nouveaux modèles, puis découvrent progressivement les limites. Le modèle n'a pas changé — les attentes se sont ajustées à la hausse plus vite que les capacités ne le justifiaient.
|
||||
|
||||
### Variance de difficulté des tâches
|
||||
|
||||
Tes tâches varient d'un jour à l'autre. Une journée de problèmes difficiles donne l'impression que le modèle s'est dégradé, même quand ce n'est pas le cas.
|
||||
|
||||
### Le mythe du « Claude du week-end »
|
||||
|
||||
Malgré la croyance de nombreux utilisateurs en des motifs selon le jour de la semaine, une analyse rigoureuse n'a trouvé **aucune preuve cohérente** de motifs de qualité selon le jour de la semaine. Une analyse intitulée « AI is Dumber on Mondays » n'a rien donné.
|
||||
|
||||
### Nature stochastique des LLM
|
||||
|
||||
Les LLM sont probabilistes. Le même prompt peut produire des sorties différentes à chaque fois. Sur une série de malchance, tu pourrais obtenir plusieurs réponses médiocres d'affilée — pur hasard, pas dégradation.
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
Le phénomène que les utilisateurs décrivent est **réel mais mal attribué** :
|
||||
|
||||
- **Correct** : leur expérience s'est dégradée certains jours
|
||||
- **Incorrect** : le modèle a été intentionnellement « nerfé »
|
||||
|
||||
Les causes réelles sont une combinaison de :
|
||||
|
||||
1. **Bugs d'infrastructure** — prouvés par le postmortem d'Anthropic (jusqu'à 16% des requêtes affectées)
|
||||
2. **Variance de routage MoE** — écart de qualité de ±8-14% mesuré par Scale AI, même avec zéro changement
|
||||
3. **Mises à jour du system prompt et du post-entraînement** — documentées chez les fournisseurs
|
||||
4. **Hétérogénéité matérielle** — TPU vs GPU vs Trainium, chacun avec des modes de défaillance différents
|
||||
5. **Pollution de contexte** — les longues sessions dégradent la qualité en session
|
||||
6. **Biais de confirmation** — les réseaux sociaux amplifient les motifs perçus
|
||||
7. **Variance stochastique** — même modèle, même prompt, sortie différente à chaque fois
|
||||
|
||||
Le problème de mesure est sévère : une variance quotidienne de ±8-14% signifie que tu ne peux pas distinguer un changement de qualité réel de 5% du bruit. C'est pourquoi les camps « c'est dans ta tête » et « ils l'ont nerfé » se sentent tous deux confiants — le rapport signal/bruit rend impossible de trancher à partir d'une expérience individuelle seule.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Anthropic: A Postmortem of Three Recent Issues](https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues) — Postmortem officiel détaillant trois bugs d'infrastructure (septembre 2025)
|
||||
- [Anthropic Reveals Three Infrastructure Bugs — InfoQ](https://www.infoq.com/news/2025/10/anthropic-infrastructure-bugs/) — Analyse technique du postmortem
|
||||
- [How is ChatGPT's Behavior Changing Over Time? — Stanford/UC Berkeley](https://arxiv.org/abs/2307.09009) — Étude marquante sur la dérive des LLM (2023)
|
||||
- [The Truth About ChatGPT's Degrading Capabilities — TechTalks](https://bdtechtalks.com/2023/07/24/chatgpt-capabilities-degrading-study/) — Critique méthodologique de l'étude de Stanford
|
||||
- [LLMs Are Getting Dumber and We Have No Idea Why — Ignorance.ai](https://www.ignorance.ai/p/llms-are-getting-dumber-and-we-have) — Cinq théories sur la dégradation perçue
|
||||
- [When Claude Forgets How to Code — Robert Matsuoka](https://hyperdev.matsuoka.com/p/when-claude-forgets-how-to-code) — Analyse des fluctuations de qualité de Claude et causes d'infrastructure
|
||||
- [Smoothing Out LLM Variance — Scale AI](https://scale.com/blog/smoothing-out-llm-variance) — Variance quotidienne de ±8-14% mesurée chez les fournisseurs
|
||||
- [What We Can Learn from Anthropic's System Prompt Updates — PromptLayer](https://blog.promptlayer.com/what-we-can-learn-from-anthropics-system-prompt-updates/) — Analyse de l'évolution du system prompt
|
||||
- [Claude's System Prompt Changes Reveal Anthropic's Priorities — Drew Breunig](https://www.dbreunig.com/2025/06/03/comparing-system-prompts-across-claude-versions.html) — Motifs de hot-fix dans les system prompts
|
||||
- [Complaints About Secretly Switching Models — OpenAI Forum](https://community.openai.com/t/complaints-about-secretly-switching-models/1360150) — Remplacements silencieux de modèle documentés
|
||||
- [Speculative Decoding — BentoML LLM Inference Handbook](https://bentoml.com/llm/inference-optimization/speculative-decoding) — Comment les draft models affectent le serving
|
||||
- [A Visual Guide to Mixture of Experts — Maarten Grootendorst](https://newsletter.maartengrootendorst.com/p/a-visual-guide-to-mixture-of-experts) — Architecture et routage MoE expliqués
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
# 🔥 Codex 5.3 High Reason and Finding
|
||||
|
||||
### Périmètre du rapport
|
||||
|
||||
Cette section explique pourquoi les utilisateurs peuvent vivre une courte fenêtre où la qualité de sortie de Claude chute tandis que Codex 5.3 semble stable ou plus fort sur les tâches de code. L'accent n'est pas sur des classements permanents de qualité de modèle. L'accent est sur le comportement de production à court horizon dans des conditions de serving réelles.
|
||||
|
||||
Date du rapport : 5 mars 2026.
|
||||
|
||||
### Motif observé
|
||||
|
||||
Le motif rapporté est :
|
||||
|
||||
1. La qualité du modèle est acceptable pendant une période.
|
||||
2. La qualité semble se dégrader pendant plusieurs jours.
|
||||
3. La qualité revient près de la base précédente.
|
||||
|
||||
Cette forme est généralement un motif de pile de serving ou de déploiement, pas un changement permanent de capacité du modèle de base. Un déclin permanent de capacité ne récupérerait normalement pas aussi vite sans rollback ou correctif explicite.
|
||||
|
||||
### High Reason : pourquoi Codex 5.3 peut paraître meilleur dans une mauvaise fenêtre
|
||||
|
||||
Codex 5.3 peut sembler nettement plus fort durant la période dégradée d'un autre fournisseur pour plusieurs raisons techniques pouvant toutes se produire en même temps :
|
||||
|
||||
1. Adéquation à l'objectif produit. Codex 5.3 est optimisé pour la génération de code et les workflows de codage agentiques, donc même une force brute de modèle égale peut produire de meilleurs résultats de code grâce à l'orchestration d'outils, au raisonnement sur dépôt et au tuning d'instructions centré code.
|
||||
2. Différences de politique d'inférence. Les fournisseurs règlent la latence, la profondeur de raisonnement et les défauts de décodage indépendamment. Une politique plus conservatrice chez un fournisseur peut paraître « plus intelligente » qu'une politique agressive optimisée vitesse chez un autre le même jour.
|
||||
3. Séparation des chemins de serving. Même si deux fournisseurs hébergent des modèles de pointe, ils exécutent des couches de routage, des piles compilateur/runtime et des pipelines de déploiement différents. Un incident dans une pile n'implique pas une dégradation corrélée dans l'autre.
|
||||
4. Timing de déploiement et de rollback. Si un fournisseur est en plein déploiement tandis qu'un autre est stable, les utilisateurs peuvent voir une large divergence temporaire de qualité sans changement de fond à long terme des poids du modèle.
|
||||
5. Effets de contamination au niveau session. Dans de longues conversations de code, l'accumulation d'erreurs peut amplifier le déclin perçu. Un assistant concurrent peut sembler meilleur simplement parce que la session défaillante a été réinitialisée ou parce que sa boucle d'outils a récupéré plus vite.
|
||||
|
||||
### Constat détaillé
|
||||
|
||||
Pour un rapport du type « Claude a paru très faible pendant environ quatre jours, puis est revenu », l'explication la plus probable est :
|
||||
|
||||
1. Un incident côté fournisseur, un problème de routage, un bug de décodage/runtime ou une régression de déploiement a affecté un sous-ensemble des requêtes.
|
||||
2. Le problème a persisté assez longtemps pour être remarqué de façon répétée dans des workflows réels.
|
||||
3. Le problème a été corrigé ou annulé (rollback).
|
||||
4. La qualité perçue est revenue rapidement.
|
||||
|
||||
Durant cette même période, Codex 5.3 pouvait sembler substantiellement meilleur car il ne partageait pas le même chemin d'incident et parce que l'optimisation pour les tâches de code amplifiait l'écart de résultats pratiques.
|
||||
|
||||
### Classement des hypothèses pour ce motif
|
||||
|
||||
| Hypothèse | Vraisemblance | Justification |
|
||||
|------------|------------|-----------|
|
||||
| Incident fournisseur plus rollback | Élevée | Meilleure correspondance pour un creux multi-jours suivi d'une récupération rapide |
|
||||
| Changement de configuration de serving (échantillonnage/latence/budget de raisonnement) | Élevée | Source courante de changements brusques de comportement sans réentraînement du modèle |
|
||||
| Mouvement silencieux d'alias ou de snapshot | Moyenne-Élevée | Peut changer le comportement sans action visible de l'utilisateur |
|
||||
| Dérive de prompt et contamination de contexte uniquement | Moyenne | Peut dégrader les sessions, mais moins susceptible d'expliquer seul de larges rapports multi-jours |
|
||||
| Dégradation permanente du modèle de base | Faible | Incohérente avec le retour rapide à la qualité précédente |
|
||||
|
||||
### Ce qui confirmerait ou réfuterait ce constat
|
||||
|
||||
Pour transformer cela d'une inférence à haute confiance en preuve solide, collecte de la télémétrie au niveau requête pour le même jeu de tâches sur plusieurs jours :
|
||||
|
||||
1. Identifiant exact du modèle et snapshot/alias au moment de la requête.
|
||||
2. Toute empreinte de backend ou marqueur de version exposé par le fournisseur.
|
||||
3. Paramètres de décodage (temperature, top_p, top_k, max tokens).
|
||||
4. Traces de latence, de timeout et de taux d'erreur.
|
||||
5. Scores de qualité structurés sur un jeu de prompts de benchmark de code fixe.
|
||||
6. Longueur de session et profondeur de contexte en tokens aux points de défaillance.
|
||||
|
||||
Si les baisses de qualité corrèlent avec une fenêtre d'incident, un changement de config ou un changement d'empreinte de backend, l'hypothèse incident/config est confirmée. Si aucun tel changement n'existe et que la dégradation n'est que dans les longues sessions, la contamination de contexte devient l'explication principale.
|
||||
|
||||
### Conseils d'ingénierie pratiques
|
||||
|
||||
Pour réduire la variance quotidienne en production :
|
||||
|
||||
1. Épingle les snapshots de modèle quand disponibles au lieu d'utiliser des alias flottants.
|
||||
2. Stocke les métadonnées de requête (ID de modèle, paramètres, latence, erreurs, label de qualité de réponse).
|
||||
3. Exécute une suite canary quotidienne fixe pour les tâches de code et alerte sur régression.
|
||||
4. Réinitialise ou compacte les sessions de longue haleine après plusieurs tours échoués.
|
||||
5. Garde un chemin de fournisseur/modèle de repli pour les fenêtres d'incident.
|
||||
6. Sépare « qualité du modèle » et « fiabilité de serving » dans les tableaux de bord internes.
|
||||
|
||||
### Conclusion finale
|
||||
|
||||
Codex 5.3 paraissant meilleur durant une courte fenêtre de dégradation de Claude est un résultat techniquement plausible et attendu dans les opérations LLM modernes. L'explication la plus solide n'est pas un effondrement permanent du modèle. L'explication la plus solide est une dégradation temporaire du chemin de serving chez un fournisseur, combinée à une optimisation spécifique au code et à un fonctionnement stable chez l'autre fournisseur durant la même période.
|
||||
@@ -0,0 +1,162 @@
|
||||
# Pourquoi le harnais est important
|
||||
|
||||
Pourquoi les fonctionnalités de Claude Code ne sont pas « juste des prompts déguisés » — et pourquoi le harnais est ce qui sépare réellement une sortie jouet d'un travail d'ingénierie de qualité production.
|
||||
|
||||
<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>
|
||||
|
||||
---
|
||||
|
||||
## Résumé exécutif
|
||||
|
||||
Une réduction courante chez les utilisateurs expérimentés de Claude Code est : *« skills, commandes, sous-agents, hooks — ils deviennent tous au final des prompts pour le modèle, donc un prompt solide à lui seul est équivalent. »*
|
||||
|
||||
À la couche de l'appel d'inférence final du modèle, c'est techniquement vrai. Le modèle ne voit jamais que des tokens.
|
||||
|
||||
À toutes les autres couches — celles où se déroule la vraie ingénierie logicielle — **cette réduction s'effondre.** Le harnais n'est pas un système de livraison de prompt. C'est un **système de construction de prompt, un système d'exécution déterministe et un système d'architecture de contexte** — et ces capacités ne peuvent être remplacées par une formulation plus forte.
|
||||
|
||||
Ce rapport explique où la réduction a raison, où elle échoue, et pourquoi confondre « ce que le modèle voit » avec « ce que le système fait » éloigne les praticiens des fonctionnalités qui donnent à Claude Code son levier réel.
|
||||
|
||||
---
|
||||
|
||||
## La réduction qui sonne juste
|
||||
|
||||
Pour une **tâche atomique en un seul coup** — « écris-moi une fonction Fibonacci récursive » — le harnais ne contribue en rien à la qualité de la sortie. Donne les mêmes tokens au même modèle et tu obtiens la même distribution de sorties, qu'ils soient arrivés via un skill, une commande ou un prompt brut.
|
||||
|
||||
Dans ce régime étroit, la réduction tient :
|
||||
|
||||
> Qualité de sortie ≈ Qualité du prompt
|
||||
|
||||
C'est le régime où Claude Code offre peu de valeur par rapport à un simple chatbot. C'est aussi le régime que la réduction suppose implicitement — et précisément celui dans lequel le vrai travail d'ingénierie ne se trouve pas.
|
||||
|
||||
---
|
||||
|
||||
## Où la réduction s'effondre
|
||||
|
||||
Dix capacités architecturales du harnais opèrent à des couches auxquelles les prompts n'ont pas accès.
|
||||
|
||||
| # | Capacité | Ce qu'elle fait | Pourquoi un prompt ne peut la répliquer |
|
||||
|---|------------|--------------|-------------------------------|
|
||||
| 1 | **Isolation de contexte** | Les sous-agents tournent dans des fenêtres de contexte séparées | Un prompt remplit une fenêtre. N sous-agents parallèles donnent ~N× de contexte effectif. |
|
||||
| 2 | **Restrictions d'outils imposées par le harnais** | `allowed-tools` / `disallowedTools` bloquent les outils avant que le modèle puisse les utiliser | Les instructions de prompt sont indicatives ; le modèle peut les ignorer. Les règles deny ne peuvent être ignorées. |
|
||||
| 3 | **Règles & mémoire en chargement paresseux** | Le frontmatter `paths:` et les fichiers `CLAUDE.md` descendants ne se chargent que lorsque Claude touche des chemins correspondants | Un prompt est statique — il ne peut charger conditionnellement selon les fichiers lus à l'exécution. |
|
||||
| 4 | **Hooks : exécution de code déterministe** | Des commandes shell s'exécutent à des événements de cycle de vie (PreToolUse, PostToolUse, Stop, etc.) et peuvent **bloquer** des appels d'outils | Un prompt ne peut intercepter ses propres appels d'outils. Les hooks s'exécutent même si le modèle ne « veut » pas. |
|
||||
| 5 | **Routage de modèle** | `model: haiku` ou `model: opus` route un appel vers un endpoint de modèle différent | Aucun token du prompt ne peut changer quel modèle répond. |
|
||||
| 6 | **Parallélisme** | Plusieurs sous-agents s'exécutent simultanément | Un prompt est séquentiel. Le harnais ordonnance et collecte les résultats de processus parallèles. |
|
||||
| 7 | **Persistance entre sessions** | Le système de mémoire et la hiérarchie des paramètres persistent entre conversations | Un prompt meurt à la fin de la session. |
|
||||
| 8 | **System prompt modulaire** | Le CLI charge 110+ fragments de system prompt conditionnellement selon les fonctionnalités activées | Un utilisateur ne peut écrire à la main ni substituer les fragments de prompt internes du CLI. |
|
||||
| 9 | **Préchargement de skill** | Le champ `skills:` injecte le contenu complet d'un skill dans le contexte de départ d'un sous-agent | L'utilisateur ne peut pré-remplir le contexte d'un autre agent — seul le loader du harnais le peut. |
|
||||
| 10 | **Classification de permissions** | Le mode de permissions `auto` utilise un classifieur en arrière-plan pour pré-approuver ou bloquer les appels d'outils | Un prompt ne peut s'ajouter à lui-même une couche de sécurité pré-exécution. |
|
||||
|
||||
Chaque ligne est une dimension où la « formulation forte » n'est catégoriquement pas un substitut.
|
||||
|
||||
---
|
||||
|
||||
## Les deux usages du mot « prompt »
|
||||
|
||||
La réduction joue sur une équivoque. Le mot *prompt* est utilisé pour signifier deux choses très différentes :
|
||||
|
||||
| Sens | Qui le contrôle | Taille |
|
||||
|---------|-----------------|------|
|
||||
| (a) Ce que l'utilisateur a tapé | L'utilisateur | ~6–60 tokens |
|
||||
| (b) Ce que le modèle voit à l'inférence | Le harnais | ~5 000–50 000+ tokens |
|
||||
|
||||
Dans un chatbot, (a) et (b) sont la même chose.
|
||||
Dans Claude Code, ils sont radicalement différents.
|
||||
|
||||
Le travail du harnais est précisément de rendre (b) bien plus riche que (a) :
|
||||
|
||||
```
|
||||
L'utilisateur tape : "write a recursive flatten function" ← (a) ~6 tokens
|
||||
|
||||
Ce que le modèle voit réellement à l'inférence : ← (b) ~15 000 tokens
|
||||
├── CLAUDE.md (conventions du projet)
|
||||
├── .claude/rules/*.md correspondants (chargés via le frontmatter paths:)
|
||||
├── Fragments de system prompt modulaires
|
||||
├── Définitions d'outils
|
||||
├── Contexte d'environnement (cwd, git status, plateforme)
|
||||
├── Historique des tours précédents
|
||||
├── Fichiers lus par le modèle via les outils Read/Grep
|
||||
└── La requête de 6 tokens de l'utilisateur
|
||||
```
|
||||
|
||||
**La qualité de la sortie est une fonction de (b), pas de (a).** Le harnais construit (b). Un « prompt solide à lui seul » ne peut reproduire (b) car l'essentiel n'est pas écrit par l'utilisateur.
|
||||
|
||||
---
|
||||
|
||||
## Même pour la qualité de sortie, le harnais fait un travail
|
||||
|
||||
Considère le même prompt — « write a recursive flatten function » — dans trois environnements :
|
||||
|
||||
| Environnement | Ce que le modèle voit | Résultat typique |
|
||||
|-------------|---------------------|----------------|
|
||||
| Chatbot, sans outils | La phrase | Récursion de manuel, style générique |
|
||||
| Claude Code, sans lecture | Phrase + CLAUDE.md | Correspond aux conventions déclarées du projet |
|
||||
| Claude Code, boucle agentique | Phrase + CLAUDE.md + lecture de fichiers adjacents + exécution de tests | Correspond aux patterns réels du codebase, passe les tests, gère les cas limites que le code existant gère |
|
||||
|
||||
Même modèle. Même prompt utilisateur. **Trois qualités de sortie différentes.** La différence est le harnais — spécifiquement, le contexte effectif qu'il assemble et la boucle d'itération qu'il permet.
|
||||
|
||||
Pour les tâches non triviales, la qualité de sortie est une fonction de :
|
||||
|
||||
```
|
||||
Qualité de sortie = f(contexte effectif, capacité du modèle, boucle d'itération)
|
||||
```
|
||||
|
||||
L'utilisateur contrôle une fraction du *contexte effectif* (son prompt tapé). Le harnais contrôle le reste — et la boucle d'itération entièrement.
|
||||
|
||||
---
|
||||
|
||||
## Ce que la réduction a juste (et ce qu'elle a faux)
|
||||
|
||||
| Affirmation | Verdict |
|
||||
|-------|---------|
|
||||
| « À l'inférence, le modèle ne voit que des tokens. » | ✅ Vrai |
|
||||
| « Skills, commandes et prompts de sous-agents contribuent tous des tokens à un certain contexte. » | ✅ Vrai |
|
||||
| « Pour une tâche atomique dans le vide, la qualité du prompt domine la qualité de sortie. » | ✅ Vrai |
|
||||
| « Donc un prompt solide est équivalent à utiliser les fonctionnalités. » | ❌ Faux |
|
||||
| « Donc le harnais n'importe pas pour la qualité de sortie. » | ❌ Faux sur les vraies tâches d'ingénierie |
|
||||
|
||||
Les trois premières affirmations sont des observations exactes. Le saut vers la quatrième est où le raisonnement échoue : il confond le modèle avec le système qui l'enveloppe, et confond les tâches atomiques avec le vrai travail d'ingénierie.
|
||||
|
||||
---
|
||||
|
||||
## Le bon modèle mental
|
||||
|
||||
> **Les prompts contrôlent ce qu'on demande au modèle de faire.**
|
||||
> **Le harnais contrôle ce que le système fait à des couches que le modèle ne peut atteindre** — avant l'arrivée des tokens, après la production des tokens, entre les sessions, entre les contextes et entre les processus.
|
||||
|
||||
Les fonctionnalités ne sont pas des prompts avec des étapes en plus. Ce sont des **primitives au niveau du harnais** — exécution déterministe, architecture de contexte et routage d'infrastructure — qui opèrent à des couches où le modèle n'a pas voix au chapitre.
|
||||
|
||||
Une analogie utile :
|
||||
|
||||
| Couche | Chatbot | Claude Code |
|
||||
|-------|---------|-------------|
|
||||
| Recette | Le message de l'utilisateur | Le message de l'utilisateur + contexte assemblé par le harnais |
|
||||
| Cuisine | Aucune — juste un élève | Outils, hooks, mémoire, workers parallèles, événements de cycle de vie |
|
||||
|
||||
Tu peux écrire la meilleure recette du monde. Sans cuisine, tu ne peux pas cuisiner à grande échelle.
|
||||
|
||||
---
|
||||
|
||||
## À retenir pour les praticiens
|
||||
|
||||
1. **Pour les questions atomiques, la qualité du prompt est ~tout.** Le harnais est sans importance. Utilise un chatbot si c'est tout ce dont tu as besoin.
|
||||
2. **Pour le vrai travail sur codebase, le harnais fait un gros travail silencieux.** Le prompt effectif à l'inférence est surtout construit par le harnais, pas tapé par l'utilisateur.
|
||||
3. **Utilise les fonctionnalités pour ce que les prompts ne peuvent catégoriquement pas faire :** déterminisme (hooks), isolation (sous-agents), chargement paresseux (règles avec `paths:`), persistance (mémoire), routage (`model:` par agent) et parallélisme.
|
||||
4. **Un prompt solide est nécessaire mais pas suffisant.** Les fonctionnalités te donnent déterminisme, isolation et composition que les prompts ne peuvent offrir. Les deux sont complémentaires, pas substituables.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [Agents vs Commandes vs Skills](claude-agent-command-skill.md) — montre l'isolation de contexte, la surcharge de modèle et les restrictions d'outils par fonctionnalité
|
||||
- [Claude Agent SDK vs system prompts du CLI](claude-agent-sdk-vs-cli-system-prompts.md) — documente les 110+ fragments de system prompt modulaires
|
||||
- [Mémoire d'agent Claude](claude-agent-memory.md) — persistance entre sessions via les portées `memory:`
|
||||
- [Bonnes pratiques — Mémoire de Claude](../best-practice/claude-memory.md) — fichiers `CLAUDE.md` descendants en chargement paresseux
|
||||
- [Bonnes pratiques — Sous-agents](../best-practice/claude-subagents.md) — référence de frontmatter pour les capacités imposées par le harnais
|
||||
- [Bonnes pratiques — Paramètres](../best-practice/claude-settings.md) — évaluation des règles de permission et classifieur du mode `auto`
|
||||
- [Workflow d'orchestration](../orchestration-workflow/orchestration-workflow.md) — démonstration concrète que la réduction échoue
|
||||
Reference in New Issue
Block a user