Отчёт: согласование ТЗ и работа с ИИ

1. Что было в исходном запросе заказчика

В первом чате задача пришла как заказ на Laravel + Vue проект, где нужно загрузить список сайтов, собрать по ним данные из Keyso и gvozd.org, сравнить результаты и показать сводку с графиками.

Входные данные

Админ загружает список сайтов. В изначальном ТЗ фигурировал диапазон “от 10 до 500 сайтов”.

Источники метрик

Keyso: видимость, ссылки, трафик, контекстная реклама. Gvozd/Setips: ошибки, CMS, страницы, технические показатели.

Результат

Сводная таблица, сравнение сайтов и графики: среднее значение, медиана, лучшее значение по метрикам.

Из рабочих сообщений: “После этого сравниваем полученные данные между собой и получаем сводную таблицу. С возможностью строить графики по типу среднее значение ИКС, медианное значение ИКС”.

Итерации разработки: кабинет, админка, сайты, операции — Картинка 1. Визуальная хронология разработки: от кабинета и админки до сайтов, provider runs и стабилизации Setips.

2. Как уточнялось ТЗ с заказчиком

В чате были не только задачи к ИИ, но и реальные уточнения от заказчика. Именно они превратили общую идею в рабочее MVP.

Вопрос / тема	Ответ заказчика	Как это повлияло на разработку
Что видит пользователь после регистрации?	Пользователь видит все ниши, но выбрать может только одну.	Добавлен сценарий выбора активной ниши и ограничение кабинета выбранной нишей.
Кто заводит сайты и ниши?	В MVP сайты и ниши заводит только админ.	Основной CRUD вынесен в админку, пользовательский кабинет стал read-only по данным.
Нужны ли тарифы и оплата?	На первом этапе только регистрация и роли, “проверка пойдёт или нет”.	Оплата не попала в MVP. Фокус ушёл на роли, доступы, админку и сбор данных.
Что с публичной страницей?	Нужна страница, куда запускается реклама; данные закрыты регистрацией.	Лендинг отделён от личного кабинета, а доступ к данным закрыт авторизацией.
Как обновляются данные?	Данные обновляются по требованию админом.	Появились ручные refresh runs, provider runs, журналы и статусы обработки.
Что нужно видеть в админке?	Лимиты API и падения при обращении к API.	Добавлены журналы API-лимитов, ошибок провайдеров и история запусков.

Было стало: кабинет пользователя и админская зона — Картинка 2. Как уточнения ТЗ превратились в два рабочих экрана: кабинет пользователя и админскую зону.

3. Как я оформил работу в этапы

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

1

Проектирование

Финализация структуры MVP, проектирование базы, описание сущностей: пользователи, ниши, сайты, история показателей, логи API.

Контрольная точка: согласована архитектура проекта и структура данных.

2

Backend-основа

Laravel-проект, регистрация, авторизация, роли, админская часть, API для фронтенда.

Контрольная точка: готова серверная часть MVP с авторизацией и админкой.

3

Интеграции и сбор данных

Подключение Keyso и gvozd.org/Setips, сохранение данных по сайтам, история изменений, ручной запуск администратором, логирование ошибок и лимитов.

Контрольная точка: данные собираются, сохраняются и видны по статусам.

4

Кабинет и визуализация

Сводка по выбранной нише, сравнение сайтов, таблицы метрик, графики среднего, медианы и лучшего значения.

Контрольная точка: пользователь видит понятную аналитику по выбранной нише.

5

Стабилизация после реальных проверок

Очереди, polling, права на сервере, корректные статусы, очистка старых/фиктивных метрик.

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

4. Как я корректировал ИИ по ходу работы

По прошлым чатам видно, что я не просто “попросил ИИ написать код”. Я постоянно сравнивал результат с ТЗ, сообщениями заказчика, макетом и поведением на сервере, а затем корректировал ИИ.

