341 lines
14 KiB
Markdown
341 lines
14 KiB
Markdown
# 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.*
|