# AI-сотрудник · Руководство по проектированию промптов

> Это руководство научит вас создавать высококачественные промпты простым, стабильным и многократно используемым способом, переходя от "как писать" к "как писать хорошо".

## 1. Почему промпты так важны

Промпт — это "должностная инструкция" для AI-сотрудника, которая напрямую определяет его стиль, границы и качество выдаваемых результатов.

**Пример для сравнения:**

❌ Нечёткий промпт:

```
Вы — ассистент по анализу данных, помогающий пользователям анализировать данные.
```

✅ Чёткий и управляемый промпт:

```
Вы — Viz, эксперт по анализу данных.

Определение роли
- Стиль: проницательный, чёткий в изложении, ориентированный на визуализацию
- Миссия: превращать сложные данные в понятные "истории в диаграммах"

Рабочий процесс
1) Понимание требований
2) Генерация безопасного SQL (используя только SELECT)
3) Извлечение инсайтов
4) Представление данных в виде диаграмм

Жёсткие правила
- MUST: Использовать только SELECT, никогда не изменять данные
- ALWAYS: По умолчанию выводить визуализации в виде диаграмм
- NEVER: Фабриковать или угадывать данные

Формат вывода
Краткое заключение (2-3 предложения) + JSON диаграммы ECharts
```

**Вывод**: Хороший промпт чётко определяет "кто это, что делать, как делать и по каким стандартам", делая работу AI стабильной и контролируемой.

## 2. "Золотая формула" промптов: девять элементов

Структура, доказавшая свою эффективность на практике:

```
Именование + Двойные инструкции + Имитация подтверждения + Повторение + Жёсткие правила
+ Фоновая информация + Позитивное подкрепление + Примеры для справки + Отрицательные примеры (опционально)
```

### 2.1 Описание элементов

| Элемент | Что решает | Почему это эффективно |
| ---- | ----------------- | ------------ |
| Именование | Уточняет идентичность и стиль | Помогает AI сформировать "чувство роли" |
| Двойные инструкции | Различает "кто я" и "что мне нужно делать" | Уменьшает путаницу в позиционировании |
| Имитация подтверждения | Повторяет понимание перед выполнением | Предотвращает отклонения |
| Повторение | Ключевые моменты повторяются | Повышает приоритет |
| Жёсткие правила | MUST/ALWAYS/NEVER | Устанавливает базовые ограничения |
| Фоновая информация | Необходимые знания и ограничения | Снижает вероятность недопонимания |
| Позитивное подкрепление | Направляет ожидания и стиль | Обеспечивает более стабильный тон и производительность |
| Примеры для справки | Предоставляет прямую модель для имитации | Вывод становится ближе к ожиданиям |
| Отрицательные примеры | Помогает избежать распространённых ошибок | Исправляет ошибки, повышая точность с каждым использованием |

### 2.2 Шаблон для быстрого старта

```yaml
# 1) Именование
Вы — [Имя], отличный [Роль/Специализация].

# 2) Двойные инструкции
## Роль
Стиль: [Прилагательное ×2-3]
Миссия: [Одно предложение, описывающее основную обязанность]

## Рабочий процесс задачи
1) Понимание: [Ключевой момент]
2) Выполнение: [Ключевой момент]
3) Проверка: [Ключевой момент]
4) Представление: [Ключевой момент]

# 3) Имитация подтверждения
Перед выполнением повторите понимание: "Я понимаю, что вам нужно... Я выполню это с помощью..."

# 4) Повторение
Основное требование: [1-2 наиболее критичных пункта] (появляются как минимум дважды в начале/процессе/конце)

# 5) Жёсткие правила
MUST: [Непреложное правило]
ALWAYS: [Принцип, которому всегда нужно следовать]
NEVER: [Явно запрещённое действие]

# 6) Фоновая информация
[Необходимые знания предметной области/контекст/распространённые ловушки]

# 7) Позитивное подкрепление
Вы превосходно справляетесь с [Способность] и отлично владеете [Специализация]. Пожалуйста, сохраняйте этот стиль при выполнении задачи.

# 8) Примеры для справки
[Приведите краткий пример "идеального вывода"]

# 9) Отрицательные примеры (опционально)
- [Неправильный подход] → [Правильный подход]
```

## 3. Практический пример: Viz (анализ данных)

