Как настроить системный промпт Claude под задачи разработки

Системный промпт задаёт поведение Claude: роль, границы работы и способ ответа. Этот материал пригодится разработчикам и руководителям команд, которые подключают модель по API или собирают собственного агента. По материалам Anthropic: Modifying system prompts. Разберём, какие настройки относятся к Agent SDK, какие идеи можно перенести в обычный API-запрос и как проверить результат на своей задаче.

Что такое системный промпт и с чего начать

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

Для инструмента разработки, похожего на Claude Code, Anthropic предлагает пресет claude_code. Он содержит инструкции по работе с инструментами, а также правила безопасности. Если нужны дополнительные требования проекта, к пресету можно добавить append.

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

Наш практический вывод: сначала опишите рабочий процесс, затем пишите инструкции. Ответьте себе, кто получает результат, что агент вправе менять и в какой момент требуется участие человека. Без этого даже подробный промпт может описывать неподходящую роль.

Шаг первый: выберите основу поведения

В Agent SDK доступны разные отправные точки. Их важно различать при переносе существующего процесса.

Подход	Когда выбирать	Что учитывать
Пресет claude_code	Агент работает с кодом, человек наблюдает и направляет работу	Сохраняется набор инструкций Claude Code
Пресет с append	Нужны дополнительные соглашения и формат ответа	Добавление сохраняет инструкции пресета
Собственный промпт	У агента другая роль или границы полномочий	Необходимые инструкции вы составляете сами
Без настройки системного промпта	Нужен минимальный цикл вызова инструментов	Agent SDK использует сокращённые инструкции

Anthropic отдельно предупреждает: отсутствие systemPrompt в TypeScript или system_prompt в Python не означает использование полного пресета. Минимальный вариант поддерживает вызовы инструментов, но не включает остальные инструкции claude_code, в том числе инструкции безопасности. Поведение отличается от claude -p, где системный промпт Claude Code используется по умолчанию.

Отсюда наш вывод для миграции: успешный запуск через CLI ещё не подтверждает, что агент с настройками SDK по умолчанию будет вести себя так же. Выбор основы нужно задать явно и проверить.

Шаг второй: добавляйте правила с понятной целью

Для инструмента разработки Anthropic называет append способом дополнить пресет с наименьшим риском: существующие инструкции сохраняются. Туда можно вынести соглашения о коде, предметный контекст или требования к ответу.

Практически полезно описывать наблюдаемое действие. Вместо требования «проверяйте внимательно» укажите, какие проблемы искать, на какие данные опираться и что вернуть пользователю.

Ниже — наш пример инструкции для проверки изменений. В Agent SDK её можно использовать как дополнительное правило. В обычном API-запросе она может стать частью вашего системного промпта, но сама по себе не подключает пресет Claude Code.

Вы проверяете изменения в обработчике платежных уведомлений.

Ищите повторную обработку одного события, потерю ошибок
и изменение поведения существующих вызовов.

Для каждого замечания укажите:
- фрагмент, на котором основан вывод;
- условие возникновения проблемы;
- минимальный способ проверки.

Если данных недостаточно, сформулируйте вопрос.
Не утверждайте, что тесты пройдены, если результатов запуска нет.

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

Это редакционный способ проверки, а не обещание вендора о качестве ревью. Если модель регулярно выдаёт общие советы, уточните требуемые доказательства и формат замечания.

Шаг третий: отделите контекст проекта от роли агента

По руководству Anthropic, CLAUDE.md передаёт постоянные инструкции и контекст проекта. Agent SDK добавляет содержимое файла в разговор, оставляя системный промпт без изменений.

Загрузка зависит от источников настроек. Источник project отвечает за CLAUDE.md или .claude/CLAUDE.md в рабочем каталоге, а user — за ~/.claude/CLAUDE.md. Стандартные настройки query() включают оба источника. Если передать пустой список settingSources или setting_sources, файл не загрузится.

Наш вывод: сведения об архитектуре и соглашениях проекта удобно держать отдельно от общей роли помощника. Так проще менять контекст конкретного репозитория.

В обычном API-запросе не рассчитывайте на автоматическое чтение CLAUDE.md: описанный механизм относится к Agent SDK. Для проверки идеи передайте нужный контекст явно вместе с задачей. Например:

Контекст проекта:
- Денежные значения хранятся целыми числами в минимальных единицах.
- Повторное событие не должно повторно менять состояние заказа.
- Изменения публичного контракта требуют отдельного согласования.

Задача:
По приложенному коду предложите тесты обработчика уведомлений.
Для каждого теста укажите входные данные и ожидаемое состояние.
Отдельно перечислите предположения, которые нужно подтвердить.

Код обработчика:
[вставьте свой код]

Перед отправкой замените последнюю строку своим кодом. Такой запрос позволяет проверить, учитывает ли модель конкретные ограничения проекта, не настраивая файловый механизм SDK.

Шаг четвёртый: проверьте, что меняется вместе со стилем

Anthropic описывает output styles как сохраняемые инструкции о роли, тоне и формате ответа. Здесь есть существенное ограничение: пользовательский стиль исключает инструкции пресета по разработке ПО, если не задано keep-coding-instructions: true.

При этом параметр действует на инструкции полного системного промпта Claude Code. Для сессии с сокращённым промптом эффекта не будет.

Наш вывод: смену стиля стоит проверять как изменение поведения агента. После неё убедитесь, что сохранились нужные требования к работе с кодом.

В обычном API можно проверить желаемый формат собственной системной инструкцией:

Вы помогаете разобрать ошибку серверного приложения.

Структура ответа:
1. Что подтверждено переданными логами.
2. Какие причины пока остаются гипотезами.
3. Какую проверку выполнить следующей.
4. Какие дополнительные данные нужны.

Не придумывайте содержимое файлов и результаты команд.
Не предлагайте изменение до объяснения проверяемой гипотезы.

Передайте логи пользовательским сообщением. Проверьте, отделяет ли ответ наблюдения от предположений и предлагает ли действие, которое вы действительно можете выполнить.

Где заканчиваются возможности промпта

В руководстве Anthropic разрешения, hooks и skills рассматриваются как отдельные механизмы, которые тоже формируют поведение. Собственный системный промпт не заменяет их настройку.

Для разработчика это означает следующее: сформулированный запрет нужно сопоставить с реальными полномочиями агента. Проверяйте отдельно текст ответа и доступные действия. Приведённые выше инструкции можно попробовать в запросах к модели, но они не создают файловый доступ, инструменты или механизм согласования операций.

FAQ

Нужно ли всегда выбирать claude_code?

Anthropic рекомендует этот пресет для инструментов разработки с подходящим рабочим процессом. Для другой роли, интерфейса или модели разрешений руководство предлагает собственный промпт.

Сохраняет ли append инструкции пресета?

Да. По описанию Anthropic, append добавляет инструкции после пресета, сохраняя его содержимое.

Зависит ли загрузка CLAUDE.md от пресета?

Загрузка определяется источниками настроек Agent SDK. CLAUDE.md может использоваться с разными конфигурациями системного промпта.

Можно ли перенести эти настройки в обычный API?

Идеи роли, ограничений и формата ответа можно выразить системной инструкцией. Пресеты, загрузка файлов и output styles требуют соответствующего механизма Agent SDK или Claude Code.

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

Модели Claude (Anthropic) доступны по API на kosareva.cloud с оплатой в рублях; каталог моделей и цены размещены на странице каталога. Можно протестировать эти советы на своём коде или логах и проверить, какие инструкции помогают получить пригодный для работы ответ.

Источник темы: https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts