Skip to main content
Системные подсказки определяют поведение Claude, его возможности и стиль ответов. Начните с предустановки claude_code для инструментов кодирования, похожих на CLI или IDE, где человек наблюдает и направляет работу. Напишите свою собственную подсказку для агентов с другой поверхностью, идентичностью или моделью разрешений.

Как работают системные подсказки

Системная подсказка — это начальный набор инструкций, который определяет поведение Claude на протяжении всего разговора. Agent SDK имеет три начальные точки для неё:
  • Минимальное значение по умолчанию: когда вы не устанавливаете systemPrompt в TypeScript или system_prompt в Python, SDK использует минимальную подсказку, которая охватывает вызов инструментов, но исключает остальное содержимое предустановки claude_code, включая её инструкции по безопасности и защите. Это отличается от claude -p, который по умолчанию использует системную подсказку Claude Code. Если вы переходите с CLI и хотите совпадающее поведение, установите предустановку claude_code.
  • Предустановка claude_code: системная подсказка, которую использует CLI Claude Code, с инструкциями по использованию инструментов и инструкциями по безопасности и защите. Установите systemPrompt: { type: "preset", preset: "claude_code" } в TypeScript или system_prompt={"type": "preset", "preset": "claude_code"} в Python, опционально с append для добавления ваших собственных инструкций в конец.
  • Пользовательская строка: подсказка, которую вы пишете сами. SDK отправляет только то, что вы предоставляете.

Выберите начальную точку

Решающий фактор — насколько ваш агент похож на Claude Code: агент кодирования, работающий в репозитории, с человеком, который смотрит потоковый вывод и управляет работой. Чем дальше ваш продукт от этого, тем больше вы захотите написать свою собственную подсказку. «Отличается от Claude Code» обычно означает одно из следующего:
  • Другая поверхность: вывод не читается в терминале человеком, который его запустил. Интерфейсы чата, потребители структурированного вывода и автоматизация без кодирования каждый требуют подсказку, которая соответствует тому, как их вывод отображается и проверяется. Автоматизация кодирования без присмотра, такая как задание CI, которое исправляет ошибки lint или проверяет различия, всё ещё соответствует предустановке, потому что сама работа — это то, для чего написана предустановка.
  • Другая идентичность: агент не должен представлять себя как Claude Code. Бот поддержки, помощник по анализу данных или любой агент, специфичный для домена, нуждается в собственном имени, области и персоне.
  • Другая модель разрешений: агент работает автономно без одобрения человеком каждого шага или работает с узким набором ресурсов. Подсказка Claude Code предполагает, что человек находится в цикле с доступом к полному набору инструментов.
  • Задачи без кодирования: большая часть подсказки Claude Code — это руководство по кодированию. Для агентов исследования, контента или операций это руководство конкурирует с инструкциями, которые вам действительно нужны.
Таблица сравнения показывает, что сохраняет каждый метод настройки.

Настройка поведения агента

append и пользовательская строка подсказки каждый изменяют системную подсказку напрямую, а стиль вывода изменяет инструкции, которые Claude Code дает Claude для каждого ответа. CLAUDE.md идёт другим путём: SDK читает его и внедряет его содержимое в разговор как контекст проекта, поэтому он формирует поведение наряду с любой выбранной вами системной подсказкой. Skills, hooks и permissions также формируют поведение вне системной подсказки и рассматриваются на отдельных страницах.

Файлы CLAUDE.md для инструкций на уровне проекта

Файлы CLAUDE.md предоставляют Claude постоянный контекст проекта и инструкции. SDK внедряет их содержимое в разговор и оставляет системную подсказку нетронутой, поэтому они работают с любой конфигурацией системной подсказки. О том, что поместить в CLAUDE.md, где его разместить и как писать эффективные инструкции, см. When to add to CLAUDE.md и остальную часть How Claude remembers your project. Этот раздел охватывает то, что специфично для SDK: как загружается CLAUDE.md. SDK читает CLAUDE.md, когда включен соответствующий источник параметров: 'project' загружает CLAUDE.md или .claude/CLAUDE.md из рабочего каталога, а 'user' загружает ~/.claude/CLAUDE.md. Параметры query() по умолчанию включают оба источника, поэтому CLAUDE.md загружается автоматически. Если вы явно установите settingSources в TypeScript или setting_sources в Python, включите необходимые источники. Загрузка CLAUDE.md контролируется источниками параметров, а не предустановкой claude_code.

