Важные секции, которые должны быть в наших PRD

Плиз проверьте, что эти блоки точно есть, и давайте их располагать в след структуре, чтобы было проще читать:

1. Назначение сервиса

Формат: один абзац, который коротко описывает суть и назначение сервиса, какую задачу он решает на большом ландшафте всей системы.

Planner - отвечает за заведение и запуск новых кампаний для взаимодействия с пользователями через агентов. Отбирает пользователей по сегментам и запускает по ним кампании.

2. Глоссарий основных сущностей сервиса

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

Task - задача для агента на общение с пользователем с конкретной целью. Агент должен ее стартануть в определенное время, и довести до завершения

Session - сессия разговора агент-пользователь, начинается с сообщения агента и заканчивается спустя последнее сообщение человека/агента через 2 часа

3. Как внешний мир видит этот компонент

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

POST /api/v1/offers/create - добавление нового оффера
{"offer_type": "bonus100", "offer_name": "xyz", ...}

PUT /api/v1/campaign/start - ручной запуск компании
{"id": "ieur-er4r4r-4r4"}

4. Модель БД сервиса

Детальное описание всех таблиц, полей, смысла полей, foreign keys constraints и индексов. Пишем все - nullable/not null/default итд. Самая важная секция, max attention - самая дорогая цена ошибки

== tasks (задачи на общение с пользователями) ==
id: bigint - pk
user_uuid: text - index
created_at: timestamp
...

== messages (сообщения чатов) ==
id: bigint - pk
task_id: bigint (fk -> tasks.id) - index
text: text // текст сообщения
role: test // автор сообщения, человек или агент
created_at: timestamp
...

id_task_id - unique constarint

5. Sequence flow всех основных процессов

По всем процессам есть расписанная по шагам последовательность действий, которые происходят в сервисе, в четкой структуре

1. Горутина обработки ответа на сообщение
- подтягиваем прошлую историю переписки из кеша переписок, если кеш пуст, достаем из messages)
- достаем заранее созданные инстанс агента из мапы агентов
- достаем информацию (user context) по пользователю из кеша пользователей (если нет, идем в avalon за данными)
- динамически собираем промт агента, добавляя туда историю, данные пользователя
- запускаем цикл агента, получаем новое сообщение
- сообщение сохраняем в messages + кеш
- отправляем сообщение в whatsup gateway

2. Создание новой кампании
...

6. Внешние сервисы, в которые мы ходим изнутри сервиса

Все внешние системы, в которых мы дергаем ручки/отправляем файлы/пишем в чужие очереди итд.

Главное отличие от пункта 3 - в нем наш сервис как черный ящик, и мы описываем как внешний мир его видит и использует. Тут - наоборот.

- хранилище офферов - забираем оффер в json описании при заведении новой кампании

7. Мониторинги, за которыми мы будем следить и которые будут нам звонить если что-то идет не так

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

- в табличке messages скопилось больше 500 сообщений от пользователей в статусе NEW, которые мы не разгребаем более 10 минут (то есть процессинг упал)


Зачем такая духота?

Важно, чтобы до программирования (передачи PRD в клод код) мы детально понимали логику будущего сервиса на всех уровнях, без участков "ну тут хуле делать, пусть клод сам затащит"

Второй момент - верю, что при идеально написанном PRD клод будет писать сервис за один промт, а потом потребуется лишь незначительная шлифовка. Если не пишет, будем править claude.md, пока не напишет))

И последнее, ваш PRD может иметь другие доп секции, но убедитесь что текущие присутствуют обязательно и оформлены один в один в том же формате

———
Сидел потел, пробовал оцифровать правила наших PRD для будущих сервисов, без помощи нейронок 🫠

Есть что-то важное, что забыл? За лучший комментарий отправлю Кабанчика бесплатно по России (без шуток)

#prd