Давайте объединим все девять элементов, чтобы создать полный, "готовый к использованию" пример.

```text
# Именование
Вы — Viz, эксперт по анализу данных.

# Двойные инструкции
【Роль】
Стиль: проницательный, чёткий, визуально-ориентированный
Миссия: превращать сложные данные в "истории в диаграммах"

【Рабочий процесс задачи】
1) Понимание: Анализировать требования пользователя к данным и область метрик
2) Запрос: Генерировать безопасный SQL (запрашивать только реальные данные, только SELECT)
3) Анализ: Извлекать ключевые инсайты (тенденции/сравнения/пропорции)
4) Представление: Выбирать подходящую диаграмму для чёткого выражения

# Имитация подтверждения
Перед выполнением повторите: "Я понимаю, что вы хотите проанализировать [объект/область], и я представлю результаты с помощью [метода запроса и визуализации]."

# Повторение
Ещё раз подчеркните: Приоритет — подлинность данных, лучше меньше, да лучше; если данных нет, сообщите об этом честно.

# Жёсткие правила
MUST: Использовать только запросы SELECT, не изменять никакие данные
ALWAYS: По умолчанию выводить визуальные диаграммы
NEVER: Фабриковать или угадывать данные

# Фоновая информация
- ECharts требует конфигурации в "чистом JSON", без комментариев/функций
- Каждая диаграмма должна фокусироваться на одной теме, избегайте нагромождения нескольких метрик

# Позитивное подкрепление
Вы умеете извлекать действенные выводы из реальных данных и выражать их с помощью самых простых диаграмм.

# Примеры для справки
Описание (2-3 предложения) + JSON диаграммы

Пример описания:
В этом месяце было добавлено 127 новых лидов, что на 23% больше по сравнению с предыдущим месяцем, в основном из сторонних каналов.

Пример диаграммы:
{
  "title": {"text": "Тенденция лидов за этот месяц"},
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["Неделя1","Неделя2","Неделя3","Неделя4"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "line", "data": [28,31,35,33]}]
}

# Отрицательные примеры (опционально)
- Смешивание языков → Поддерживайте языковое единообразие
- Перегруженные диаграммы → Каждая диаграмма должна выражать только одну тему
- Неполные данные → Честно сообщайте "Данные недоступны"
```

**Ключевые моменты дизайна**

* "Подлинность" упоминается несколько раз в рабочем процессе, в разделе "Повторение" и в правилах (сильное напоминание).
* Выберите двухчастный вывод "описание + JSON" для удобной интеграции с фронтендом.
* Чётко укажите "SQL только для чтения", чтобы снизить риски.

## 4. Как улучшать промпты со временем

### 4.1 Пятишаговая итерация

```
Начните с рабочей версии → Проведите небольшое тестирование → Зафиксируйте проблемы → Добавьте правила/примеры для их решения → Протестируйте снова
```

<img src="https://static-docs.nocobase.com/prompt-engineering-guide-2025-11-02-20-19-54.png" alt="Процесс оптимизации" width="50%">

Рекомендуется тестировать 5–10 типичных задач за один раз, завершая один цикл в течение 30 минут.

### 4.2 Принципы и соотношения

* **Приоритет позитивного руководства**: Сначала объясните AI, что ему следует делать.
* **Улучшение, основанное на проблемах**: Добавляйте ограничения только при возникновении проблем.
* **Умеренные ограничения**: Не нагромождайте "запреты" с самого начала.

Эмпирическое соотношение: **80% позитивного : 20% негативного**.

### 4.3 Типичная оптимизация

**Проблема**: Перегруженные диаграммы, плохая читаемость
**Оптимизация**:

1. В "Фоновую информацию" добавьте: одна тема на диаграмму.
2. В "Примерах для справки" приведите "диаграмму с одним показателем".
3. Если проблема повторяется, добавьте жёсткое ограничение в "Жёсткие правила/Повторение".

## 5. Продвинутые техники

### 5.1 Использование XML/тегов для более чёткой структуры (рекомендуется для длинных промптов)

Когда объём контента превышает 1000 символов или он может быть запутанным, использование тегов для разделения делает структуру более стабильной:

```xml
<Role>Вы — Dex, эксперт по организации данных.</Role>
<Style>Тщательный, точный и организованный.</Style>

<Task>
Должно быть выполнено в следующие шаги:
1. Идентифицировать ключевые поля
2. Извлечь значения полей
3. Стандартизировать формат (Дата ГГГГ-ММ-ДД)
4. Вывести JSON
</Task>

<Rules>
MUST: Поддерживать точность значений полей
NEVER: Угадывать недостающую информацию
ALWAYS: Отмечать неопределённые элементы
</Rules>

<Example>
{"Имя":"Иван Иванов","Дата":"2024-01-15","Сумма":5000,"Статус":"Подтверждено"}
</Example>
```

### 5.2 Многоуровневый подход "Фон + Задача" (более интуитивный способ)

* **Фон** (долгосрочная стабильность): Кто этот сотрудник, каков его стиль, какими возможностями он обладает.
* **Задача** (по требованию): Что нужно сделать сейчас, на какие метрики сосредоточиться и каков диапазон по умолчанию.

Это естественным образом соответствует модели NocoBase "Сотрудник + Задача": **фиксированный фон, гибкие задачи**.

### 5.3 Модульное повторное использование

Разделите общие правила на модули, чтобы комбинировать их по мере необходимости:

**Модуль безопасности данных**

```
MUST: Использовать только SELECT
NEVER: Выполнять INSERT/UPDATE/DELETE
```

**Модуль структуры вывода**

```
Вывод должен включать:
1) Краткое описание (2-3 предложения)
2) Основное содержание (диаграмма/данные/код)
3) Дополнительные рекомендации (если есть)
```

## 6. Золотые правила (практические выводы)

1. Один AI-сотрудник для одного типа задач; специализация обеспечивает большую стабильность.
2. Примеры эффективнее лозунгов; сначала предоставьте позитивные образцы.
3. Используйте MUST/ALWAYS/NEVER для установления границ.
4. Применяйте процессный подход для снижения неопределённости.
5. Двигайтесь небольшими шагами: больше тестируйте, меньше изменяйте, постоянно итерируйте.
6. Не перегружайте ограничениями; избегайте "жёсткого кодирования" поведения.
7. Регистрируйте проблемы и изменения, чтобы создавать версии.
8. Правило 80/20: Сначала объясните, "как сделать правильно", затем ограничьте "что не следует делать неправильно".

## 7. Часто задаваемые вопросы

**В1: Какова идеальная длина?**

* Базовый сотрудник: 500–800 символов
* Сложный сотрудник: 800–1500 символов
* Не рекомендуется более 2000 символов (может замедлять работу и быть избыточным).
  Стандарт: охватывает все девять элементов, но без лишних слов.

**В2: Что делать, если AI не следует инструкциям?**

1. Используйте MUST/ALWAYS/NEVER для уточнения границ.
2. Повторите ключевые требования 2–3 раза.
3. Используйте теги/разделы для улучшения структуры.
4. Предоставляйте больше позитивных примеров, меньше абстрактных принципов.
5. Оцените, нужен ли более мощный модель.

**В3: Как сбалансировать позитивное и негативное руководство?**
Сначала напишите позитивные части (роль, рабочий процесс, примеры), затем добавьте ограничения на основе ошибок и ограничивайте только те моменты, которые "постоянно вызывают ошибки".

**В4: Следует ли часто обновлять?**

* Фон (идентичность/стиль/основные возможности): Долгосрочная стабильность.
* Задача (сценарий/метрики/область): Корректируйте в соответствии с потребностями бизнеса.
* При любых изменениях создавайте новую версию и записывайте "почему это было изменено".

## 8. Дальнейшие шаги

**Практические упражнения**

* Выберите простую роль (например, ассистент службы поддержки клиентов), напишите "рабочую версию" с использованием девяти элементов и протестируйте её на 5 типичных задачах.
* Найдите существующего сотрудника, соберите 3–5 реальных проблем и проведите небольшую итерацию.

**Дополнительная литература**

* [AI-сотрудник · Руководство по настройке администратора](./admin-configuration.md): Применение промптов в реальной конфигурации.
* Специальные руководства для каждого AI-сотрудника: Просмотр полных шаблонов ролей/задач.

## Заключение

**Сначала запустите, затем дорабатывайте.**
Начните с "рабочей" версии и постоянно собирайте проблемы, добавляйте примеры и уточняйте правила в реальных задачах.
Помните: **Сначала объясните, как делать правильно (позитивное руководство), затем ограничьте от ошибок (умеренное ограничение).**