Systemanfragen ändern

Systemanfragen definieren Claudes Verhalten, Fähigkeiten und Antwortstil. Das Claude Agent SDK bietet drei Möglichkeiten, Systemanfragen anzupassen: Verwendung von Ausgabestilen (persistente, dateibasierte Konfigurationen), Anhängen an Claudes Code-Anfrage oder Verwendung einer vollständig benutzerdefinierten Anfrage.

Systemanfragen verstehen

Eine Systemanfrage ist der anfängliche Anweisungssatz, der definiert, wie sich Claude während eines Gesprächs verhält.

Claudes Code-Systemanfrage umfasst:

• Tool-Nutzungsanweisungen und verfügbare Tools
• Code-Stil- und Formatierungsrichtlinien
• Antworttone und Ausführlichkeitseinstellungen
• Sicherheits- und Sicherheitsanweisungen
• Kontext zum aktuellen Arbeitsverzeichnis und zur Umgebung

Änderungsmethoden

Methode 1: CLAUDE.md-Dateien (Anweisungen auf Projektebene)

CLAUDE.md-Dateien bieten projektspezifischen Kontext und Anweisungen, die vom Agent SDK automatisch gelesen werden, wenn es in einem Verzeichnis ausgeführt wird. Sie dienen als persistentes „Gedächtnis" für Ihr Projekt.

Wie CLAUDE.md mit dem SDK funktioniert

Speicherort und Erkennung:

• Projektebene: CLAUDE.md oder .claude/CLAUDE.md in Ihrem Arbeitsverzeichnis
• Benutzerebene: ~/.claude/CLAUDE.md für globale Anweisungen über alle Projekte hinweg

WICHTIG: Das SDK liest CLAUDE.md-Dateien nur, wenn Sie settingSources (TypeScript) oder setting_sources (Python) explizit konfigurieren:

• Fügen Sie 'project' ein, um CLAUDE.md auf Projektebene zu laden
• Fügen Sie 'user' ein, um CLAUDE.md auf Benutzerebene zu laden (~/.claude/CLAUDE.md)

Die claude_code-Systemanfrage-Voreinstellung lädt CLAUDE.md NICHT automatisch - Sie müssen auch Einstellungsquellen angeben.

Inhaltsformat: CLAUDE.md-Dateien verwenden einfaches Markdown und können enthalten:

• Codierungsrichtlinien und Standards
• Projektspezifischen Kontext
• Häufige Befehle oder Workflows
• API-Konventionen
• Testanforderungen

Beispiel CLAUDE.md

# Projektrichtlinien

## Code-Stil

- TypeScript-Strict-Modus verwenden
- Funktionale Komponenten in React bevorzugen
- Immer JSDoc-Kommentare für öffentliche APIs einschließen

## Testen

- `npm test` vor dem Commit ausführen
- Mindestens 80% Code-Abdeckung beibehalten
- Jest für Unit-Tests, Playwright für E2E verwenden

## Befehle

- Build: `npm run build`
- Dev-Server: `npm run dev`
- Typprüfung: `npm run typecheck`

CLAUDE.md mit dem SDK verwenden

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

// WICHTIG: Sie müssen settingSources angeben, um CLAUDE.md zu laden
// Die claude_code-Voreinstellung allein lädt CLAUDE.md-Dateien NICHT
const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Claudes Code-Systemanfrage verwenden
    },
    settingSources: ["project"], // Erforderlich, um CLAUDE.md aus dem Projekt zu laden
  },
})) {
  messages.push(message);
}

// Jetzt hat Claude Zugriff auf Ihre Projektrichtlinien aus CLAUDE.md

Wann CLAUDE.md verwenden

Am besten für:

• Team-gemeinsamer Kontext - Richtlinien, die jeder befolgen sollte
• Projektkonventionen - Codierungsstandards, Dateistruktur, Benennungsmuster
• Häufige Befehle - Build-, Test-, Deploy-Befehle spezifisch für Ihr Projekt
• Langzeitgedächtnis - Kontext, der über alle Sitzungen hinweg bestehen bleiben sollte
• Versionskontrollierte Anweisungen - Commit zu Git, damit das Team synchron bleibt

Wichtige Merkmale:

• ✅ Persistent über alle Sitzungen in einem Projekt
• ✅ Mit Team über Git geteilt
• ✅ Automatische Erkennung (keine Codeänderungen erforderlich)
• ⚠️ Erfordert das Laden von Einstellungen über settingSources

Methode 2: Ausgabestile (persistente Konfigurationen)

