Полное руководство по написанию системных промптов для агентов — уроки реверс-инжиниринга Claude Code

Я декомпилировал системный промпт Claude Code, изучил исходники DeepAgents и собрал своего ИИ-агента с нуля. Большинство гайдов по промптам — это сплошная вода.

Прямо сейчас в сфере ИИ происходит массовое помешательство.

В каждом туториале вас учат писать системные промпты так, будто вы творите заклинание — нужно лишь подобрать правильные слова, и модель будет повиноваться. «Ты НЕВЕРОЯТНО ТАЛАНТЛИВЫЙ senior-инженер с 20-летним опытом...» Знакомая картина?

Последние несколько месяцев я создавал VibeCom — ИИ-эдвайзера для стартапов, который проводит глубокое исследование рынка и генерирует аналитику уровня VC. Попутно я отреверс-инжинирил системный промпт Claude Code, перерыл исходники middleware от DeepAgents и сжег больше кредитов API, чем хотелось бы признавать. Главный урок? Большая часть того, что люди считают важным в системных промптах, на самом деле не имеет значения. А о том, что действительно важно, почти никто не говорит.

Этот пост — полноценный плейбук. Не 5-минутная выжимка, а всё то, что я хотел бы знать до того, как начал. Наливайте кофе.

1. Философия дизайна: Доверяйте модели

"An agent is a model. Not a framework. Not a prompt chain." — shareAI-lab/learn-claude-code

Эта мысль изменила для меня всё. LLM уже умеет рассуждать, планировать и выполнять задачи. Ваш системный промпт не учит её думать — он создает среду, в которой она будет работать.

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

У вашего системного промпта есть ровно четыре задачи:

Сказать, кто она — роль и идентичность
Показать, где стены — ограничения безопасности
Объяснить, как выглядит хороший результат — стандарты качества
Дать инструменты — возможности и знания

Вот и всё. Остальное — просто шум.

Концепция Harness (Каркаса)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

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

Не пишите системный промпт в виде блок-схемы. Модель сама решит, в каком порядке выполнять действия.

2. Структура промпта и порядок секций

Почему этот порядок важен

У LLM U-образная кривая внимания — они обращают максимум внимания на начало и конец вашего промпта, а середина выпадает. Это хорошо задокументированный эффект "Lost in the Middle".

Идентичность + Безопасность в самом верху: Модель в первую очередь устанавливает свою роль и границы (эффект первичности).
Основной воркфлоу чуть выше середины: Ваша самая важная секция — то, как агент делает свою работу.
Описания инструментов инжектятся системой после вашего промпта: Описания инструментов в Claude Code съедают ~11 438 токенов. Это означает, что ваш кастомный контент на самом деле оказывается ближе к началу, чем вы думаете — что помогает модели лучше следовать инструкциям.
Напоминания в самом низу: Используем эффект недавности (recency bias) для закрепления критически важных правил.

3. Написание каждой секции

3.1 Идентичность — Кто этот агент?

Цель: Закрепить роль модели в 1-3 предложениях.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Правила:

Будьте лаконичны — максимум 1-3 предложения.
Назовите роль явно (это помогает модели различать контексты).
Укажите основную обязанность («помогает с X»), а не размытое «ты полезный ассистент».
Упомяните SDK/платформу, если применимо («построен на базе Anthropic Claude Agent SDK»).

Антипаттерны:

«Ты полезный, безобидный и честный ИИ-ассистент» — слишком обобщенно, нет привязки к роли.
Целый абзац предыстории и лора — пустая трата токенов, модели не нужно развитие персонажа.

3.2 Безопасность и защита — Жесткие границы

Цель: Установить нерушимые поведенческие ограничения.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Правила:

Используйте префикс IMPORTANT: — иерархия инструкций при обучении Claude придает этому дополнительный вес.
Используйте абсолютные формулировки: NEVER, MUST NOT, Refuse to.
Указывайте как то, что разрешено, ТАК И то, что запрещено (двунаправленные ограничения понятнее).
Размещайте в самом верху, не прячьте в середине.
Повторяйте критические правила безопасности в конце — Claude Code делает именно так.

