Modification des invites système

Les invites système définissent le comportement, les capacités et le style de réponse de Claude. Le Claude Agent SDK fournit trois façons de personnaliser les invites système : en utilisant des styles de sortie (configurations persistantes basées sur des fichiers), en ajoutant à l'invite de Claude Code, ou en utilisant une invite entièrement personnalisée.

Comprendre les invites système

Une invite système est l'ensemble initial d'instructions qui façonne le comportement de Claude tout au long d'une conversation.

Comportement par défaut : Le Agent SDK utilise une invite système minimale par défaut. Elle contient uniquement les instructions essentielles des outils mais omet les directives de codage de Claude Code, le style de réponse et le contexte du projet. Pour inclure l'invite système complète de Claude Code, spécifiez systemPrompt: { preset: "claude_code" } en TypeScript ou system_prompt={"type": "preset", "preset": "claude_code"} en Python.

L'invite système de Claude Code inclut :

Les instructions d'utilisation des outils et les outils disponibles
Les directives de style et de formatage du code
Les paramètres de ton et de verbosité des réponses
Les instructions de sécurité et de sûreté
Le contexte du répertoire de travail actuel et de l'environnement

Méthodes de modification

Méthode 1 : Fichiers CLAUDE.md (instructions au niveau du projet)

Les fichiers CLAUDE.md fournissent un contexte et des instructions spécifiques au projet qui sont automatiquement lus par le Agent SDK lorsqu'il s'exécute dans un répertoire. Ils servent de « mémoire » persistante pour votre projet.

Comment CLAUDE.md fonctionne avec le SDK

Localisation et découverte :

Au niveau du projet : CLAUDE.md ou .claude/CLAUDE.md dans votre répertoire de travail
Au niveau de l'utilisateur : ~/.claude/CLAUDE.md pour les instructions globales sur tous les projets

IMPORTANT : Le SDK ne lit les fichiers CLAUDE.md que lorsque vous configurez explicitement settingSources (TypeScript) ou setting_sources (Python) :

Incluez 'project' pour charger CLAUDE.md au niveau du projet
Incluez 'user' pour charger CLAUDE.md au niveau de l'utilisateur (~/.claude/CLAUDE.md)

L'invite système preset claude_code ne charge PAS automatiquement CLAUDE.md - vous devez également spécifier les sources de paramètres.

Format du contenu : Les fichiers CLAUDE.md utilisent le markdown simple et peuvent contenir :

Les directives de codage et les normes
Le contexte spécifique au projet
Les commandes ou flux de travail courants
Les conventions d'API
Les exigences de test

Exemple CLAUDE.md

# Directives du projet

## Style de code

- Utiliser le mode strict TypeScript
- Préférer les composants fonctionnels dans React
- Toujours inclure des commentaires JSDoc pour les API publiques

## Test

- Exécuter `npm test` avant de valider
- Maintenir une couverture de code > 80%
- Utiliser jest pour les tests unitaires, playwright pour E2E

## Commandes

- Build : `npm run build`
- Serveur de développement : `npm run dev`
- Vérification de type : `npm run typecheck`

Utiliser CLAUDE.md avec le SDK

Quand utiliser CLAUDE.md

Idéal pour :

Contexte partagé en équipe - Directives que tout le monde doit suivre
Conventions du projet - Normes de codage, structure de fichiers, modèles de nommage
Commandes courantes - Commandes de build, test, déploiement spécifiques à votre projet
Mémoire à long terme - Contexte qui doit persister dans toutes les sessions
Instructions contrôlées par version - Valider sur git pour que l'équipe reste synchronisée

Caractéristiques clés :

✅ Persistant dans toutes les sessions d'un projet
✅ Partagé avec l'équipe via git
✅ Découverte automatique (aucune modification de code nécessaire)
⚠️ Nécessite le chargement des paramètres via settingSources

Méthode 2 : Styles de sortie (configurations persistantes)

Les styles de sortie sont des configurations enregistrées qui modifient l'invite système de Claude. Ils sont stockés sous forme de fichiers markdown et peuvent être réutilisés dans les sessions et les projets.

Créer un style de sortie

Utiliser les styles de sortie

Une fois créés, activez les styles de sortie via :

CLI : /output-style [style-name]
Paramètres : .claude/settings.local.json
Créer nouveau : /output-style:new [description]

Remarque pour les utilisateurs du SDK : Les styles de sortie sont chargés lorsque vous incluez settingSources: ['user'] ou settingSources: ['project'] (TypeScript) / setting_sources=["user"] ou setting_sources=["project"] (Python) dans vos options.

Méthode 3 : Utiliser `systemPrompt` avec ajout

Vous pouvez utiliser le preset Claude Code avec une propriété append pour ajouter vos instructions personnalisées tout en préservant toutes les fonctionnalités intégrées.

Méthode 4 : Invites système personnalisées

Vous pouvez fournir une chaîne personnalisée comme systemPrompt pour remplacer entièrement la valeur par défaut par vos propres instructions.

Comparaison des quatre approches