Ausgabestile sind gespeicherte Konfigurationen, die Claudes Systemanfrage ändern. Sie werden als Markdown-Dateien gespeichert und können über Sitzungen und Projekte hinweg wiederverwendet werden.

Einen Ausgabestil erstellen

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

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // Benutzerebene: ~/.claude/output-styles
  // Projektebene: .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");
}

// Beispiel: Erstellen Sie einen Code-Review-Spezialisten
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)`
);

Ausgabestile verwenden

Aktivieren Sie Ausgabestile nach der Erstellung über:

• CLI: /output-style [style-name]
• Einstellungen: .claude/settings.local.json
• Neu erstellen: /output-style:new [description]

Hinweis für SDK-Benutzer: Ausgabestile werden geladen, wenn Sie settingSources: ['user'] oder settingSources: ['project'] (TypeScript) / setting_sources=["user"] oder setting_sources=["project"] (Python) in Ihren Optionen einschließen.

Methode 3: Verwendung von systemPrompt mit Anhang

Sie können die Claude Code-Voreinstellung mit einer append-Eigenschaft verwenden, um Ihre benutzerdefinierten Anweisungen hinzuzufügen und gleichzeitig alle integrierten Funktionen beizubehalten.

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

Methode 4: Benutzerdefinierte Systemanfragen

Sie können eine benutzerdefinierte Zeichenkette als systemPrompt bereitstellen, um die Standardeinstellung vollständig durch Ihre eigenen Anweisungen zu ersetzen.

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

Vergleich aller vier Ansätze

Hinweis: „Mit Anhang" bedeutet die Verwendung von systemPrompt: { type: "preset", preset: "claude_code", append: "..." } in TypeScript oder system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} in Python.

Anwendungsfälle und Best Practices

Wann CLAUDE.md verwenden

Am besten für:

• Projektspezifische Codierungsstandards und Konventionen
• Dokumentation der Projektstruktur und Architektur
• Auflistung häufiger Befehle (Build, Test, Deploy)
• Team-gemeinsamer Kontext, der versionskontrolliert sein sollte
• Anweisungen, die für alle SDK-Nutzungen in einem Projekt gelten

Beispiele:

• „Alle API-Endpunkte sollten async/await-Muster verwenden"
• „npm run lint:fix vor dem Commit ausführen"
• „Datenbankmigrationen befinden sich im Verzeichnis migrations/"

Wichtig: Um CLAUDE.md-Dateien zu laden, müssen Sie explizit settingSources: ['project'] (TypeScript) oder setting_sources=["project"] (Python) festlegen. Die claude_code-Systemanfrage-Voreinstellung lädt CLAUDE.md ohne diese Einstellung NICHT automatisch.

Wann Ausgabestile verwenden

Am besten für:

• Persistente Verhaltensänderungen über Sitzungen hinweg
• Team-gemeinsame Konfigurationen
• Spezialisierte Assistenten (Code-Reviewer, Datenwissenschaftler, DevOps)
• Komplexe Prompt-Änderungen, die Versionierung benötigen

Beispiele:

• Erstellen eines dedizierten SQL-Optimierungsassistenten
• Aufbau eines sicherheitsorientierten Code-Reviewers
• Entwicklung eines Lernassistenten mit spezifischer Pädagogik

Wann systemPrompt mit Anhang verwenden

Am besten für:

• Hinzufügen spezifischer Codierungsstandards oder Vorlieben
• Anpassung der Ausgabeformatierung
• Hinzufügen domänenspezifischen Wissens
• Änderung der Antwortausführlichkeit
• Verbesserung des Standardverhaltens von Claude Code ohne Verlust von Tool-Anweisungen

Wann benutzerdefinierte systemPrompt verwenden

Am besten für:

• Vollständige Kontrolle über Claudes Verhalten
• Spezialisierte Single-Session-Aufgaben
• Testen neuer Prompt-Strategien
• Situationen, in denen Standard-Tools nicht benötigt werden
• Aufbau spezialisierter Agenten mit einzigartigem Verhalten

Ansätze kombinieren

Sie können diese Methoden kombinieren, um maximale Flexibilität zu erreichen:

Beispiel: Ausgabestil mit sitzungsspezifischen Ergänzungen

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

// Angenommen, der Ausgabestil „Code Reviewer" ist aktiv (über /output-style)
// Sitzungsspezifische Fokusbereich hinzufügen
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);
}

Siehe auch

• Ausgabestile - Vollständige Dokumentation zu Ausgabestilen
• TypeScript SDK-Anleitung - Vollständige SDK-Nutzungsanleitung
• Konfigurationsanleitung - Allgemeine Konfigurationsoptionen