Зачем повторять? Эффект первичности (начало) + Эффект недавности (конец) = двойное закрепление. Декларация безопасности Claude Code появляется как в начале, так и в конце промпта. Не потому, что инженеры забывчивы — а потому, что они понимают U-образную кривую внимания.

3.3 Тон и стиль — Контроль вывода

Цель: Контролировать формат вывода и голос.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Правила:

Перечисляйте конкретные паттерны поведения, а не размытое «будь профессионалом».
Каждое правило должно быть тестируемым на true/false («коротко и по делу» против «постарайся быть кратким»).
Включайте требования к формату вывода (markdown? JSON? plain text?).
Указывайте, чего делать НЕ НАДО — многие проблемы со стилем решаются именно запретами.

Жемчужина Claude Code — Профессиональная объективность:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Этот абзац критически важен: он блокирует склонность модели к поддакиванию (sycophancy). Если вашему агенту нужно давать объективные оценки (ревью кода, оценка идей, архитектурные решения), вам абсолютно необходим подобный пункт.

3.4 Основной воркфлоу — Самая важная секция

Цель: Научить модель как работать — дать методологию, а не жесткие процедуры.

Это самая сложная для написания секция, и она дает наибольший эффект, если сделать всё правильно.

Главный принцип: давайте принципы, а не процедуры.

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

Подход Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Обратите внимание на слово "recommended" (рекомендуется) — а не "вы должны точно следовать этим шагам". Одно это слово дает модели пространство для адаптации.

Хорошее описание воркфлоу:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

В каждом правиле есть неявное «почему» — модель может понять намерение и обобщить его на новые сценарии.

Антипаттерны:

Жесткая процедура из 20 шагов — модель будет выполнять её механически и зависнет на неожиданных вводных.
«Сначала сделай А, потом Б, потом В» — это промпт-чейн, а не промпт для агента.
Избыточное руководство в вещах, которые LLM и так делает хорошо — пустая трата токенов.

Я усвоил это на горьком опыте с VibeCom. В ранних версиях был 10-шаговый воркфлоу для ресерча. Модель послушно выполняла все 10 шагов, даже когда шаг 3 уже давал ответ на вопрос пользователя. Когда я перешел на принципы («исследуй, пока не соберешь достаточно доказательств, затем синтезируй»), качество выросло, а затраты на токены снизились.

Исключение: Когда вывод потребляется машинами (общение между агентами, форматы ответов API), вы должны определять строгие форматы. Принципы — для поведения; схемы — для интерфейсов.

3.5 Политика использования инструментов — Разрешение неоднозначностей

Цель: Когда несколько инструментов могут сделать одно и то же, подскажите модели, какой предпочесть.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Правила:

Используйте "instead of" (вместо), чтобы выразить приоритет (А вместо Б).
Объясняйте, почему стоит предпочесть определенные инструменты («обеспечивает лучший UX», «снижает использование контекста»).
Определите стратегию параллелизма (независимые → параллельно, зависимые → последовательно).
Перечислите ограничения безопасности для использования инструментов (валидация путей, проверка прав).

Критически важная связь между инструментами и промптами:

Описания инструментов обычно инжектятся системой, и вы не можете редактировать их напрямую. Описания инструментов в Claude Code занимают ~11 438 токенов. Это значит:

Не повторяйте информацию, которая уже есть в описаниях инструментов.
Используйте системный промпт для стратегического руководства: когда использовать каждый инструмент, почему предпочесть один другому, порядок приоритетов.
Качество описания инструментов напрямую влияет на эффективность агента — если вы создаете собственного агента, инвестируйте время в написание отличных описаний для tools.

3.6 Предметные знания — Загрузка по требованию, а не заранее

Цель: Предоставить специализированные знания, которых может не быть в обучающих данных модели.

