ИИ способен написать функцию по короткому описанию, но в большом проекте одного описания недостаточно. Чем меньше требований зафиксировано заранее, тем больше решений агент принимает самостоятельно.
Спецификация задаёт правила для ИИ-разработки
Большая часть требований к системе не помещается в формулировку отдельной задачи. Они скрыты в бизнес-правилах, структуре данных, договорённостях между компонентами, документации внешних сервисов и критериях приёмки.
Представим систему учёта заявок. Агент может сам определить статусы, права пользователей, структуру данных и API. Но из запроса он не узнает, можно ли удалить завершённую заявку, кто назначает исполнителя, нужно ли хранить историю изменений и может ли сотрудник одной организации видеть данные другой.
Если эти правила не заданы, агент выбирает один из возможных вариантов.
Specification-Driven Development, или SDD, строит процесс иначе. Команда сначала фиксирует требования и ограничения, а затем использует их при реализации и проверке результата.
Спецификация при этом не обязана быть одним документом. Она может состоять из нескольких материалов: бизнес-правил, модели предметной области, контрактов API, документации интеграций и критериев приёмки.
Бизнес-правила нужно формулировать явно
Техническое задание часто описывает основной пользовательский сценарий.
Например:
«Пользователь загружает документ и отправляет его сотруднику на подпись».
Для реализации этого недостаточно. Нужно определить, можно ли отправить один документ нескольким сотрудникам, заменить файл после отправки, отменить операцию или создать несколько документов одного типа для одного человека.
Для заказчика часть ответов может подразумеваться. Разработчик узнаёт их из общения и опыта работы с проектом. У агента такого контекста нет, пока его не добавили в задачу или документацию.
Поэтому бизнес-правила стоит записывать как конкретные ограничения системы.
Например:
- подписанный документ нельзя заменить без создания новой версии;
- оплаченный заказ нельзя удалить;
- один платёж нельзя обработать дважды;
- пользователь получает данные только своей организации;
- переход между состояниями разрешён только при заданных условиях.
Такие правила задают допустимые состояния системы. Без них отдельные функции могут выполнять свои задачи, но вместе допускать сценарии, которых бизнес не предусматривает.
Модель данных и контракты уменьшают число догадок
После бизнес-правил нужно описать предметную область: какие сущности существуют, как они связаны и какие ограничения действуют между ними.
В системе заявок это могут быть пользователь, организация, заявка, комментарий, документ и уведомление. Заявка связана с автором и исполнителем, пользователь — с организацией, комментарий — с заявкой.
Это описание задаёт основу для таблиц, моделей и прикладной логики.
Следующий слой — взаимодействие компонентов.
Backend, web-интерфейс, мобильное приложение и фоновые процессы должны одинаково понимать структуру запросов, ответы, ошибки и допустимые значения.
Без общего контракта backend может вернуть поле user_id, а frontend ждать userId. Один компонент сочтёт отсутствие записи обычным результатом, другой — ошибкой.
Для API такие правила можно хранить в OpenAPI. Формат вторичен. Главное — чтобы все части системы опирались на один источник требований.
Это особенно актуально для ИИ-разработки, где разные задачи могут выполнять разные агенты. Зафиксированный контракт не позволяет каждому из них заново придумывать формат взаимодействия.
Для внешних сервисов нужен проверяемый источник
Интеграции требуют отдельного контекста.
Платёжные системы, службы доставки, телефония и другие сервисы меняют API. Знания модели могут относиться к другой версии документации или не содержать нужного метода.
Поэтому агенту стоит передавать документацию поставщика.
Небольшую документацию можно хранить вместе с проектом. Для большого объёма можно настроить поиск по разделам и передавать модели только материалы, связанные с текущей задачей.
Тогда агент отвечает не по памяти, а по источнику, который команда может проверить.
Этот принцип сокращает число выдуманных параметров, устаревших методов и несовпадений с текущей версией API.
Критерии приёмки определяют, когда задача закончена
Описание функций отвечает на вопрос, что должна делать система. Этого недостаточно, чтобы принять реализацию.
Нужны проверяемые критерии.
Часть из них превращается в тесты:
- пользователь одной организации не получает документы другой;
- повторный запрос не создаёт второй платёж;
- запрещённый переход состояния возвращает ошибку;
- удаление пользователя не нарушает правила хранения документов.
Другие критерии относятся к архитектуре. Команда может заранее определить способ проверки прав, обработки ошибок, работы с базой данных или взаимодействия между компонентами.
Отдельно фиксируются требования безопасности: какие данные считаются чувствительными, что нельзя записывать в журналы, где выполняется проверка доступа и какие сведения разрешено передавать внешним сервисам.
После этого агент получает конкретный критерий ошибки: не прошёл тест, нарушен API-контракт или не соблюдено архитектурное правило.
Такой контроль точнее формулировок вроде «переделай» или «сделай лучше».
ИИ можно использовать и для подготовки спецификации
SDD не требует писать всю документацию вручную.
Агент может разобрать исходное описание проекта, найти неоднозначности, составить вопросы заказчику, предложить модель данных, перечислить пограничные сценарии или подготовить черновик OpenAPI.
Он также может сопоставить несколько документов и найти противоречия между требованиями.
Но предложенный вариант не становится бизнес-правилом автоматически.
Если агент решил удалять документы вместе с учётной записью пользователя, это один из вариантов реализации. Решение о хранении документов должна принять команда.
Поэтому ИИ подходит для подготовки и проверки спецификаций, но утверждает требования человек.
Одного технического задания часто недостаточно
Техническое задание обычно описывает функции, которые увидит пользователь. При этом часть решений остаётся открытой.
Агенту всё равно придётся выбрать структуру данных, правила удаления, форматы API, способы обработки ошибок и ограничения доступа.
Если эти решения не согласованы, разные части системы могут опираться на разные предположения.
После изменения структуры данных приходится менять API. Затем — клиентскую часть и тесты. Одно исправление затрагивает несколько уже созданных компонентов.
Каждая такая итерация требует дополнительной работы и новых обращений к модели.
Спецификация сокращает число решений, которые приходится пересматривать после начала реализации.
Спецификация остаётся частью проекта после смены ИИ
Документация нужна не только агенту.
Описание предметной области помогает разработчику понять бизнес-логику. Схема данных объясняет устройство системы. OpenAPI связывает backend и frontend. Документация интеграций фиксирует работу со сторонними сервисами. Критерии приёмки определяют ожидаемое поведение.
Эти материалы сохраняют значение после смены модели, агента или инструментов разработки.
Проект не должен зависеть от того, какая нейросеть когда-то написала его код. Другой разработчик должен иметь возможность понять принятые решения и продолжить работу.
SDD сокращает число решений, которые ИИ принимает сам
Задача разработки на основе спецификаций — не создать как можно больше документации до первой строки кода.
Нужно заранее зафиксировать решения, изменение которых потребует переделывать несколько частей системы.
Перед реализацией стоит определить бизнес-правила, основные сущности и ограничения, контракты компонентов, источники данных для интеграций и критерии приёмки.
После этого агент получает не набор пожеланий, а систему требований, по которой можно писать и проверять код.
Чем меньше решений ему приходится принимать без заданных правил, тем меньше расхождений появляется между отдельными частями проекта.