Fonctionnalité	CLAUDE.md	Styles de sortie	`systemPrompt` avec ajout	`systemPrompt` personnalisé
Persistance	Fichier par projet	Enregistré en tant que fichiers	Session uniquement	Session uniquement
Réutilisabilité	Par projet	Entre les projets	Duplication de code	Duplication de code
Gestion	Sur le système de fichiers	CLI + fichiers	Dans le code	Dans le code
Outils par défaut	Préservés	Préservés	Préservés	Perdus (sauf s'ils sont inclus)

Remarque : « Avec ajout » signifie utiliser systemPrompt: { type: "preset", preset: "claude_code", append: "..." } en TypeScript ou system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} en Python.

Cas d'usage et meilleures pratiques

Quand utiliser CLAUDE.md

Idéal pour :

Les normes et conventions de codage spécifiques au projet
Documenter la structure et l'architecture du projet
Lister les commandes courantes (build, test, déploiement)
Le contexte partagé en équipe qui doit être contrôlé par version
Les instructions qui s'appliquent à toute utilisation du SDK dans un projet

Exemples :

« Tous les points de terminaison API doivent utiliser les modèles async/await »
« Exécuter npm run lint:fix avant de valider »
« Les migrations de base de données se trouvent dans le répertoire migrations/ »

Important : Pour charger les fichiers CLAUDE.md, vous devez explicitement définir settingSources: ['project'] (TypeScript) ou setting_sources=["project"] (Python). L'invite système preset claude_code ne charge PAS automatiquement CLAUDE.md sans ce paramètre.

Quand utiliser les styles de sortie

Idéal pour :

Les modifications de comportement persistantes entre les sessions
Les configurations partagées en équipe
Les assistants spécialisés (examinateur de code, data scientist, DevOps)
Les modifications d'invite complexes qui nécessitent une gestion de version

Exemples :

Créer un assistant dédié d'optimisation SQL
Construire un examinateur de code axé sur la sécurité
Développer un assistant pédagogique avec une pédagogie spécifique

Quand utiliser `systemPrompt` avec ajout

Idéal pour :

Ajouter des normes de codage ou des préférences spécifiques
Personnaliser le formatage de la sortie
Ajouter des connaissances spécifiques au domaine
Modifier la verbosité des réponses
Améliorer le comportement par défaut de Claude Code sans perdre les instructions des outils

Quand utiliser `systemPrompt` personnalisé

Idéal pour :

Contrôle complet du comportement de Claude
Tâches spécialisées d'une seule session
Tester de nouvelles stratégies d'invite
Les situations où les outils par défaut ne sont pas nécessaires
Construire des agents spécialisés avec un comportement unique

Combiner les approches

Vous pouvez combiner ces méthodes pour une flexibilité maximale :

Exemple : Style de sortie avec ajouts spécifiques à la session

Voir aussi

Output styles - Documentation complète des styles de sortie
Guide du SDK TypeScript - Guide complet d'utilisation du SDK
Guide de configuration - Options de configuration générales

import { query } from "@anthropic-ai/claude-agent-sdk";

// IMPORTANT : Vous devez spécifier settingSources pour charger CLAUDE.md
// Le preset claude_code seul ne charge PAS les fichiers CLAUDE.md
const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Utiliser l'invite système de Claude Code
    },
    settingSources: ["project"], // Requis pour charger CLAUDE.md du projet
  },
})) {
  messages.push(message);
}

// Maintenant Claude a accès à vos directives de projet depuis CLAUDE.md

import { writeFile, mkdir } from "fs/promises";
import { join } from "path";
import { homedir } from "os";

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // Au niveau de l'utilisateur : ~/.claude/output-styles
  // Au niveau du projet : .claude/output-styles
  const outputStylesDir = join(homedir(), ".claude", "output-styles");

  await mkdir(outputStylesDir, { recursive: true });

  const content = `---
name: ${name}
description: ${description}
---

${prompt}`;

  const filePath = join(
    outputStylesDir,
    `${name.toLowerCase().replace(/\s+/g, "-")}.md`
  );
  await writeFile(filePath, content, "utf-8");
}

// Exemple : Créer un spécialiste en révision de code
await createOutputStyle(
  "Code Reviewer",
  "Thorough code review assistant",
  `You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)`
);

import { query } from "@anthropic-ai/claude-agent-sdk";

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Always include detailed docstrings and type hints in Python code.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";

// En supposant que le style de sortie « Code Reviewer » est actif (via /output-style)
// Ajouter des domaines de focus spécifiques à la session
const messages = [];

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `,
    },
  },
})) {
  messages.push(message);
}

Comprendre les invites système

Méthodes de modification

Méthode 1 : Fichiers CLAUDE.md (instructions au niveau du projet)

Comment CLAUDE.md fonctionne avec le SDK

Exemple CLAUDE.md

Utiliser CLAUDE.md avec le SDK

Quand utiliser CLAUDE.md

Méthode 2 : Styles de sortie (configurations persistantes)

Créer un style de sortie

Utiliser les styles de sortie

Méthode 3 : Utiliser systemPrompt avec ajout

Méthode 4 : Invites système personnalisées

Comparaison des quatre approches

Cas d'usage et meilleures pratiques

Quand utiliser CLAUDE.md

Quand utiliser les styles de sortie

Quand utiliser systemPrompt avec ajout

Quand utiliser systemPrompt personnalisé

Combiner les approches

Exemple : Style de sortie avec ajouts spécifiques à la session

Voir aussi

Méthode 3 : Utiliser `systemPrompt` avec ajout

Quand utiliser `systemPrompt` avec ajout

Quand utiliser `systemPrompt` personnalisé