Загрузка CLAUDE.md с SDK

Чтобы загрузить CLAUDE.md, установите settingSources для включения уровня, на котором находится ваш CLAUDE.md. Пример ниже загружает CLAUDE.md на уровне проекта наряду с предустановкой claude_code, поэтому Claude имеет как полную подсказку агента кодирования, так и соглашения вашего проекта:
Когда вы запустите любой из примеров, SDK потоком передаёт сообщения по мере работы Claude: системное сообщение инициализации, сообщения помощника, пользовательские сообщения с результатами инструментов и финальное сообщение результата с исходом сеанса. CLAUDE.md постоянен во всех сеансах в проекте, общий с вашей командой через git и обнаруживается автоматически без изменений кода. Он не загружается, если вы передаёте пустой массив settingSources.

Стили вывода для постоянных конфигураций

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

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

Стиль вывода — это файл markdown с frontmatter для метаданных, за которым следует содержимое подсказки. Сохраните его в ~/.claude/output-styles/ для стиля на уровне пользователя, доступного в каждом проекте, или .claude/output-styles/ в вашем репозитории для стиля на уровне проекта, который вы можете зафиксировать и поделиться с вашей командой. Пользовательский стиль вывода исключает инструкции по разработке программного обеспечения из предустановки claude_code и использует ваши собственные. Чтобы сохранить их и наложить ваши инструкции поверх, задайте keep-coding-instructions: true во frontmatter. Эти инструкции есть только в полном системном промпте Claude Code, поэтому настройка не действует в сессии с более коротким системным промптом; задайте CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT равным 0, чтобы выбрать полный промпт на любой модели. Сохраняйте их, когда ваш агент всё ещё выполняет работу по разработке программного обеспечения. Исключайте их, когда вы полностью заменяете роль. Пример ниже определяет персону рецензента кода, которая сохраняет инструкции кодирования, поскольку проверка кода всё ещё выигрывает от руководства Claude Code по безопасности и качеству кода. Сохраните его как ~/.claude/output-styles/code-reviewer.md, чтобы сделать его доступным во всех проектах:
~/.claude/output-styles/code-reviewer.md

Активация стиля вывода

После создания активируйте стили вывода через:
  • CLI: запустите /output-style <style>, например /output-style concise, или запустите /config и выберите один. Команда /output-style требует Claude Code v2.1.269 или позже.
  • Параметры: установите outputStyle в .claude/settings.local.json
  • TypeScript SDK: установите outputStyle внутри встроенного объекта settings, передаваемого в query(), или укажите settings на файл параметров, который его устанавливает. outputStyle не является полем Options верхнего уровня:
В Python SDK установите outputStyle через опцию settings, которая принимает строку JSON, такую как '{"outputStyle": "Explanatory"}', или путь к файлу параметров, который его устанавливает. Примечание для пользователей SDK: Стили вывода загружаются, когда вы включаете settingSources: ['user'] или settingSources: ['project'] (TypeScript) / setting_sources=["user"] или setting_sources=["project"] (Python) в ваши параметры.

Добавление к предустановке claude_code

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

Улучшение кэширования подсказок между пользователями и машинами

По умолчанию два сеанса, которые используют одну и ту же предустановку claude_code и текст append, всё ещё не могут совместно использовать запись кэша подсказок, когда их расположения автоматической памяти отличаются. Предустановка встраивает это расположение в системную подсказку перед вашим текстом append. Расположение по умолчанию — это абсолютный путь под ~/.claude/projects/, названный по пути репозитория на диске, поэтому он отличается между пользователями, машинами и checkouts. Содержимое CLAUDE.md и детали окружения, такие как рабочий каталог, платформа, оболочка и версия ОС, не влияют на кэш системной подсказки, потому что Claude Code доставляет их в разговор, а не в системную подсказку. Чтобы сделать системную подсказку идентичной во всех сеансах, установите excludeDynamicSections: true в TypeScript или "exclude_dynamic_sections": True в Python. Контекст для каждого пользователя переходит в первое пользовательское сообщение, оставляя только статическую предустановку и ваш текст append в системной подсказке, чтобы идентичные конфигурации совместно использовали запись кэша между пользователями и машинами.
excludeDynamicSections требует @anthropic-ai/claude-agent-sdk v0.2.98 или позже, или claude-agent-sdk v0.1.58 или позже для Python. Установите его только на форме объекта предустановки. SDK игнорирует его, когда вы передаёте пользовательскую подсказку вместо предустановки; чтобы сохранить пользовательскую подсказку в кэше в TypeScript SDK, см. Cache the static part of a custom prompt.
Следующий пример объединяет общий блок append с excludeDynamicSections, чтобы флот агентов мог переиспользовать одну и ту же кэшированную системную подсказку:
Компромиссы: текст, который переходит из системной подсказки, всё ещё достигает Claude, но в пользовательском сообщении. Это по крайней мере расположение каталога автоматической памяти, и часто весь раздел автоматической памяти. Инструкции в пользовательском сообщении имеют немного меньший вес, чем тот же текст в системной подсказке, поэтому Claude может следовать его руководству автоматической памяти менее последовательно. Включите эту опцию, когда переиспользование кэша между сеансами важнее, чем это. Для эквивалентного флага в неинтерактивном режиме CLI см. --exclude-dynamic-system-prompt-sections.

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