Моя корректировка	Почему это было важно	Что поменялось в реализации
Верстка “Откати верстку. Вот что оказывается писал заказчик...”	ИИ ушёл не в тот визуальный/продуктовый сценарий, а заказчику нужна была рекламная страница + закрытый кабинет.	Фокус вернулся к реальному сценарию: публичная страница, регистрация, личный кабинет, данные закрыты.
Стиль “В стиле Keyso”, затем “сделай красным как gvozd.ru”.	Визуальный стиль уточнялся по ходу согласования и сравнения с брендом/макетом.	Интерфейс менялся итерационно: сначала Keyso-подход, потом красный акцент под Gvozd.
API “Прикрепил api keyso... а gvozd.org надо адаптировать”.	Нужно было понять, где реальный API, где заглушки, и что можно подключить честно.	Появился документ по интеграциям, Keyso adapter и исследование Setips workflow.
Setips “Он писал, что там 2 эндпоинта...”	Контракт Setips был неочевидным: запуск и polling нужно было сверить с тем, что говорил Кирилл.	Интеграция стала работать через запуск workflow и опрос статуса, а спорные места вынесены в вопросы к поставщику API.
Стабилизация “Попробуй по одной посылать... polling 20 минут”.	При пачечном запуске Setips часть сайтов зависала, прогресс был непонятен.	Подход изменён: один активный workflow, остальные в очереди; polling увеличен до 20 минут.
Метрики “Убери лишние метрики, которых нет в Setips”.	Заказчик/поставщик API указал риск фиктивных данных и непонятного расхода кредитов.	Метрики сверялись с реальными payloads, неподтверждённые поля удалялись.

5. Подробная хронология по прошлым чатам

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

Этап общения	Что я отправлял / уточнял	Как ИИ реагировал	Что изменилось в работе
Старт проекта	Передал заказ: Laravel + Vue, 10-500 сайтов, Keyso, gvozd.org, сводная таблица, графики среднего и медианы ИКС.	Предложил делать фундамент: backend-модель, миграции, роли, API-каркас, интеграционный слой и логи.	Работа началась не с UI, а с основы данных и backend-архитектуры.
Контрольная точка 2	Уточнил, что нужна именно “серверная часть MVP с авторизацией и админкой”, и дал Figma-ссылки.	Сфокусировался на Laravel MVP: auth, roles, admin CRUD, endpoints для будущего фронта.	Появился файл `docs/checkpoint-2-architecture.md` с границами этапа.
Уточнения заказчика	Передал ответы: пользователь видит все ниши, но выбирает одну; сайты/ниши заводит админ; тарифов нет.	Собрал рабочее MVP: регистрация, роли, выбор ниши, админское управление и ручное обновление данных.	ТЗ стало конкретным: без оплаты, без пользовательского добавления сайтов, с одной активной нишей.
Правка курса	Остановил неверную верстку: заказчику нужна рекламная страница, регистрация и закрытый кабинет.	Вернул фокус на сценарий заказчика и отделил лендинг от кабинета.	ИИ был скорректирован по продуктовой логике, а не только по стилю.
План этапов	Сформулировал этапы: проектирование, backend, интеграции, сбор данных, логирование ошибок и лимитов.	Принял план и пошёл до второй контрольной точки без лишней фронтовой доработки.	Работа стала измеряться контрольными точками, а не общим “сделать проект”.
API Keyso и Gvozd	Прикрепил OpenAPI Keyso и уточнил, есть ли у gvozd.org реальный API или только слой в проекте.	Проверил код, OpenAPI, адаптеры и отделил реальные endpoints от заглушек.	Появился документ `docs/provider-integrations.md` и нормальный слой провайдеров.
Setips	Передал сообщения Кирилла: API работает на setips.com, токен из local storage, “по сути 2 endpoint”.	Сверил запуск аудита и polling workflow, выделил вопросы к поставщику API.	Интеграция стала строиться вокруг workflow: создать аудит, опрашивать статус, сохранять результат.
План дожима	Зафиксировал 3 итерации: стабилизация ядра, полировка UI, интеграции и данные.	Начал с очередей, статусов, ошибок, автообновления и UX, а Keyso отложил до ключей.	Появился реалистичный план завершения без попытки чинить всё одновременно.
Production-проверка	После деплоя указал: прошёл только 1 сайт, Setips зависает, нужно слать сайты по одному.	Изменил архитектуру: один активный workflow, остальные в очереди, polling 20 минут.	ТЗ уточнилось по реальной эксплуатации: важны очередь, статусы и понятная ошибка.
Метрики	Потребовал убрать лишние метрики, которых нет в Setips, и свериться по реальным логам.	Сравнил definitions с raw payloads и убрал неподтверждённые значения.	Отчёты стали честнее: меньше полей, но каждое связано с реальным источником.

