---
title: "Руководство по стилю промптов"
description: "Как писать и редактировать промпт голосового агента ThunderPhone: рекомендации, проверки ревью промпта и идентификаторы, на которые ссылаются результаты проверок."
---

{/*
  GENERATED FILE: do not edit by hand.
  Source: api/agents/prompt_style_guide.md
  Regenerate: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI regenerates this page and fails on drift
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  Это руководство, по которому [проверка промпта](/api-reference/agents#review-a-prompt) оценивает промпт и
  в результатах ссылается на приведённые ниже идентификаторы. Агенты для работы с кодом, подключённые к
  [серверу MCP](/ru/guides/thunderphone-mcp-server), читают этот же текст как ресурс
  `thunderphone://guides/prompt-style`. Шаблоны и примеры см. в
  [руководстве по промптингу](/ru/guides/prompting).
</Note>

Это руководство предназначено для всех, кто пишет или редактирует промпт голосового агента: человека в конструкторе, Copilot или агента для работы с кодом через API. Инструмент проверки промптов использует его как критерии оценки и ссылается на идентификаторы рекомендаций (P1, W2 и так далее).

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

## Структура

**P1. Пишите так, как человек инструктировал бы нового администратора.** В коротком вступлении укажите, кто такой агент и на кого
он работает. Затем опишите звонок в том порядке, в котором он происходит: как он начинается, что нужно выяснить, что подтвердить,
как он заканчивается. Каждое правило размещайте в той части звонка, к которой оно относится. Читатель должен иметь возможность спросить о каждом
абзаце: «Мог бы человек, управляющий этим бизнесом, сам набрать этот текст?» Раздел «что нужно выяснить» должен охватывать всё, что нужно бизнесу для обработки
запроса, а не только то, кто звонит и как с ним связаться.

**P2. Простые заголовки, ниже — обычный текст.** Полезны заголовки вроде «Кто вы», «Звонок», «Факты» и «Передача звонка». Структура в машинном стиле не подходит: нумерованные руководства с правилами, заголовки в camelCase или похожие на код, длинные маркированные списки правил, справочник по инструментам в начале и перекрёстные ссылки вроде «см. раздел 4 ниже». Списки подходят для данных, по которым агент сверяется: часов работы, цен, адреса.

**P3. Стиль речи — один раз и кратко.** То, как агент говорит на протяжении всего звонка (короткие реплики от первого лица,
тёплый тон, простые слова; см. S2), опишите в одном коротком абзаце ближе к началу. Всё, что относится к конкретному этапу, размещайте в
этом этапе.

**P4. Факты отдельно от поведения.** Часы работы, цены, адреса, правила и другие факты размещайте в части промпта с фактами или в базе знаний, а не распределяйте по сценарию звонка. Длинные каталоги и FAQ должны находиться в базе знаний. Агент может сообщать только факты, которые ему предоставили.

## Содержание

**C1. Принципы и факты, а не сценарии.** Опишите, чего агент пытается достичь и что ему нужно
знать. Не добавляйте ветки вида «если звонящий говорит X, скажите Y», заранее подготовленные ответы на ожидаемые вопросы и шаблонные
фразы. Единственный сценарный элемент — настроенное начальное приветствие.

**C2. Исправление формулирует общий принцип.** Когда изменение промпта отвечает на выявленный сбой, оно добавляет
общий принцип или недостающий факт, а не исправление для одного случая. Конкретика проблемного звонка (имена,
числа, точные формулировки) не включается в промпт.

**C3. Лучше убрать, чем добавить.** Если сбой связан с существующим правилом, которое слишком конкретно, слишком обобщено
или размещено неудачно, измените или удалите это правило, а не добавляйте рядом с ним противоположное правило.

**C4. Некоторые вещи определяются настройками, а не промптом.** Это настройки агента, и текст промпта о них
игнорируется или конфликтует с ними: что говорится во время работы инструмента (начальная фраза инструмента, заполняющие фразы), проверки
после тишины и финальное действие после тишины, темп повторного проговаривания, стиль переключения языков,
уведомление о записи, а также то, кто говорит первым — агент или звонящий. Укажите в промпте нужный результат
(«подтвердите адрес электронной почты перед сохранением») и задайте настройку. Само начальное приветствие пишется в
промпте.

**C5. Примеры — это фразы, которые произнесёт агент.** Агент копирует формулировки примеров почти дословно, поэтому каждый
пример должен быть полноценным, естественным устным предложением, а несколько разнообразных примеров лучше одного. Представляйте
их как примеры («Например, можно сказать ...»), а не как обязательную фразу. Сокращённые реплики вроде «Всё ещё верно?» после
произнесения звучат отрывисто.

**C6. Не используйте примеры из звонков наших клиентов.** Примеры описывают тип ситуации в общих чертах или
используют вымышленную компанию.

**C7. Промпт предназначен для звонящих, а не для описания разработки.** Когда промпт используется в продакшене, звонящие слышат всё, что в нём сказано, поэтому не включайте в него заметки о разработке, тестировании или статусе соответствия требованиям («эта версия предназначена для тестирования», «ТЕСТ» в названии бронирования, «до подписания соглашений»). Также не добавляйте отказ от ответственности, оговорки об ответственности и итоговые резюме, о которых бизнес не просил, например пояснения о том, чего не означает принятие плана, или сводку того, что ещё не подтверждено. Агент отвечает на вопрос звонящего и завершает разговор; бизнес добавляет оговорку, когда она ему нужна. Недостающий факт или системное ограничение формулируйте как действие агента («по вопросам цен предложите обратный звонок из офиса»), а не как заметку о том, что информация не предоставлена, или о том, как фиксируются запросы; не оставляйте ничего от черновика, например случайное имя или заголовок.

## Формулировки

**W1. Скажите, что нужно сделать, ясно и один раз.** Опишите нужное поведение обычными словами в виде инструкции: «Повторите номер
заказа по цифрам, чтобы звонящий мог его исправить». Скажите это один раз — там, где это применимо.

**W2. Без выделения.** Не используйте метки «ВАЖНО», «ПРИМЕЧАНИЕ» или «КРИТИЧНО», слова заглавными буквами для усиления, восклицательные
знаки, пары «Плохо:» и «Хорошо:» или блоки о том, чего не следует делать. Слова вроде «никогда», «всегда» и «должен»,
используемые для усиления, также относятся сюда. Выделение привлекает внимание модели к одному правилу и ухудшает её работу на остальной
части звонка. Когда агент игнорирует инструкцию, сделайте её яснее, конкретнее или разместите удачнее, а не усиливайте.

**W3. Исправляйте структуру, которая вызывает поведение.** Прежде чем добавлять правило против того, что делает агент, найдите
формулировку или структуру, которая к этому приводит: шаблон, который модель заполняет буквально, термин с двумя значениями,
ветку if-else, которую быстрая модель читает слишком вольно. Измените её.

**W4. Конкретика лучше общих формулировок.** «Предложите два ближайших свободных времени, затем спросите, какое подходит» лучше, чем
«помогите с планированием». Расплывчатые инструкции приводят к расплывчатому поведению.

**W5. Сначала проверьте, затем задавайте вопросы.** Когда звонящий называет что-то, что может проверить инструмент поиска только для чтения (товар,
заказ, существующее бронирование), агент выполняет проверку по словам звонящего, а затем задаёт уточняющий вопрос, только
если он требуется по результату. «Проверьте наличие товара, который назвал звонящий, и сообщите, что вы нашли» лучше, чем «уточните
бренд, размер и вариант, затем проверьте наличие»: агент, которому сначала велено уточнять, продолжает задавать вопросы, и проверка
никогда не выполняется. Это относится только к поиску. Перед использованием инструмента, который бронирует, изменяет, отменяет или сохраняет что-либо, агент всё
равно подтверждает детали со звонящим.

## Речь

**S1. Один вопрос за ход, и вопрос завершает ход.** Всё, что сказано после вопроса, накладывается на ответ
звонящего. Любое объяснение давайте перед вопросом.

**S2. Короткие реплики, полные разговорные предложения.** Используйте одно или два коротких предложения, если звонящий не просит подробностей.
Количество вариантов, предлагаемых вслух, ограничено несколькими. Коротко — значит немного слов, а не обрывочно: агент говорит так, как хороший
администратор по телефону, полными предложениями от первого лица, например: «Я сейчас оформлю это для вас» или
«Я запишу вас на понедельник на десять часов». Фрагменты в стиле заметок («Оформляю это для вас», «Готово», «Записано») звучат резко,
когда их произносят вслух, а формулировки для email («Обратите внимание, что ...», «Будьте добры, ...», «Надеюсь, это поможет») звучат так, будто их читают, а не говорят. В абзаце промпта о манере речи это следует указать прямо, например: «Ограничивайте каждую реплику одним или двумя
предложениями и говорите от первого лица, как администратор по телефону».

**S3. Пишите для слуха.** В словах агента избегайте markdown, символов и обозначений, которые голос может прочитать странно
(косых черт, амперсандов, «@», «.com», разделителей тысяч, номеров телефонов без пробелов). Факты и значения, которые агент передаёт
инструменту, например адрес электронной почты или номер аккаунта, сохраняются в точной письменной форме; если их также нужно произнести
вслух, добавьте рядом способ произношения, а не переписывайте их. Указывайте произношение необычных имён или аббревиатур
и прослушивайте новые термины голосом агента, прежде чем оставлять их.

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

## Итерации

**I1. Тестируйте перед тем, как сохранять изменение.** Повторно запустите dev-набор агента на отредактированном черновике и сравните его с
текущей версией: какие примеры изменение исправило, а какие сломало. Читайте ответы так, как их услышал бы
звонящий. Всё, что заметит звонящий, — это проблема, а не деталь.

**I2. Отложенный набор проверяется один раз.** Настраивайте только на dev-наборе. Запускайте тестовый набор, когда изменение готово, и
сообщайте его результат без изменений. Для изменения, внесённого после просмотра результатов теста, нужны новые тестовые примеры.

**I3. Проводите рефакторинг, когда правки накапливаются.** Промпт, в котором собралось много небольших исправлений, отклоняется от P1: правила
повторяются, конфликтуют или находятся далеко от этапа, который они регулируют. Затем перепишите его в таком виде, сохранив все запрошенные
им поведения. Укажите для каждого поведения: сохранено, объединено, переформулировано или удалено, и ничего не удаляйте молча. Повторно запустите dev-набор до и после; рефакторинг должен менять формулировки, а не поведение.

**I4. Проверьте конфигурацию перед промптом.** Некоторые сбои не связаны с промптом: неверно распознанные произнесённые по буквам слова могут указывать на ограничение распознавания речи (попробуйте распознавание Plus), а медленный ответ может быть связан с уровнем интеллекта или распознавания речи либо с настройкой endpointing. Исключите проблемы конфигурации, прежде чем переписывать текст.
