Изменение системных подсказок

Системные подсказки определяют поведение Claude, его возможности и стиль ответов. Claude Agent SDK предоставляет три способа настройки системных подсказок: использование стилей вывода (постоянные конфигурации на основе файлов), добавление к подсказке Claude Code или использование полностью пользовательской подсказки.

Понимание системных подсказок

Системная подсказка — это начальный набор инструкций, который определяет поведение Claude на протяжении всего разговора.

Поведение по умолчанию: Agent SDK использует минимальную системную подсказку по умолчанию. Она содержит только необходимые инструкции инструментов, но опускает рекомендации по кодированию Claude Code, стиль ответов и контекст проекта. Чтобы включить полную системную подсказку Claude Code, укажите systemPrompt: { preset: "claude_code" } в TypeScript или system_prompt={"type": "preset", "preset": "claude_code"} в Python.

Системная подсказка Claude Code включает:

Инструкции по использованию инструментов и доступные инструменты
Рекомендации по стилю кода и форматированию
Параметры тона и подробности ответов
Инструкции по безопасности и защите
Контекст о текущем рабочем каталоге и окружении

Методы изменения

Метод 1: Файлы CLAUDE.md (инструкции на уровне проекта)

Файлы CLAUDE.md предоставляют контекст и инструкции, специфичные для проекта, которые автоматически читаются Agent SDK при запуске в каталоге. Они служат постоянной "памятью" для вашего проекта.

Как CLAUDE.md работает с SDK

Расположение и обнаружение:

На уровне проекта: CLAUDE.md или .claude/CLAUDE.md в вашем рабочем каталоге
На уровне пользователя: ~/.claude/CLAUDE.md для глобальных инструкций во всех проектах

ВАЖНО: SDK читает файлы CLAUDE.md только когда вы явно настраиваете settingSources (TypeScript) или setting_sources (Python):

Включите 'project' для загрузки CLAUDE.md на уровне проекта
Включите 'user' для загрузки CLAUDE.md на уровне пользователя (~/.claude/CLAUDE.md)

Предустановка системной подсказки claude_code НЕ загружает CLAUDE.md автоматически — вы также должны указать источники параметров.

Формат содержимого: Файлы CLAUDE.md используют простой markdown и могут содержать:

Рекомендации по кодированию и стандарты
Контекст, специфичный для проекта
Общие команды или рабочие процессы
Соглашения API
Требования к тестированию

Пример CLAUDE.md

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

Использование CLAUDE.md с SDK

Когда использовать CLAUDE.md

Лучше всего для:

Контекст, общий для команды — рекомендации, которые должны соблюдать все
Соглашения проекта — стандарты кодирования, структура файлов, шаблоны именования
Общие команды — команды сборки, тестирования, развертывания, специфичные для вашего проекта
Долгосрочная память — контекст, который должен сохраняться во всех сеансах
Инструкции, контролируемые версией — фиксация в git, чтобы команда оставалась синхронизированной

Ключевые характеристики:

✅ Постоянство во всех сеансах в проекте
✅ Совместное использование с командой через git
✅ Автоматическое обнаружение (изменения кода не требуются)
⚠️ Требует загрузки параметров через settingSources

Метод 2: Стили вывода (постоянные конфигурации)

Стили вывода — это сохраненные конфигурации, которые изменяют системную подсказку Claude. Они хранятся как файлы markdown и могут быть переиспользованы в разных сеансах и проектах.

Создание стиля вывода

Использование стилей вывода

После создания активируйте стили вывода через:

CLI: /output-style [style-name]
Параметры: .claude/settings.local.json
Создать новый: /output-style:new [description]

Примечание для пользователей SDK: Стили вывода загружаются, когда вы включаете settingSources: ['user'] или settingSources: ['project'] (TypeScript) / setting_sources=["user"] или setting_sources=["project"] (Python) в ваши параметры.

Метод 3: Использование `systemPrompt` с добавлением

Вы можете использовать предустановку Claude Code со свойством append для добавления ваших пользовательских инструкций при сохранении всей встроенной функциональности.

Метод 4: Пользовательские системные подсказки

Вы можете предоставить пользовательскую строку как systemPrompt для полной замены значения по умолчанию на ваши собственные инструкции.

Сравнение всех четырех подходов

