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 SDK Claude Agent fournit trois façons de personnaliser les invites système : utiliser des styles de sortie (configurations persistantes basées sur des fichiers), ajouter à l'invite de Claude Code, ou utiliser une invite entièrement personnalisée.

Comprendre les invites système

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

L'invite système de Claude Code inclut :

• Instructions d'utilisation des outils et outils disponibles
• Directives de style et de formatage du code
• Paramètres de ton et de verbosité des réponses
• Instructions de sécurité et de sûreté
• Contexte sur le répertoire de travail actuel et 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 SDK Agent 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

Emplacement et découverte :

• Niveau projet : CLAUDE.md ou .claude/CLAUDE.md dans votre répertoire de travail
• Niveau utilisateur : ~/.claude/CLAUDE.md pour des instructions globales à travers 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 utilisateur (~/.claude/CLAUDE.md)

Le preset d'invite système 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 du markdown simple et peuvent contenir :

• Directives et standards de codage
• Contexte spécifique au projet
• Commandes ou flux de travail courants
• Conventions d'API
• Exigences de test

Exemple CLAUDE.md

# Directives du Projet

## Style de Code

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

## Tests

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

## Commandes

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

Utiliser CLAUDE.md avec le SDK

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: "Ajouter un nouveau composant React pour les profils utilisateur",
  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

Quand utiliser CLAUDE.md

Idéal pour :

• Contexte partagé en équipe - Directives que tout le monde devrait suivre
• Conventions de projet - Standards 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 devrait persister à travers toutes les sessions
• Instructions versionnées - Commiter dans git pour que l'équipe reste synchronisée

Caractéristiques clés :

• ✅ Persistant à travers toutes les sessions dans un projet
• ✅ Partagé avec l'équipe via git
• ✅ Découverte automatique (aucun changement 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 sauvegardées qui modifient l'invite système de Claude. Ils sont stockés comme fichiers markdown et peuvent être réutilisés à travers les sessions et projets.

Créer un style de sortie

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

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // Niveau utilisateur : ~/.claude/output-styles
  // Niveau 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 de révision de code
await createOutputStyle(
  "Code Reviewer",
  "Assistant de révision de code approfondie",
  `Vous êtes un expert en révision de code.

Pour chaque soumission de code :
1. Vérifier les bugs et problèmes de sécurité
2. Évaluer les performances
3. Suggérer des améliorations
4. Noter la qualité du code (1-10)`
);

Utiliser les styles de sortie

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

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

Note 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 append

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.

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

const messages = [];

for await (const message of query({
  prompt: "Aidez-moi à écrire une fonction Python pour calculer les nombres de fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Toujours inclure des docstrings détaillées et des annotations de type dans le code Python.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

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

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

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

const customPrompt = `Vous êtes un spécialiste du codage Python.
Suivez ces directives :
- Écrire du code propre et bien documenté
- Utiliser des annotations de type pour toutes les fonctions
- Inclure des docstrings complètes
- Préférer les modèles de programmation fonctionnelle quand approprié
- Toujours expliquer vos choix de code`;

const messages = [];

for await (const message of query({
  prompt: "Créer un pipeline de traitement de données",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

Comparaison des quatre approches

Note : "Avec append" 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 :

• Standards et conventions de codage spécifiques au projet
• Documenter la structure et l'architecture du projet
• Lister les commandes courantes (build, test, déploiement)
• Contexte partagé en équipe qui devrait être versionné
• Instructions qui s'appliquent à toute utilisation du SDK dans un projet

Exemples :

• "Tous les endpoints d'API devraient utiliser les modèles async/await"
• "Exécuter npm run lint:fix avant de commiter"
• "Les migrations de base de données sont 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). Le preset d'invite système claude_code ne charge PAS automatiquement CLAUDE.md sans ce paramètre.

Quand utiliser les styles de sortie

Idéal pour :

• Changements de comportement persistants à travers les sessions
• Configurations partagées en équipe
• Assistants spécialisés (réviseur de code, data scientist, DevOps)
• Modifications d'invite complexes qui nécessitent un versioning

Exemples :

• Créer un assistant dédié à l'optimisation SQL
• Construire un réviseur de code axé sur la sécurité
• Développer un assistant d'enseignement avec une pédagogie spécifique

Quand utiliser systemPrompt avec append

Idéal pour :

• Ajouter des standards ou préférences de codage spécifiques
• Personnaliser le formatage de 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 d'outils

Quand utiliser systemPrompt personnalisé

Idéal pour :

• Contrôle complet sur le comportement de Claude
• Tâches spécialisées à session unique
• Tester de nouvelles stratégies d'invite
• 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

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: "Réviser ce module d'authentification",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Pour cette révision, priorisez :
        - Conformité OAuth 2.0
        - Sécurité du stockage des tokens
        - Gestion des sessions
      `,
    },
  },
})) {
  messages.push(message);
}

Voir aussi

• Styles de sortie - Documentation complète des styles de sortie
• Guide du SDK TypeScript - Guide complet d'utilisation du SDK
• Référence du SDK TypeScript - Documentation complète de l'API
• Guide de configuration - Options de configuration générales