Предметная областьОписания страницГайдлайн

Гайдлайн: как описывать разделы программы для AI чат-помощника

Актуально на: 2026-03-25

Контекст

Описания разделов используются для генерации системного промпта AI-помощника, который работает в отдельном чате (не встроен в UI страницы). Помощник собирает данные у пользователя через диалог и вызывает API для сохранения.

Поэтому описание должно быть ориентировано на сбор данных, а не на UI-взаимодействие.

Формат файла описания раздела

Каждый раздел описывается в отдельном .md файле со следующей структурой:

# Название раздела
 
## Назначение
Одно-два предложения: что делает этот раздел и зачем он нужен пользователю.
 
## Роль в проекте
- Как данные этого раздела влияют на другие разделы и итоговые расчёты.
- Конкретные связи: какие разделы зависят от этого, от каких зависит этот.
 
## Зависимости
- **Требует заполнения до этого раздела:** [список разделов]
- **От этого раздела зависят:** [список разделов]
 
## Данные для сбора
 
### Сущность: [Название] (например: "Продукт", "Этап", "Сотрудник")
 
| Поле | Тип | Обязательное | Ограничения | Значение по умолчанию |
|------|-----|:------------:|-------------|----------------------|
| название | строка | да | макс. 255 символов | — |
| цена | число | да | > 0 | — |
| дата начала | дата | да | в рамках проекта | дата начала проекта |
| комментарий | строка | нет | — | — |
 
### Повторяемые/периодические данные
Если раздел содержит данные по периодам (помесячные объёмы, цены и т.п.):
 
| Параметр | Тип | Обязательное | Ограничения |
|----------|-----|:------------:|-------------|
| объём сбыта | число/период | да | >= 0 |
 
## Валидации и ограничения
- Перечислить бизнес-правила, которые должны соблюдаться.
- Примеры: "сумма оплат по графику не должна превышать стоимость этапа",
  "дата найма должна быть в рамках проекта".
 
## Сценарий диалога (рекомендуемый)
Краткое описание того, как AI должен вести диалог для заполнения этого раздела:
1. Что спросить первым
2. Какие уточняющие вопросы задать
3. Что предложить по умолчанию
4. Когда считать раздел заполненным
 
## Примеры данных
Один-два примера заполненного раздела в формате JSON или таблицы.
Помогает AI понимать ожидаемый результат.

Правила написания

Что писать

  1. Данные, не действия. Описывай какие данные нужно собрать, а не какие кнопки нажать.

    • Плохо: “Нажать кнопку «Добавить продукт», заполнить форму”
    • Хорошо: “Собрать: название (обязательное), единица измерения (обязательное), цена (обязательное, число > 0)”

  2. Типы и ограничения полей. Для каждого поля указывай тип данных и валидацию.

    • Плохо: “Указать цену”
    • Хорошо: “цена: число, обязательное, > 0, валюта проекта”

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

    • Плохо: “Данные используются в плане сбыта”
    • Хорошо: “Требует: Заголовок проекта. Зависят: План сбыта, План производства”

  4. Бизнес-правила. Описывай правила валидации и ограничения, которые AI должен проверять.

    • Плохо: “Дата должна быть корректной”
    • Хорошо: “Дата начала продаж >= дата начала проекта И <= дата начала + длительность проекта”

  5. Значения по умолчанию. Если поле имеет разумное значение по умолчанию, укажи его. AI будет предлагать его пользователю.

  6. Сценарий диалога. Опиши рекомендуемый порядок вопросов. AI будет группировать вопросы, а не спрашивать по одному полю.

  7. Примеры. Дай один-два примера заполненных данных. Это критически важно для AI — он будет ориентироваться на формат и масштаб значений.

Чего не писать

  1. UI-действия. Не описывай кнопки, вкладки, переключатели, drag-and-drop, чекбоксы, наведение курсора. Чат-помощник не имеет доступа к UI.

  2. Навигацию. Не описывай как перейти на страницу, открыть меню, переключить вид. Роуты приложения указывай только в справочных целях.

  3. Визуализацию. Не описывай графики, спарклайны, диаграммы Ганта. Описывай данные, которые за ними стоят.

  4. Опциональные UI-фичи. “Закрепить период”, “развернуть строку”, “сравнить на графике” — это удобства интерфейса, не данные.

  5. Размытые формулировки обязательности. Не “опционально, но желательно”. Пиши чётко: обязательное для MVP / необязательное.

Чеклист перед сдачей описания

  • Есть раздел “Назначение” (1-2 предложения)
  • Есть раздел “Зависимости” с конкретными названиями разделов
  • Все поля описаны в таблице с типом, обязательностью и ограничениями
  • Указаны бизнес-правила валидации
  • Есть рекомендуемый сценарий диалога
  • Есть хотя бы один пример заполненных данных
  • Нет UI-действий (кнопки, вкладки, навигация)
  • Нет описания визуализаций (графики, диаграммы)
  • Обязательность указана чётко: да/нет, без “желательно”
ОбзорИдеальный путь пользователя (MVP)