Modification des invites système

• Fonctionnement des invites système, avec un tableau de décision pour choisir entre le préréglage, le préréglage avec append, et une invite personnalisée
• Personnaliser le comportement de l’agent avec des fichiers CLAUDE.md, des styles de sortie, append, ou une chaîne personnalisée
• Comparer les quatre approches par persistance, portée, et ce qu’elles préservent
• Combiner les approches pour superposer les méthodes de personnalisation

​

Fonctionnement des invites système

• Défaut minimal : lorsque vous ne définissez pas systemPrompt en TypeScript ou system_prompt en Python, le SDK utilise une invite minimale qui couvre l’appel d’outils mais omet les directives de codage de Claude Code, le style de réponse et le contexte du projet. Cela diffère de claude -p, qui utilise l’invite complète de Claude Code par défaut. Si vous migrez depuis la CLI et souhaitez un comportement correspondant, définissez le préréglage claude_code.
• Préréglage claude_code : l’invite système complète que la CLI Claude Code utilise, avec les instructions d’utilisation des outils, les directives de style et de formatage du code, les règles de ton et de verbosité des réponses, les instructions de sécurité et de sûreté, et le contexte du répertoire de travail et de l’environnement. Définissez systemPrompt: { type: "preset", preset: "claude_code" } en TypeScript ou system_prompt={"type": "preset", "preset": "claude_code"} en Python, éventuellement avec append pour ajouter vos propres instructions à la fin.
• Chaîne personnalisée : une invite que vous écrivez vous-même. Le SDK envoie uniquement ce que vous fournissez.

​

Décider d’un point de départ

• Surface différente : la sortie n’est pas lue dans un terminal par la personne qui l’a déclenchée. Les interfaces de chat, les consommateurs de sortie structurée et l’automatisation non-codage ont chacun besoin d’une invite qui correspond à la façon dont leur sortie est rendue et examinée. L’automatisation de codage sans surveillance, comme un travail CI qui corrige les erreurs de lint ou examine les diffs, s’adapte toujours au préréglage car le travail lui-même est ce pour lequel le préréglage est écrit.
• Identité différente : l’agent ne devrait pas se présenter comme Claude Code. Un bot d’assistance, un assistant d’analyse de données ou tout agent spécifique à un domaine a besoin de son propre nom, portée et persona.
• Modèle de permission différent : l’agent s’exécute de manière autonome sans qu’un humain n’approuve chaque étape, ou opère sur un ensemble étroit de ressources. L’invite de Claude Code suppose qu’un humain est dans la boucle avec accès à un ensemble complet d’outils.
• Tâches non-codage : la plupart de l’invite de Claude Code est une guidance de codage. Pour les agents de recherche, de contenu ou d’opérations, cette guidance entre en concurrence avec les instructions dont vous avez réellement besoin.

​

Personnaliser le comportement de l’agent

​

Fichiers CLAUDE.md pour les instructions au niveau du projet

​

Charger CLAUDE.md avec le SDK

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

const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Use Claude Code's system prompt
    },
    settingSources: ["project"] // Loads CLAUDE.md from project
  }
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []

async for message in query(
    prompt="Add a new React component for user profiles",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",  # Use Claude Code's system prompt
        },
        setting_sources=["project"],  # Loads CLAUDE.md from project
    ),
):
    messages.append(message)

# Now Claude has access to your project guidelines from CLAUDE.md

​

Styles de sortie pour les configurations persistantes

​

Créer un style de sortie

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

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)

​

Activer un style de sortie

• CLI : exécutez /config et sélectionnez un style de sortie
• Paramètres : définissez outputStyle dans .claude/settings.local.json
• SDK TypeScript : définissez outputStyle dans l’objet settings en ligne passé à query(), ou pointez settings vers un fichier de paramètres qui le définit. outputStyle n’est pas un champ Options de niveau supérieur :
  const options = { settings: { outputStyle: "Explanatory" } };
  

​

Ajouter au préréglage claude_code

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);
  }
}

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []

async for message in query(
    prompt="Help me write a Python function to calculate fibonacci numbers",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
            "append": "Always include detailed docstrings and type hints in Python code.",
        }
    ),
):
    messages.append(message)
    if isinstance(message, AssistantMessage):
        print(message.content)

​

Améliorer la mise en cache des invites entre les utilisateurs et les machines

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

for await (const message of query({
  prompt: "Triage the open issues in this repo",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
      excludeDynamicSections: true
    }
  }
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Triage the open issues in this repo",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
            "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
            "exclude_dynamic_sections": True,
        },
    ),
):
    ...

​

Invites système personnalisées

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);
  }
}

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

custom_prompt = """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"""

messages = []

async for message in query(
    prompt="Create a data processing pipeline",
    options=ClaudeAgentOptions(system_prompt=custom_prompt),
):
    messages.append(message)
    if isinstance(message, AssistantMessage):
        print(message.content)

​

Comparaison des quatre approches

​

Cas d’utilisation et meilleures pratiques

​

Quand utiliser CLAUDE.md

​

Quand utiliser les styles de sortie

• Les modifications de comportement persistantes dans les sessions
• Les configurations partagées par l’équipe
• Les assistants spécialisés comme un examinateur de code, un data scientist ou un assistant DevOps
• Les modifications d’invite complexes qui nécessitent une gestion de version

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

• Ajouter des normes ou des préférences de codage 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é

• Contrôle complet du comportement de Claude
• Les 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

​

Combiner un style de sortie avec des ajouts spécifiques à la session

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
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);
}

from claude_agent_sdk import query, ClaudeAgentOptions

# Assuming "Code Reviewer" output style is active (via /config or settings)
# Add session-specific focus areas
messages = []

async for message in query(
    prompt="Review this authentication module",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
            "append": """
            For this review, prioritize:
            - OAuth 2.0 compliance
            - Token storage security
            - Session management
            """,
        }
    ),
):
    messages.append(message)

​

Voir aussi

• Styles de sortie : créer, gérer et partager les styles de sortie pour la CLI, y compris le format de fichier et les emplacements de stockage
• Comment Claude se souvient de votre projet : ce qu’il faut mettre dans CLAUDE.md, où le placer et comment rédiger des instructions de projet efficaces
• Référence du SDK TypeScript : le type Options complet, y compris systemPrompt, settingSources et settings
• Référence du SDK Python : le type ClaudeAgentOptions complet, y compris system_prompt et setting_sources
• Paramètres : la référence settings.json, y compris où les styles de sortie et autres configurations sont stockés