claude_code для инструментов кодирования, похожих на CLI или IDE, где человек наблюдает и направляет работу. Напишите свою собственную подсказку для агентов с другой поверхностью, идентичностью или моделью разрешений.
На этой странице рассматривается:
- Как работают системные подсказки, с таблицей решений для выбора между предустановкой, предустановкой с
appendи пользовательской подсказкой - Настройка поведения агента с файлами CLAUDE.md, стилями вывода,
appendили пользовательской строкой - Сравнение четырёх подходов по постоянству, области действия и тому, что они сохраняют
- Объединение подходов для наслоения методов настройки вместе
Как работают системные подсказки
Системная подсказка — это начальный набор инструкций, который определяет поведение 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.md идёт другим путём: SDK читает его и внедряет его содержимое в разговор как контекст проекта, а не в системную подсказку, поэтому он формирует поведение наряду с любой выбранной вами системной подсказкой. Skills, hooks и permissions также формируют поведение вне системной подсказки и рассматриваются на отдельных страницах.
Файлы CLAUDE.md для инструкций на уровне проекта
Файлы CLAUDE.md предоставляют Claude постоянный контекст проекта и инструкции. SDK внедряет их содержимое в разговор, а не в системную подсказку, поэтому они работают с любой конфигурацией системной подсказки. О том, что поместить в 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/output-styles/code-reviewer.md, чтобы сделать его доступным во всех проектах:
~/.claude/output-styles/code-reviewer.md
Активация стиля вывода
После создания активируйте стили вывода через:-
CLI: запустите
/configи выберите стиль вывода -
Параметры: установите
outputStyleв.claude/settings.local.json -
TypeScript SDK: установите
outputStyleвнутри встроенного объектаsettings, передаваемого вquery(), или укажитеsettingsна файл параметров, который его устанавливает.outputStyleне является полемOptionsверхнего уровня:
.claude/settings.local.json, используйте append или пользовательскую строку подсказки вместо этого.
Примечание для пользователей SDK: Стили вывода загружаются, когда вы включаете settingSources: ['user'] или settingSources: ['project'] (TypeScript) / setting_sources=["user"] или setting_sources=["project"] (Python) в ваши параметры.
Добавление к предустановке claude_code
Вы можете использовать предустановку Claude Code со свойством append для добавления ваших пользовательских инструкций при сохранении всей встроенной функциональности.
Улучшение кэширования подсказок между пользователями и машинами
По умолчанию два сеанса, которые используют одну и ту же предустановкуclaude_code и текст append, всё ещё не могут совместно использовать запись кэша подсказок, если они запускаются из разных рабочих каталогов. Это потому, что предустановка встраивает контекст для каждого сеанса в системную подсказку перед вашим текстом append: рабочий каталог, является ли это репозиторием git, платформу, активную оболочку, версию ОС и пути автоматической памяти. Любое различие в этом контексте создаёт другую системную подсказку и промах кэша. Содержимое CLAUDE.md не влияет на кэш системной подсказки, потому что SDK внедряет его в разговор, а не в системную подсказку.
Чтобы сделать системную подсказку идентичной во всех сеансах, установите 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. Это применяется только к форме объекта предустановки и не имеет эффекта, когда systemPrompt является строкой.append с excludeDynamicSections, чтобы флот агентов, работающих из разных каталогов, мог переиспользовать одну и ту же кэшированную системную подсказку:
--exclude-dynamic-system-prompt-sections.
Пользовательские системные подсказки
Вы можете предоставить пользовательскую строку какsystemPrompt для полной замены значения по умолчанию вашими собственными инструкциями.
Сравнение четырех подходов
Четыре метода настройки различаются по месту их расположения, способу совместного использования и тому, что они сохраняют из предустановкиclaude_code.
“С добавлением” означает использование
systemPrompt: { type: "preset", preset: "claude_code", append: "..." } в TypeScript или system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} в Python. CLAUDE.md не изменяет сам системный запрос: SDK внедряет его содержимое в разговор как контекст проекта.
Варианты использования и лучшие практики
Когда использовать CLAUDE.md
Используйте CLAUDE.md для инструкций, которые должны применяться к каждому сеансу в проекте, независимо от того, какой системный запрос использует сеанс: стандарты кодирования, общие команды, контекст архитектуры и соглашения команды. CLAUDE.md фиксируется в вашем репозитории, поэтому он остается синхронизированным с кодом, который он описывает. Полное руководство см. в разделе Когда добавлять в CLAUDE.md. Файлы CLAUDE.md загружаются, когда включен источник параметровproject, что происходит для параметров query() по умолчанию. Если вы явно установите settingSources в TypeScript или setting_sources в Python, включите 'project' для продолжения загрузки CLAUDE.md на уровне проекта.
Когда использовать стили вывода
Стили вывода предназначены для персон, которые вы хотите повторно использовать в CLI и SDK без изменения кода приложения. Поскольку они находятся в виде файлов в.claude/output-styles, одна и та же персона доступна из /config в CLI и из любого сеанса SDK, который загружает соответствующий источник параметров.
Лучше всего подходит для:
- Постоянных изменений поведения между сеансами
- Конфигураций, общих для команды
- Специализированных помощников, таких как рецензент кода, специалист по данным или DevOps помощник
- Сложных изменений подсказок, которые требуют версионирования
- Создание выделенного помощника по оптимизации SQL
- Построение рецензента кода, ориентированного на безопасность
- Разработка помощника по обучению с определенной педагогикой
Когда использовать systemPrompt с добавлением
Используйте append, когда предустановка claude_code уже подходит для вашего продукта и вам нужно только добавить дополнительные инструкции. Вы сохраняете руководство инструментов предустановки, правила безопасности и соглашения кодирования без их переимплементации.
Лучше всего подходит для:
- Добавления определенных стандартов кодирования или предпочтений
- Настройки форматирования вывода
- Добавления знаний, специфичных для домена
- Изменения многословности ответов
- Улучшения поведения Claude Code по умолчанию без потери инструкций инструментов
Когда использовать пользовательский systemPrompt
Используйте пользовательский запрос, когда поверхность вашего агента, идентичность или модель разрешений отличаются от Claude Code, как описано в разделе Решите на начальную точку. Вы определяете полный набор инструкций, включая любое руководство инструментов и правила безопасности, которые требуются вашему агенту.
Лучше всего подходит для:
- Полного контроля над поведением Claude
- Специализированных однократных задач
- Тестирования новых стратегий подсказок
- Ситуаций, когда инструменты по умолчанию не требуются
- Построения специализированных агентов с уникальным поведением
Объединение подходов
Эти методы можно комбинировать. Постоянный стиль вывода или 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, включая место хранения стилей вывода и другой конфигурации