Ключевой принцип: постепенное раскрытие (progressive disclosure), а не свалка знаний.

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

Эту стратегию разделяют система Skills в Claude Code и middleware Progressive Disclosure в DeepAgents. Обе загружают знания по требованию через вызовы инструментов, а не загружают всё заранее.

Подходы к реализации:

Оставьте указатели в системном промпте: «Используй инструмент get_api_docs для получения документации при необходимости».
Используйте CLAUDE.md / AGENTS.md для контекста проекта — загружается в рантайме, а не хардкодится.
Используйте Skills / SKILL.md для обнаружения возможностей — модель видит меню доступных навыков и запрашивает полные спецификации по требованию.

3.7 Информация о среде — Контекст времени выполнения

Цель: Дать модели понимание среды, в которой она выполняется.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Правила:

Генерируйте динамически, никогда не хардкодьте.
Включайте: рабочую директорию, платформу, дату, имя модели, статус git.
Используйте структурированный формат (XML-теги или блоки кода) для удобного парсинга.
Дата имеет значение — модели нужно знать, когда наступило «сейчас», чтобы оценивать свежесть информации.

3.8 Напоминания — Финальное закрепление

Цель: Повторить самые критичные правила в конце промпта.

Claude Code повторяет свои ограничения безопасности и требование использовать TodoWrite в самом низу:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Правила:

Повторяйте только 2-3 самых критичных правила — не дублируйте всё подряд.
Используйте эффект недавности — модель сильнее запоминает недавний контент.
Лучшие кандидаты: ограничения безопасности, наиболее часто нарушаемые правила, напоминания об основном воркфлоу.

4. Бюджет токенов и управление контекстом

Справочник по распределению бюджета

Секция	Рекомендуемые токены	Примечания
Идентичность + Безопасность	200-500	Кратко, но не подлежит обсуждению
Тон и стиль	300-800	Правила должны быть конкретными, без воды
Основной воркфлоу	500-2,000	Самая важная секция, стоит инвестиций
Политика использования инструментов	300-1,000	Зависит от количества инструментов
Предметные знания	0-1,000	Предпочтительна загрузка по требованию
Информация о среде	100-300	Генерируется динамически
Напоминания	100-300	Повторяйте только самое важное
Ваш итог	1,500-6,000
Описания инструментов (системные)	5,000-15,000	Вне вашего контроля

Кривая деградации контекста

Тесты сообщества (Reddit u/CodeMonke_) показали, как деградирует следование инструкциям в реальных условиях:

< 80K токенов: Следование промпту остается стабильным
80K - 120K токенов: Выполнение инструкций начинает деградировать
> 120K токенов: Значительная деградация — модель «забывает» ранние инструкции
> 180K токенов: Серьезная деградация

Ваше контекстное окно в 200K ≠ 200K эффективного контекста. Планируйте соответственно.

Стратегии смягчения:

Держите ваш системный промпт компактным (< 6,000 токенов для вашей части).
Используйте суммаризацию для сжатия истории диалога (в DeepAgents она срабатывает на ~80K символов).
Размещайте критические правила на обоих концах промпта (U-образное внимание).
Инжектируйте теги <system-reminder> посреди диалога (подробнее об этом в разделе 8).

5. Принципы написания

5.1 Давайте принципы, а не процедуры

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

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

Исключение: Когда вывод потребляется машинами (общение между агентами, форматы API), определяйте строгие схемы.

5.2 Используйте абсолютные формулировки для жестких ограничений

Сила	Формулировка	Для чего использовать
Абсолютный запрет	`NEVER`, `MUST NOT`	Безопасность, необратимые операции
Строгое требование	`ALWAYS`, `MUST`	Правила основного воркфлоу
Рекомендация	`recommended`, `prefer`	Best practices с исключениями
Предложение	`consider`, `you may`	Опциональные оптимизации

Примеры из Claude Code:

NEVER update the git config — абсолютный запрет
ALWAYS prefer editing an existing file — строгое требование, но бывают исключения
The following steps are recommended — предлагаемый воркфлоу

5.3 Используйте примеры вместо объяснений

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Один пример учит лучше, чем 100 слов объяснений:

Модели усваивают паттерны из примеров надежнее, чем из абстрактных описаний.
Оборачивайте их в теги <example>, чтобы отделить от правил.
Приводите как позитивные («делай так»), так и негативные («не делай так») примеры.
Используйте реальные, конкретные примеры — никаких заглушек вроде "foo/bar".

5.4 Двунаправленные ограничения

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Если сказать только «делай это» → модель не знает, когда этого НЕ делать. Если сказать только «не делай это» → модель не знает альтернативы. Двунаправленность → ясность и однозначность.

5.5 Объясняйте «Почему», а не только «Что»

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Объяснение почему позволяет модели принимать правильные решения в пограничных случаях. Протокол безопасности git в Claude Code — это мастер-класс: каждое правило подразумевает свое обоснование.

5.6 Структура важнее прозы

Заголовки Markdown (##, ###) — модели распознают иерархию.
Маркированные списки вместо абзацев — каждое правило можно протестировать независимо.
XML-теги для специального контента: <example>, <env>, <system-reminder>.
Таблицы для сравнений и маппинга.
Никогда не вываливайте неструктурированный текст — в тестах на следование инструкциям структурированные промпты стабильно превосходят прозу на естественном языке.

6. Антипаттерны, которые впустую тратят ваши токены

Промпт-чейны под видом агентов

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Это не промпт для агента — это скрипт пайплайна. Модель будет выполнять его механически и потеряет способность к автономному планированию.

Решение: Скажите модели цель и ограничения. Пусть она сама решает, какие шаги предпринять.

Инженерия лести

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Комплименты и превосходные степени не улучшают качество вывода. У модели нет эго, которое нужно тешить. Сэкономьте эти 15 токенов для реального правила.

Свалки знаний

"Here is the complete API documentation for our 200 endpoints..."

Это пожирает ваше контекстное окно и ускоряет деградацию контекста. Замените на загрузку по требованию:

"Use the get_api_docs tool to retrieve API documentation when needed."

Дублирование описаний инструментов

Если в определении инструмента уже сказано: "Инструмент Read читает файл из файловой системы", не повторяйте это в системном промпте. Добавляйте только стратегическое руководство, которое не покрывается описанием инструмента — когда его использовать, почему предпочесть, порядок приоритетов.

Отсутствие обработки ошибок

Без явных указаний модели будут повторять неудачные вызовы инструментов в бесконечном цикле. Всегда добавляйте:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Игнорирование деградации контекстного окна

Окно контекста в 200K ≠ 200K эффективного контекста. Реальные тесты показывают, что деградация начинается с 80K. Вам нужна стратегия суммаризации.

7. Точки инъекции и приоритеты

Три метода кастомизации в Claude Code

Метод	Что заменяет	Расположение	Для чего лучше всего
Output Styles	Секции "Tone and style" + "Doing tasks"	Прямо перед описаниями инструментов	Изменение стиля взаимодействия
--append-system-prompt	Ничего (дополняет)	После output style, перед описаниями инструментов	Добавление специфического поведения
--system-prompt	Весь системный промпт	Оставляет описания инструментов + одну строку идентичности	Полная кастомизация (ядерный вариант)

Если вы используете несколько: Output Style → Append Prompt → Tool Definitions

Иерархия инструкций

Claude специально обучен с учетом иерархии инструкций:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

Это означает:

Правила из CLAUDE.md переопределяют дефолтное поведение системного промпта.
Прямые запросы пользователя переопределяют всё.
Ваш кастомный промпт переопределяет дефолтный промпт.

Механизмы динамической инъекции

<system-reminder> — инжектируется в любое сообщение посреди диалога, чтобы напомнить модели о критических правилах.
CLAUDE.md / AGENTS.md — загружаются в рантайме из файлов, добавляются к системному промпту.
Skills / SKILL.md — загружаются по требованию через вызовы инструментов, нулевой след в системном промпте.

8. Инъекции посреди диалога — Секретное оружие

Системный промпт появляется только один раз, в самом начале массива сообщений. Но LLM принимают на вход весь массив сообщений (чередующиеся сообщения пользователя / ассистента / инструментов), и вы можете инжектировать промпты в сообщения пользователя и результаты инструментов тоже. Claude Code активно использует эту технику в продакшене.

Почему это необходимо

Борьба с деградацией контекста (context rot). По мере того как диалоги становятся длиннее, следование модели инструкциям системного промпта ухудшается (заметно на 80K+ токенов). Инъекция напоминаний посреди диалога = обновление правил через эффект недавности.

Ментальная модель:

Системный промпт = конституция (устанавливается один раз, долгосрочный авторитет)
Напоминания в сообщениях пользователя = служебные записки (memos) (отправляются периодически, поддерживают исполнение)

Три точки инъекции в массиве сообщений

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

Расположение	Преимущество	Недостаток
Системный промпт	Эффект первичности, читается первым	Появляется один раз, «забывается» в длинных диалогах
Инъекция в сообщение пользователя	Эффект недавности, периодическое обновление	Каждая инъекция стоит токенов
Инъекция в результат инструмента	Самая естественная точка инъекции	Работает только когда вызываются инструменты

Как Claude Code использует это на практике

Обязательное условие — объявите теги в системном промпте:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Этот шаг критически важен: он говорит модели, что эти теги инжектируются системой, а не являются речью пользователя.

Применение 1: Поведенческие напоминания (периодическое обновление правил)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code использует это, чтобы напомнить модели о необходимости планировать с помощью TodoWrite — потому что модели склонны «забывать» о планировании и просто начинают писать код.

Применение 2: Переключение режимов (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

Plan mode не реализован в системном промпте. Это тег, инжектируемый в следующее сообщение пользователя. Это позволяет переключать режимы динамически без изменения системного промпта. Гениально.

Применение 3: Уведомления об изменении файлов

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Когда внешний процесс (линтер, форматтер, ручное редактирование) изменяет файл, система уведомляет модель через напоминание — предотвращая решения, основанные на устаревшем содержимом файла.

Применение 4: Динамический контекст (даты, правила проекта)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Контекст рантайма (дата, статус git, правила проекта) инжектируется через сообщения пользователя, а не хардкодится в системном промпте.

Правила написания напоминаний

Оборачивайте в XML-теги (<system-reminder>) — модель сможет отличить системную инъекцию от речи пользователя.
Заранее объявите теги в системном промпте — иначе модель может попытаться ответить на напоминание.
Не инжектируйте в каждое сообщение — каждая инъекция стоит токенов, инжектируйте только при необходимости.
Будьте кратки — напоминание — это не второй системный промпт, а всего 1-2 критических правила.
Не противоречьте системному промпту — напоминания дополняют и закрепляют, они не переопределяют.
Используйте для динамического переключения — plan mode, readonly mode, фича-флаги.

Когда использовать системный промпт, а когда напоминание в сообщении

Сценарий	Системный промпт	Напоминание в сообщении
Определение роли	✅	❌
Ограничения безопасности	✅ Первичная декларация	✅ Периодический повтор
Методология воркфлоу	✅	❌
Переключение режимов (plan mode)	❌	✅
Уведомления об изменении файлов	❌	✅
Дата / информация о среде	✅ Начальное значение	✅ Обновленное значение
Корректировка поведения	❌	✅
Напоминания об инструментах	✅ Определение правила	✅ Подталкивание к выполнению

9. Кеширование промптов — Экономия 90% на повторяющихся токенах

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

Для агентов это имеет огромное значение: вы заново отправляете системный промпт + описания инструментов при каждом вызове LLM в рамках диалога.

Ключевые цифры

Метрика	Значение
Стоимость при попадании в кеш	10% от обычной цены (экономия 90%)
Стоимость записи в кеш	125% от обычной цены (наценка 25% при первой записи)
Время жизни кеша (TTL)	5 минут (истекает, если нет запросов)
Минимальная длина для кеширования	1,024 токена (Claude 3.5+)
Гранулярность кеша	Совпадение по префиксу — от начала до отмеченного брейкпоинта
Максимум брейкпоинтов	4

Как это меняет дизайн промптов

Главный принцип: сначала статичный контент, динамический — в конце.

✅ Cache-friendly layout:
  System prompt (static)      ← Cache breakpoint 1
  Tool definitions (static)   ← Cache breakpoint 2
  CLAUDE.md / project rules   ← Cache breakpoint 3 (changes occasionally)
  Conversation history         ← Breakpoint 4 for rolling window

❌ Cache-destroying layout:
  System prompt
  DYNAMIC TIMESTAMP            ← Changes every request, everything after = cache miss
  Tool definitions
  Conversation history

Ловушка, о которой никто не предупреждает: Если вы поместите динамический таймстемп в середину вашего системного промпта, всё, что идет после него, станет промахом мимо кеша (cache miss). Каждый. Божий. Запрос. Один таймстемп не в том месте, и вы платите полную цену за тысячи токенов.

Использование API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marks a cache breakpoint
    }
  ],
  messages: [...]
});

