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

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

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

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

Системная подсказка 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

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

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

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

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

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

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

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

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

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

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

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

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

• 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 для добавления ваших пользовательских инструкций при сохранении всей встроенной функциональности.

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

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

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

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

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

Примечание: "С добавлением" означает использование 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
• Специализированных задач одного сеанса
• Тестирования новых стратегий подсказок
• Ситуаций, когда инструменты по умолчанию не требуются
• Создания специализированных агентов с уникальным поведением

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

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

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

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

См. также

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