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 имеет как полную подсказку агента кодирования, так и соглашения вашего проекта:
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верхнего уровня:
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, чтобы флот агентов мог переиспользовать одну и ту же кэшированную системную подсказку:
--exclude-dynamic-system-prompt-sections.
Пользовательские системные подсказки
Вы можете предоставить пользовательскую строку какsystemPrompt для полной замены значения по умолчанию вашими собственными инструкциями.
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
cache_creation_input_tokens и cache_read_input_tokens на каждом сообщении результата.
SDK собирает блоки из массива следующим образом:
- SDK объединяет строки с каждой стороны маркера с пустой строкой между ними и удаляет сам маркер, поэтому текст маркера не достигает Claude.
- Если вы включите маркер более одного раза, первый — это разделение и SDK удаляет остальные.
- Если вы опустите маркер, SDK объединяет все строки в один блок, то же самое, что передача одной строки.
--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из callbackUserPromptSubmitилиPostToolUsehook, написанный как фактическое утверждение, такое как “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 читал ранее, изменился на диске
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, включая место хранения стилей вывода и другой конфигурации