Как доверять ИИ-агенту: Spec Generator и проверка задач
Суть: Spec Generator связывает требования, дизайн, задачи и фактические результаты тестов в один граф, чтобы после AI-агента оставался проверяемый след, а не только код и ответ «готово».
Spec Generator
Как
доверять
ИИ-агенту
Коротко
- Проверка работы ИИ-агента съедает время и концентрацию: он нередко понимает задачу неправильно, делает только часть и не проверяет результат перед уверенным «готово». Даже подробный план, список задач и режим Goal сами по себе от этого не спасают.
- Вместо самой работы вы пишете десятки наводящих промптов: «проверь», «доделай», «ты пропустил условие», «запусти тесты». Если вам тоже надоело постоянно быть надзирателем для агента — вы не одиноки.
- Spec Generator превращает исходный промпт в цепочку: проблема → сценарий → требование → дизайн → приёмка → проверка → задача → результат. Так агент видит весь объём работы и не держит его по памяти одного чата.
- Вы заранее задаёте, чем подтвердить результат: тестом, ревью, инспекцией, браузерным сценарием, MP4 с работой фичи или другим конкретным пруфом.
- MCP-инструменты, скилы и хук проводят агента по этой системе. Если работа неполная или пруфа нет, хук не принимает «готово» и прямо сообщает агенту, что ещё нужно сделать и проверить.
- В результате один раз описанную через Spec Generator фичу можно отдать агенту и переключиться на другую задачу, вместо того чтобы постоянно следить за каждым шагом. Современные агенты уже достаточно умны для сложной работы, но часто невнимательны: пропускают условия, не проверяют себя и слишком рано останавливаются.
- Spec Generator замыкает агента в рабочую петлю: реализация → проверка → обратная связь → доработка. Это не отменяет человеческую приёмку, но уменьшает количество ручных напоминаний и экономит время и концентрацию.
Создание спецификации
Как из промпта создаётся спека
Главное: вы описываете фичу или баг обычным промптом, а Spec Generator превращает запрос в согласованную систему требований, критериев приёмки, дизайна, проверок и задач. Перед переходом к коду человек подтверждает смысл задачи, ограничения и способ проверки результата.
Из вашего промпта он выясняет, кто будет пользоваться фичей, что должно происходить, какие есть исключения и что пока неизвестно.
Механизм принуждения, а не хорошая воля
Проблема: без формальных полей агент может записать красивую, но бесполезную историю задачи.
Что блокирует запись: USER_STORIES.md не принимается без приоритета P1/P2/P3, причины Why, независимой проверки и acceptance-сценариев. Отказ приходит как список недостающих полей (user-story guard).
Что блокирует риски: если секция RESEARCH.md уже начата, две пустые строки рисков не пройдут. Нужны Likelihood, Impact и Mitigation (risk guard).
Что блокирует переход дальше: перед следующей фазой STOP ищет незаполненные плейсхолдеры и битые ссылки. Если в RESEARCH.md написано PoC Required: yes, Discovery не подтверждается без пруфа и оценки стоимости (spec-status -ConfirmStop).
Он находит связанные файлы, другие спеки, уже существующую реализацию, действующие правила, зависимости и команды проверок. Поэтому новая фича не проектируется в отрыве от того, что уже описано и работает в проекте.
Порядок не случайный: сценарий показывает, кто и как пользуется фичей; требование формулирует, что система должна делать; дизайн объясняет, как это устроено. Приёмка задаёт границу «принято / не принято», а проверка называет конкретное доказательство: тест, ревью, инспекцию, браузерный сценарий или другой пруф.
Она указывает порядок работы, нужные изменения и проверку для каждой задачи, а затем ищет пропущенные связи и незакрытые требования.
Он проходит до того, как технологии попадут в требования, дизайн и задачи.
Зачем нужна спека
Промпт не хранит весь контракт задачи
Проблема возникает, когда выполненная задача, требование и проверка существуют отдельно: зелёный тест подтверждает только свой сценарий, но не всю цепочку изменений.
- Непонятно, какой критерий приёмки подтверждает конкретный тест и относится ли его результат к текущей версии кода.
- Новая реализация может пересечься с уже существующей функцией, если её не сравнить с общим корпусом требований и решений. В workflow такое сравнение выполняет cross-spec reconcile перед финализацией.
- Инструкция может быть выполнена частично, а незакрытые шаги останутся только в чате или TODO.
- Зелёный тест может проходить через мок или побочный путь, не проверяя реальную границу системы.
Поэтому нужен не более длинный промпт, а проверяемый контракт между требованием, изменением и доказательством.
Содержимое спецификации
Что появляется в спеке
Результат — не один длинный документ, а связанный набор материалов: пользовательские сценарии, функциональные и нефункциональные требования, критерии приёмки, дизайн, изменения файлов, проверки и задачи на реализацию.
По умолчанию между Claude Code и папкой со спеками стоит MCP. Он собирает контекст, валидирует изменение и возвращает статус. Осознанный обход возможен, но требует явной причины и остаётся в журнале.
- payment-retry/
- USER_STORIES.md
- USE_CASES.md
- FR.md — поведение фичи
- NFR.md — ограничения
- ACCEPTANCE_CRITERIA.md
- DESIGN.md
- FILE_CHANGES.md
- payment-retry.feature
- TASKS.md
- CHANGELOG.md
- RESEARCH.md
- README.md
- REQUIREMENTS.md
- FIXTURES.md — при работе с данными
- *_SCHEMA.md — когда нужна схема
Что под капотом / условный пример
Как документы связываются между собой
Плагин читает заранее заданные ссылки, теги и идентификаторы в Markdown и Gherkin. По ним он строит проверяемую цепочку от требования до результата запуска. Все пути и номера ниже вымышлены и нужны только для объяснения механики.
.specs/payment-retry/FR.md#fr-12Условный путь от корня репозитория. В FR.md записано требование FR-12: что должна делать фича..specs/payment-retry/DESIGN.md · FR-12Дизайн хранится отдельно от требований и приёмки. Он объясняет, как устроено решение, и явно ссылается на требование FR-12..specs/payment-retry/ACCEPTANCE_CRITERIA.md#ac-12-1Критерий AC-12.1 хранится отдельно и явной ссылкой указывает, какое условие подтверждает для FR-12. Он задаёт границу «принято / не принято»..specs/payment-retry/payment-retry.feature · @FR-12BDD-сценарий — описание наблюдаемого поведения — явно помечен тегом требования. Зелёный результат другого сценария не засчитывается вместо него..specs/payment-retry/TASKS.md · TASK-07Задача ссылается на FR-12 и содержит проверяемое условие завершения. Путь к изменяемому коду указывается отдельно и остаётся заявленной связью, а не доказательством корректности кода..specs/payment-retry/.test-results.ndjson · SPEC001_07После BDD-прогона сохраняются статус сценария, время и источник результата: прошёл, упал или не запускался. Это фактический результат проверки, а не фраза агента «всё готово».Быстрая проверка проводится перед созданием задач, а полный аудит — перед финализацией спеки. Быстрая проверка ищет пересечения файлов, модулей и runtime-идентификаторов: адресов API, переменных окружения и CLI-флагов. В отдельном полном аудите система сравнивает по смыслу только отобранные пары требований и критериев приёмки. Для находки уровня CRITICAL человек выбирает одно из трёх действий: исправить конфликт, записать обоснованное исключение или остановить финализацию. Предупреждение само по себе работу не блокирует (как работает проверка между спеками).
get_trace.Для всей спеки агент получает рабочую картину: что уже подтверждено, что не запускалось, где оборвана связь и какой шаг нужно выполнить дальше. Это возвращает
get_spec_status.Если агент слишком рано пытается поставить задаче статус «готово»,
set_entity_status не просто отказывает: он возвращает причину и список недостающих частей. Агент может исправить разрыв, запустить проверку и повторить попытку без очередного напоминания человека. Финальная приёмка остаётся за человеком.read_spec_doc · search · get_traceconformance_check · get_spec_statuspropose_patch · apply_proposed_patch · apply_spec_transactioncreate_spec · set_entity_status · archive_specСначала выясняем, что вообще делаем
Из короткой хотелки генератор выясняет, кто пользователь, какую проблему он решает и как выглядит нормальный рабочий сценарий. Для каждого ожидания фиксируются приоритет, причина и независимый способ проверки. Отдельно записываются риски и неизвестные, которые нужно исследовать.
После разбора задачи агент показывает краткое резюме решений и ждёт подтверждения человека. Перескочить из размытой идеи сразу в код нельзя.
- Кто пользователь
- Зачем ему фича
- Как проверить независимо
- Какие риски и редкие случаи
Map 02 / трассировка требования
Как требование связано с кодом и проверкой
Каждая связь в спеке явная: требование указывает на дизайн и приёмку, проверка помечена тегом требования, задача ссылается на требование. Поэтому видно полный путь от проблемы к результату.
Контекст проекта собирается до дизайна
Агент читает правила проекта, зависимости, существующий код и настройки запуска тестов. Сначала он выясняет, как проверки уже устроены в этом репозитории, и только потом проектирует новые.
Для нового проекта отдельно выбирается архитектура. Названия технологий не успевают случайно расползтись по требованиям и задачам до принятия решения.
- Активные правила проекта
- Реальные файлы и зависимости
- Как запускаются и очищаются тесты
- Ограничения существующей архитектуры
Старая фича не теряется в переписке
Каждое требование связывается со сценарием использования, условием приёмки, дизайном, проверкой, задачей и фактическим результатом. По этой цепочке можно пройти в обе стороны — если в документах стоят явные ссылки. Пропущенная ссылка становится видимым разрывом, а не заполняется догадкой агента.
- Зачем → что требуется
- Требование → как принимаем
- Проверка → что реализовать
- Задача → фактический результат
Проверка проектируется раньше реализации
Генератор фиксирует поведение фичи, ограничения, условия приёмки, дизайн, изменяемые файлы и сценарии проверки. Если тест создаёт данные, заранее описывается, как их подготовить и гарантированно удалить после запуска.
- Сначала проверяемое поведение, потом код
- Одна таблица для всех вариантов
- Очистка тестовых данных после запуска
- Конфликт с соседней фичей виден до кода
Если подходящего инструмента для таких проверок ещё нет, его установка становится первой инфраструктурной задачей, а не вечным оправданием «у нас это не тестируется».
Чекбокс DONE не делает задачу готовой
Статус выводится из результатов проверок. Задаче нужен успешный результат именно её сценариев: зелёный тест соседней задачи не подходит, а незапущенная проверка не превращается в успешную.
- Проверка комплекта файлов — только первый шаг
- Итог собирается по всей цепочке
- Все сценарии, а не «хотя бы один»
- Красный статус обязан назвать разрывы
Готовность спеки — не мнение агента. Итоговый гейт проверяет структуру, явные связи, реальные запуски, правду статусов задач, синхронность сценариев и смысловые противоречия.
Map 03 / против ложного «готово»
Какие проверки формируют итоговый статус
Красиво заполненные документы ещё не подтверждают готовность. get_spec_status собирает применимые проверки и показывает либо подтверждённое состояние, либо конкретные разрывы.
И ПРОБЕЛЫ
Правки спецификации проверяются до записи
Через MCP агент может предложить правку одного раздела, заменить документ целиком или атомарно изменить несколько документов. Сначала сервер проверяет форму и связи. При чтении для редактирования он выдаёт контрольный хеш версии; параметр expected_sha не даёт перезаписать более свежую правку другого участника.
- Если правка не проходит проверку формы и связей, MCP отказывает до записи файла
- Многодокументная правка применяется целиком или не применяется
- Переданный хеш не даёт затереть более свежую версию
- В автоматическом запуске оркестратора каждую фазу может выполнять свежая сессия агента
- Сомнение помечается, но не выдаётся за приговор
Map 04 / техническое ограничение
Как MCP-инструменты проводят агента по спеке
Проблема: если агент может свободно править спеку обычными файловыми инструментами, он обойдёт все проверки и скажет «готово» над битыми ссылками. Что блокируется: прямая запись в папку .specs — правка, создание файла, скриптовая замена текста или перенаправление вывода. Что остаётся: безопасное чтение для поиска и навигации; само изменение проходит через контрольную дверь, где проверяются структура, связи и версия. Осознанный аварийный обход требует явной причины и записывается в журнал.
или объяснить отказ
Проверка результата
Как определяется статус «готово»
Главное: Spec Generator принимает не отчёт агента, а пруф из заданного вами условия приёмки: прошедший тест, ревью, инспекцию или MP4 с работой фичи. Не сошлось — хук вернёт задачу и прямо скажет агенту, чего не хватает.
с условием?
Хук перечислит, чего не хватает.
В графе останется проверяемый след.
Один пример целиком
Пример: повтор неуспешного платежа
Это упрощённый учебный пример. Фраза «добавь повтор оплаты через провайдера» выглядит маленькой. Но в ней уже спрятаны защита от повторного списания, лимит попыток, несколько провайдеров и восстановление после таймаута.
Именно на таких задачах длинный промпт быстро перестаёт быть страховкой.
Разбор задачи не даёт назвать повтор оплаты «одной кнопкой»
Появляются роли, успешный путь, отмена, ожидание ответа, повтор после неизвестного результата и отдельный риск повторного списания. Человек подтверждает, какие состояния считаются безопасными.
Контекст находит реальную платёжную инфраструктуру
Генератор видит существующую интеграцию с платёжным сервисом, формат идентификатора операции и способ создавать тестовые платежи. Новая схема не выдумывается параллельно старой.
Все варианты попадают в одну таблицу
Успех, ожидание ответа, окончательный отказ и повторный ответ раскладываются по провайдерам. Для каждого варианта заранее описываются ожидаемый результат, тестовые данные и их очистка.
Каждая задача получает собственное доказательство
Защиту от двойного списания нельзя закрыть зелёной проверкой интерфейса. Ей нужен свой сценарий и собственный успешный результат. Общая готовность фичи не маскирует недоделанную ветку.
Следующая сессия начинает не с нуля
Если через неделю меняется один провайдер, агент проходит от его сценариев к требованиям, файлам и соседним спекам. Контекст восстанавливается из графа, а не из случайно сохранившегося диалога.
Что изменилось
Что меняется в работе с агентом
Раньше финальным артефактом работы агента был код и убедительный ответ в чате. Теперь остаётся модель фичи, по которой следующая сессия видит старые решения, варианты, дизайн, тесты и известные разрывы.
Это не гарантирует идеальную архитектуру и не отменяет ревью. Но агенту намного сложнее забыть старую фичу, пропустить вариант, объявить незапущенный тест зелёным или закончить задачу без доказательств.
Граница текущей версии: подтверждение фаз фиксирует решение в процессе, но не доказывает личность подтвердившего. Обязательная независимая проверка другим агентом и отдельный гейт проверки живой системы пока остаются открытыми задачами.
Почему не приходится переспрашивать
Как хук возвращает незавершённую работу
Обычная поломка выглядит так: агент останавливается на «сделал», хотя часть работы ещё открыта. В чате это читается как готовый результат, приходится переспрашивать по каждой задаче отдельно — а незакрытое всплывает через неделю как подводный камень: реализовано и проверено не то, что задумывалось.
Поэтому закрытие хода проходит через два разных слоя. Первый — перепись задач: она отдельно считает открытые (todo, in-progress, blocked) и «готовые с красным» — те, что помечены DONE, но у них хотя бы один сценарий упал, не определён или неоднозначен. Итог кладётся в кэш .dev-pomogator/.task-census.json, и следующий запрос начинается с напоминания, что именно осталось.
Второй — Stop-хук, который перехватывает саму попытку завершить ход. Заявил результат без улики — хук возвращает решение «блокировать» с причиной, и агент продолжает работу вместо финального отчёта. В реестре хуков он стоит на событии остановки с таймаутом 60 секунд.
Граница текущей версии: хук ошибается в обе стороны, и оба случая разобраны в репозитории. Один раз он не пнул преждевременный стоп, потому что читал отстающий кэш переписи. В другой раз заблокировал закрытие шесть раз подряд на зонтичной задаче. Припаркованную спеку из переписи можно исключить явно — тогда её открытые задачи перестают считаться работой на сейчас.
Исходники и контекст проекта
Где смотреть Spec Generator и большую картину
Фазы работы, контроль правок, карту требований и MCP-инструментов можно проверить в открытом репозитории Dev Pomogator без пересказа.
Ai Помогатор — медиа и продукт вокруг этой практики: aipomogator.ru и Telegram-канал @ii_pomogator. Здесь я показываю, как мы сами строим и проверяем работу с ИИ-агентами.
Языки и тесты · что реально подключено
Сейчас рабочий путь подтверждён только для Cucumber.js
Spec Generator берёт результаты из файла, который создаёт Cucumber.js в этом репозитории, и связывает каждый сценарий с требованиями. Это единственный путь, который сейчас подключён к рабочему сборщику графа (production builder).
Что работает сейчас
TypeScript / JavaScript + Cucumber.js. Отчёт Cucumber.js проходит через основной сборщик, а результаты сценариев попадают в граф требований. Это подтверждено реальным примером результата и рабочим parser (источник данных).
Что умеет только запускаться
Общий runner может запустить Vitest, Jest, обычный pytest, dotnet test, cargo test и go test. Но их обычный вывод сейчас не связывается с требованиями и не влияет на итоговый статус Spec Generator (test runner).
Частые вопросы · FAQPage
Что важно знать о Spec Generator
Что именно проверяет Spec Generator?
Он проверяет связи между проблемой, требованием, критерием приёмки, задачей, сценарием и свежим результатом теста, а не только наличие файлов или обещание агента.
Чем это отличается от набора Markdown-файлов?
Документы разбираются в граф: система находит незакрытые требования, осиротевшие задачи и сценарии без трассировки. Правила и MCP-дверь описаны в дисциплине Spec Generator.
Достаточно ли зелёного теста для статуса «готово»?
Нет. Нужны связь с критерием приёмки, актуальный результат и доказательство реальной границы системы; открытая задача live-верификации зафиксирована в issue #157.
Какие ограничения остаются?
Обязательный независимый adversarial review и отдельная live-проверка ещё развиваются; их текущее состояние открыто описано в issue #153 и issue #157.