Итерация метрик: реальные payloads Setips и кабинет — Картинка 3. Отдельная итерация по метрикам: неподтверждённые поля убраны, оставлены показатели из реальных payloads.

6. Как корректировки превращались в разработку

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

Корректировка	Визуальный / технический результат	Где видно в проекте
Пользователь выбирает только одну нишу	В кабинете появился выбор активной ниши и сводка только по этой нише.	Кабинет пользователя, блок “Активная ниша”.
Сайты и ниши заводит админ	В админке появились создание сайта, массовый импорт доменов и выбор провайдеров.	Админка, вкладка “Сайты”.
Нужно видеть падения API	Добавлена вкладка операций с provider runs, статусами и текстом ошибки по каждому сайту.	Админка, вкладка “Операции”.
Setips зависает, слать по одному	Добавлена последовательная очередь: один активный workflow, остальные ждут.	`app/Actions/DispatchNextGvozdRun.php`.
Polling 20 минут	Настроено окно ожидания Setips workflow и завершение зависших запусков с понятной ошибкой.	`config/services.php`, `gvozd:poll`.

Было стало: сайты и операции в админке — Картинка 4. Была админка для сайтов и импорта; после production-проверок появилась зона операций со статусами и ошибками Setips.

7. План дожима, который появился после проверки

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

Итерация 1

Стабилизация ядра. Статусы refresh/provider runs, понятные ошибки, прогресс X/Y, очередь, timeout, retry и финальный reconcile.

Итерация 2

Полировка интерфейса. Консистентная белая тема, фоновые обновления, стабильные графики, удобные таблицы и состояния.

Итерация 3

Интеграции и данные. Дожать Keyso после ключей, сверить Setips, убрать фиктивные метрики, проверить лимиты и ошибки API.

Setips проблема и инженерная правка — Картинка 5. Пример именно разработки: симптом в админке привёл к изменению конфигурации, очереди и polling-логики.

8. Что можно показать новому заказчику

Как я работаю

сначала вытаскиваю из общего описания конкретное MVP;
задаю уточняющие вопросы по ролям, данным, доступам и границам этапа;
разбиваю работу на контрольные точки;
использую ИИ для ускорения реализации и анализа;
проверяю результат и корректирую ИИ, если он уходит не туда.

Как это сформулировать

“Я не просто генерирую код через ИИ. Я веду процесс: разбираю ТЗ, согласовываю этапы, задаю вопросы заказчику, направляю ИИ, проверяю результат, исправляю подход и довожу проект до рабочего состояния”.

Отчёт основан на прошлых чатах Codex по этому проекту. Доступы, токены, IP, приватные контакты и технические секреты намеренно удалены.

9. Артефакты, которые подтверждают процесс

Артефакт	Что подтверждает
`docs/checkpoint-2-architecture.md`	Контрольную точку backend MVP: роли, сущности, доступы, API и acceptance criteria.
`docs/provider-integrations.md`	Исследование Keyso и Gvozd/Setips, endpoint-логику, env-настройки и карту метрик.
`app/Actions/DispatchNextGvozdRun.php`	Изменение подхода после реальной проблемы: последовательная очередь Setips.
`app/Console/Commands/PollGvozdWorkflowsCommand.php`	Polling workflow, обработку зависаний и финализацию статусов.
`resources/js/components/AdminPage.vue` и `CabinetPage.vue`	Админку, кабинет, операции, сравнения, метрики и пользовательский сценарий.