Функция	CLAUDE.md	Стили вывода	`systemPrompt` с добавлением	Пользовательский `systemPrompt`
Постоянство	Файл для каждого проекта	Сохраняется как файлы	Только сеанс	Только сеанс
Переиспользуемость	Для каждого проекта	Между проектами	Дублирование кода	Дублирование кода
Управление	На файловой системе	CLI + файлы	В коде	В коде
Инструменты по умолчанию	Сохранены	Сохранены	Сохранены	Потеряны (если не включены)

Примечание: "С добавлением" означает использование systemPrompt: { type: "preset", preset: "claude_code", append: "..." } в TypeScript или system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} в Python.

Варианты использования и лучшие практики

Когда использовать CLAUDE.md

Лучше всего для:

Стандартов и соглашений кодирования, специфичных для проекта
Документирования структуры и архитектуры проекта
Перечисления общих команд (сборка, тестирование, развертывание)
Контекста, общего для команды, который должен быть под контролем версий
Инструкций, которые применяются ко всему использованию SDK в проекте

Примеры:

"Все конечные точки API должны использовать асинхронные/ожидающие шаблоны"
"Запустите npm run lint:fix перед фиксацией"
"Миграции базы данных находятся в каталоге migrations/"

Важно: Чтобы загрузить файлы CLAUDE.md, вы должны явно установить settingSources: ['project'] (TypeScript) или setting_sources=["project"] (Python). Предустановка системной подсказки claude_code НЕ загружает CLAUDE.md автоматически без этого параметра.

Когда использовать стили вывода

Лучше всего для:

Постоянных изменений поведения между сеансами
Конфигураций, общих для команды
Специализированных помощников (рецензент кода, специалист по данным, DevOps)
Сложных изменений подсказок, которые требуют версионирования

Примеры:

Создание выделенного помощника по оптимизации SQL
Создание рецензента кода, ориентированного на безопасность
Разработка помощника по обучению с определенной педагогикой

Когда использовать `systemPrompt` с добавлением

Лучше всего для:

Добавления определенных стандартов кодирования или предпочтений
Настройки форматирования вывода
Добавления знаний, специфичных для домена
Изменения подробности ответов
Улучшения поведения Claude Code по умолчанию без потери инструкций инструментов

Когда использовать пользовательский `systemPrompt`

Лучше всего для:

Полного контроля над поведением Claude
Специализированных задач одного сеанса
Тестирования новых стратегий подсказок
Ситуаций, когда инструменты по умолчанию не требуются
Создания специализированных агентов с уникальным поведением

Комбинирование подходов

Вы можете комбинировать эти методы для максимальной гибкости:

Пример: Стиль вывода с добавлениями, специфичными для сеанса

См. также

Output styles — Полная документация по стилям вывода
TypeScript SDK guide — Полное руководство по использованию SDK
Configuration guide — Общие параметры конфигурации

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

// IMPORTANT: You must specify settingSources to load CLAUDE.md
// The claude_code preset alone does NOT load CLAUDE.md files
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"], // Required to load CLAUDE.md from project
  },
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from 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
) {
  // User-level: ~/.claude/output-styles
  // Project-level: .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");
}

// Example: Create a code review specialist
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";

// Assuming "Code Reviewer" output style is active (via /output-style)
// 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);
}

Понимание системных подсказок

Методы изменения

Метод 1: Файлы CLAUDE.md (инструкции на уровне проекта)

Как CLAUDE.md работает с SDK

Пример CLAUDE.md

Использование CLAUDE.md с SDK

Когда использовать CLAUDE.md

Метод 2: Стили вывода (постоянные конфигурации)

Создание стиля вывода

Использование стилей вывода

Метод 3: Использование systemPrompt с добавлением

Метод 4: Пользовательские системные подсказки

Сравнение всех четырех подходов

Варианты использования и лучшие практики

Когда использовать CLAUDE.md

Когда использовать стили вывода

Когда использовать systemPrompt с добавлением

Когда использовать пользовательский systemPrompt

Комбинирование подходов

Пример: Стиль вывода с добавлениями, специфичными для сеанса

См. также

Метод 3: Использование `systemPrompt` с добавлением

Когда использовать `systemPrompt` с добавлением

Когда использовать пользовательский `systemPrompt`