Стратегия с несколькими брейкпоинтами

Breakpoint 1: System prompt           ← Almost never changes
Breakpoint 2: Tool definitions         ← Almost never changes
Breakpoint 3: Project rules / CLAUDE.md ← Changes occasionally
Breakpoint 4: First N history messages  ← Rolling window cache

Даже когда история диалога меняется, первые 3 брейкпоинта всё равно попадают в кеш. Диалог из 10 реплик экономит примерно 40-60% затрат на входные токены.

10. Чек-лист

После написания системного промпта проверьте его по этому чек-листу:

Структура

Идентичность находится в самом верху?
Ограничения безопасности отмечены словом IMPORTANT и повторяются в конце?
Есть четкое разделение секций с помощью заголовков?
Примеры обернуты в теги <example>?

Бюджет токенов

Ваша часть занимает < 6,000 токенов?
Не повторяется ли информация, которая уже есть в описаниях инструментов?
Предметные знания загружаются по требованию, а не заранее?
Нет ли излишнего лора или предыстории персонажа?

Качество правил

Каждое правило можно протестировать на true/false?
Для жестких ограничений используются абсолютные формулировки (NEVER/MUST)?
Для мягких предложений используются рекомендательные формулировки (recommended/prefer)?
Критические правила объясняют почему, а не только что?
Есть ли двунаправленные ограничения (делай это + не делай то)?

Поведение агента

Даны принципы, а не жесткие пошаговые процедуры?
Обработан сценарий «в вызове инструмента отказано»?
Обработана стратегия «столкнулся с препятствием» (не пытаться пробить стену лбом)?
Есть ли стратегия управления контекстом (порог суммаризации)?

Чего делать НЕ НАДО

Никакой лести или превосходных степеней?
Никаких избыточных деклараций «ты полезный ИИ»?
Не написано ли это как промпт-чейн?
Нет ли оверинжиниринга (фич, о которых никто не просил)?

Если бы я начинал сегодня

Вот что именно я бы сделал:

Начните с идентичности + безопасности в первых 3 строках. Два предложения о том, кто такой агент. Жесткие ограничения с NEVER/MUST. Повторите правила безопасности в конце.
Опишите ваш основной воркфлоу как принципы, а не шаги. Максимум 4-5 пунктов. Используйте "recommended" и "prefer" для мягких правил, "NEVER" и "MUST" для жестких.
Заложите бюджет в 1,500-6,000 токенов для вашей части. Описания инструментов добавят еще 5,000-15,000. Если у вас больше 6K, вы, вероятно, вываливаете знания, которые должны загружаться по требованию.
Структурируйте всё. Заголовки Markdown, маркированные списки, XML-теги для примеров. Структурированный промпт всегда превосходит прозу на естественном языке.
Встройте напоминания посреди диалога с первого дня. Объявите <system-reminder> в вашем системном промпте. Инжектируйте напоминания для критических правил, переключения режимов и обновления контекста.
Проектируйте с учетом кеша. Сначала статичный контент, динамический — в конце. Никогда не помещайте меняющиеся значения в тело системного промпта.

Ирония всей этой работы? Лучшие системные промпты — короткие. Кастомные инструкции Claude Code (без учета описаний инструментов) на удивление лаконичны. Каждая строка отрабатывает свое место.

Раньше я думал, что промпт-инжиниринг — это поиск хитрых трюков. Теперь я считаю, что это про дисциплину — говорить меньше, формулировать точнее и доверять модели во всем остальном. Модель умнее вашего промпта. Проектируйте среду, а не поведение.

Ссылки / Источники

Источник	Ключевой инсайт
Claude Code v2.0.14 System Prompt	Полный референс структуры промпта агента в продакшене
Reddit: Understanding Claude Code's 3 System Prompt Methods	Глубокий разбор Output Styles / --append / --system-prompt, реальные данные о деградации контекста
shareAI-lab/learn-claude-code	Философия «Модель — это агент», методология инженерии каркаса (harness)
Anthropic Prompt Engineering Docs	Официальные best practices по промптам
DeepAgents Framework	Middleware для суммаризации, постепенное раскрытие навыков (skills)

Полное руководство по написанию системных промптов для агентов — уроки реверс-инжиниринга Claude Code

1. Философия дизайна: Доверяйте модели

Концепция Harness (Каркаса)

2. Структура промпта и порядок секций

Рекомендуемая структура (на основе реверс-инжиниринга Claude Code v2.0.14)

Почему этот порядок важен

3. Написание каждой секции

3.1 Идентичность — Кто этот агент?

3.2 Безопасность и защита — Жесткие границы

3.3 Тон и стиль — Контроль вывода

3.4 Основной воркфлоу — Самая важная секция

3.5 Политика использования инструментов — Разрешение неоднозначностей

3.6 Предметные знания — Загрузка по требованию, а не заранее

3.7 Информация о среде — Контекст времени выполнения

3.8 Напоминания — Финальное закрепление

4. Бюджет токенов и управление контекстом

Справочник по распределению бюджета

Кривая деградации контекста

5. Принципы написания

5.1 Давайте принципы, а не процедуры

5.2 Используйте абсолютные формулировки для жестких ограничений

5.3 Используйте примеры вместо объяснений

5.4 Двунаправленные ограничения

5.5 Объясняйте «Почему», а не только «Что»

5.6 Структура важнее прозы

6. Антипаттерны, которые впустую тратят ваши токены

Промпт-чейны под видом агентов

Инженерия лести

Свалки знаний

Дублирование описаний инструментов

Отсутствие обработки ошибок

Игнорирование деградации контекстного окна

7. Точки инъекции и приоритеты

Три метода кастомизации в Claude Code

Иерархия инструкций

Механизмы динамической инъекции

8. Инъекции посреди диалога — Секретное оружие

Почему это необходимо

Три точки инъекции в массиве сообщений

Как Claude Code использует это на практике

Правила написания напоминаний

Когда использовать системный промпт, а когда напоминание в сообщении

9. Кеширование промптов — Экономия 90% на повторяющихся токенах

Ключевые цифры

Как это меняет дизайн промптов

Использование API

Стратегия с несколькими брейкпоинтами

Рекомендации по дизайну

10. Чек-лист

Структура

Бюджет токенов

Качество правил

Поведение агента

Чего делать НЕ НАДО

Если бы я начинал сегодня

Ссылки / Источники