Вы можете предоставить пользовательскую строку как systemPrompt для полной замены значения по умолчанию вашими собственными инструкциями.
В Python загружайте большую пользовательскую подсказку из файла с помощью system_prompt={"type": "file", "path": "..."} вместо передачи её в виде строки. Python SDK передаёт строковую подсказку как один аргумент командной строки подпроцессу CLI, поэтому подсказка, которая превышает лимит длины аргумента ОС, не работает при порождении процесса до отправки любого запроса API. На Linux ошибка — Argument list too long. См. SystemPromptFile для пороговых значений платформы и поведения Windows.

Кэширование статической части пользовательской подсказки

В TypeScript SDK вы можете передать пользовательскую подсказку как массив строк вместо одной строки, с маркером SYSTEM_PROMPT_DYNAMIC_BOUNDARY между статической частью и остальным. Используйте это, когда ваша подсказка объединяет инструкции, которые одинаковы на каждом запросе, с контекстом, который изменяется для каждого запроса, например клиент или билет, который обрабатывает агент. Когда вы передаёте обе части как одну строку, изменение части для каждого запроса изменяет всю системную подсказку, поэтому статические инструкции пропускают кэш тоже. Форма массива недоступна в Python SDK; ClaudeAgentOptions перечисляет формы, которые принимает system_prompt.
Claude Code разделяет подсказку только когда он вызывает Claude API напрямую или работает на Claude Platform on AWS. Во всех остальных конфигурациях, таких как Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry или LLM gateway, он отправляет всю подсказку как один блок, то же самое, что передача одной строки. То же самое происходит, когда вы установите CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.
Чтобы разделить подсказку, импортируйте SYSTEM_PROMPT_DYNAMIC_BOUNDARY из @anthropic-ai/claude-agent-sdk и передайте его как собственный элемент массива между двумя частями. SDK отправляет строки перед маркером как один текстовый блок и строки после него как второй блок, каждый со своей собственной точкой разрыва кэша. В примере ниже агент поддержки загружает свои инструкции по сортировке из файла и получает детали об одном билете на каждый запрос, поэтому инструкции остаются в кэше, пока детали билета изменяются:
TypeScript
Track cache tokens описывает поля cache_creation_input_tokens и cache_read_input_tokens на каждом сообщении результата. SDK собирает блоки из массива следующим образом:
  • SDK объединяет строки с каждой стороны маркера с пустой строкой между ними и удаляет сам маркер, поэтому текст маркера не достигает Claude.
  • Если вы включите маркер более одного раза, первый — это разделение и SDK удаляет остальные.
  • Если вы опустите маркер, SDK объединяет все строки в один блок, то же самое, что передача одной строки.
С флагами CLI --system-prompt или --system-prompt-file, подсказка — это одна строка, поэтому нет массива для переноса маркера. Включите строку, содержащую только __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__, между статической и частью для каждого запроса вместо этого. Claude Code разделяет подсказку на первой такой строке на те же два блока и удаляет эту строку. Требует Claude Code v2.1.275 или позже. В SDK предпочитайте форму массива, которая переносит границу без строки маркера.

Изменение подсказки существующего сеанса

По умолчанию, если вы передаёте другой append или пользовательскую подсказку, когда вы возвращаетесь к сеансу с помощью resume или continue, Claude не видит это на следующем ходу. Claude Code записывает системную подсказку на первом запросе сеанса и переиспользует эту запись до сжатия сеанса. Новый текст вступает в силу после этого сжатия или в новом сеансе.

Обновление инструкций Claude в середине сеанса

Если инструкции, которые вы поместили в системную подсказку, должны измениться во время работы сеанса, например потому что ваш пользователь переключил агента в режим только для чтения или отредактировал его конфигурацию в вашем приложении, отправьте новые инструкции в разговор вместо изменения systemPrompt:
  • В вашем следующем сообщении: включите новые инструкции в следующее пользовательское сообщение, которое вы отправляете.
  • Из hook: верните additionalContext из callback UserPromptSubmit или PostToolUse hook, написанный как фактическое утверждение, такое как “The workspace is now read-only”. SDK вставляет текст в разговор в точке, где сработал hook, поэтому записанная подсказка остаётся неизменной.

Отключение записи во время итерации формулировки

Пока вы итерируете формулировку подсказки и хотите, чтобы каждое редактирование достигло сеанса, который вы возобновляете, установите snapshot на false на форме объекта системной подсказки. Claude Code затем перестраивает подсказку на каждом запросе. Поле доступно на форме preset и custom systemPrompt в TypeScript и system_prompt в Python, и требует @anthropic-ai/claude-agent-sdk v0.3.257 или позже, или claude-agent-sdk v0.2.153 или позже. Сохраняйте запись включённой в production. С записью отключённой, другой append или пользовательская подсказка на возобновлённом сеансе достигает Claude на следующем ходу, и этот запрос не может переиспользовать кэш подсказок сеанса. Где API требует preserved thinking, Claude также теряет своё мышление из более ранних ходов. Вне cloud sessions, если вы запустите Claude Code в bare mode, передав --bare через extraArgs или установив CLAUDE_CODE_SIMPLE=1, запись остаётся отключённой, если вы не установите snapshot: true. Запись append или пользовательской подсказки по умолчанию требует Claude Code v2.1.265 или позже, который TypeScript Agent SDK поставляет с v0.3.265 и Python Agent SDK с v0.2.153. До Claude Code v2.1.268 сеансы, которые не получают флаги функций, включая сеансы на Amazon Bedrock, Google Cloud’s Agent Platform и Microsoft Foundry, перестраивали подсказку на каждом запросе и snapshot не имел эффекта.

Контекст, который Claude Code добавляет вне системного приглашения

Системные напоминания — это сообщения, которые Claude Code добавляет в диалог во время сессии, чтобы предоставить Claude контекст, например содержимое ваших файлов CLAUDE.md или примечание об изменении файла на диске. Claude Code отправляет их в диалоге, а не в системном промпте, поэтому большинство из них достигают Claude независимо от того, используете ли вы предустановку claude_code или передаёте собственную строку как systemPrompt. В этом разделе рассматриваются напоминания, которые с наибольшей вероятностью изменят поведение вашего агента, как отключить те, которые заменяет ваш агент, и как увидеть, что получил Claude в конкретном запросе.

Напоминания, которые Claude Code добавляет в беседу

Системные напоминания — это текст, который Claude Code добавляет в беседу вместе с приглашениями, которые отправляет ваш код. Следующие напоминания — это те, которые с наибольшей вероятностью изменят поведение вашего агента:
  • Инструкции проекта: файлы CLAUDE.md, которые загружает ваш параметр settingSources
  • Инструкции по стилю вывода: инструкции активного стиля вывода в основной беседе
  • Атрибуция коммитов и запросов на слияние: трейлер Co-Authored-By и нижний колонтитул запроса на слияние из параметра attribution
  • Вывод hooks: текст, который ваши hooks возвращают как additionalContext
  • Доступные skills: имена и описания skills, которые может вызвать Claude
  • Доступные subagents: имена и описания subagents, которые может запустить Claude
  • Подсказки списка задач: в сеансе, который имеет инструменты отслеживания задач, приглашение обновить список задач, когда Claude не трогал его несколько ходов
  • Примечания об изменённых файлах: примечание о том, что файл, который Claude читал ранее, изменился на диске
Claude Code представляет ваши файлы CLAUDE.md строкой, сообщающей Claude, что инструкции переопределяют поведение по умолчанию. Если вы передаёте собственную строку как systemPrompt, добавьте в неё предложение, объясняющее, что такое системное напоминание. Предустановка claude_code имеет одно, и ваша строка заменяет всю предустановку. Без этого ничто в вашем приглашении не говорит Claude, что напоминания, такие как содержимое CLAUDE.md и вывод hooks, поступают из приложения, а не от пользователя. Например:

Отключите контекст, который заменяет ваш агент

Отключите часть встроенного контекста, когда ваш агент предоставляет собственную версию того же руководства. Например, если ваше приглашение говорит Claude писать сообщения коммитов как PROJ-142: fix login redirect без трейлеров, Claude Code всё равно говорит Claude заканчивать каждое сообщение коммита трейлером Co-Authored-By, поэтому Claude получает два конфликтующих инструкции для одного коммита. Передавайте ключи параметров через параметр settings в TypeScript или settings в Python, и переменные окружения через параметр env. В TypeScript env заменяет унаследованное окружение, поэтому распределите process.env в него. Установите includeGitInstructions в false, чтобы исключить встроенные инструкции для коммитов и pull request, которые являются частью описания инструмента Bash и достигают Claude даже при пользовательском systemPrompt. Однако при минимальном варианте по умолчанию, пользовательском systemPrompt или пользовательском агенте основного потока с собственным промптом сессия начинается без снимка статуса git. Если вы установите CLAUDE_CODE_DISABLE_ATTACHMENTS, Claude Code также отправляет упоминания файлов @ как простой текст вместо их раскрытия в содержимое файла. Список доступных субагентов и уведомления о фоновых задачах всё ещё поступают. Чтобы отключить только раскрытие упоминаний файлов @, вместо этого установите CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 в Claude Code v2.1.299 или новее. Тогда Claude получает упомянутые пути и примечание о том, что их нужно прочитать с помощью файловых инструментов. Следующий пример предназначен для агента, который несёт собственные правила коммитов в append. Он устанавливает оба ключа attribution на пустые строки для удаления трейлера и нижнего колонтитула и отключает includeGitInstructions, чтобы собственные инструкции рабочего процесса коммитов Claude Code не конкурировали с вашими:
Чтобы подтвердить изменение, запустите пример в репозитории с поставленными в очередь изменениями и проверьте новый коммит с помощью git log -1. Сообщение заканчивается без трейлера Co-Authored-By.

Посмотрите, что получил Claude

Поток сообщений SDK не включает системные напоминания, поэтому чтение сообщений, которые получает ваш код, не покажет вам, что видел Claude. Чтобы их увидеть, логируйте запросы, которые отправляет Claude Code:
  • Логирование необработанных запросов: установите OTEL_LOG_RAW_API_BODIES в file:<dir>. Claude Code записывает каждое тело запроса в этот каталог.
  • Шлюз, который вы контролируете: укажите ANTHROPIC_BASE_URL на прокси, который логирует тела запросов.
В логируемом запросе посмотрите в массив messages. Напоминание появляется внутри пользовательского сообщения, обёрнутого в теги <system-reminder>, или, на некоторых моделях, как отдельное сообщение с ролью system.

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

Четыре метода настройки различаются по месту их расположения, способу совместного использования и тому, что они сохраняют из предустановки claude_code. “С добавлением” означает использование systemPrompt: { type: "preset", preset: "claude_code", append: "..." } в TypeScript или system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} в Python. CLAUDE.md не изменяет сам системный запрос: SDK внедряет его содержимое в разговор как контекст проекта.

Объединение подходов

Подходы могут быть объединены. Постоянный стиль вывода или CLAUDE.md устанавливает долгосрочное поведение, а append добавляет инструкции, специфичные для сеанса, поверх без изменения сохраненной конфигурации.

Объединение стиля вывода с дополнениями, специфичными для сеанса

Приведенный ниже пример предполагает, что стиль вывода Code Reviewer уже активен. Блок append добавляет области фокуса, специфичные для сеанса, поверх персоны, так что один сеанс проверки может приоритизировать OAuth и хранение токенов без изменения сохраненного стиля вывода:

См. также

  • Стили вывода: создание, управление и совместное использование стилей вывода для CLI, включая формат файла и места хранения
  • Как Claude запоминает ваш проект: что поместить в CLAUDE.md, где его разместить и как писать эффективные инструкции проекта
  • Справочник TypeScript SDK: полный тип Options, включая systemPrompt, settingSources и settings
  • Справочник Python SDK: полный тип ClaudeAgentOptions, включая system_prompt и setting_sources
  • Параметры: справочник settings.json, включая место хранения стилей вывода и другой конфигурации