Почему API‑First уже недостаточно и что меняется, когда SDD строится на.md‑файлах и обязательном участии агентов?
В агентном SDD спецификация становится не пояснением к коду, а рабочим контекстом, из которого агент строит план, тесты и реализацию. Это ускоряет разработку — и одновременно увеличивает цену неоднозначности. Разбираем, как превратить.md из документации в управляемый контракт.
Мы привыкли объяснять неудачный результат агента «галлюцинациями модели». В агентном SDD причина часто прозаичнее: агент получил неполную, противоречивую или слишком свободную спецификацию — и последовательно реализовал одну из возможных трактовок. Чем лучше агент исполняет инструкции, тем быстрее такая ошибка распространяется по коду, тестам и документации.
API‑First решил только часть проблемы
API‑First научил команды договариваться об интерфейсе до начала разработки. OpenAPI фиксирует операции, параметры, схемы данных и ошибки. Потребитель может построить mock, поставщик — проверить совместимость и сгенерировать часть обвязки.
Но корректный контракт интерфейса ещё не означает корректное решение. В нём обычно нет ответа, зачем существует операция, какой результат считается успешным для бизнеса, какие инварианты нельзя нарушать и что должно произойти при частичном отказе.
Риск
Команда может идеально реализовать API‑контракт и при этом нарушить смысл операции: неверно выбрать владельца статуса, допустить повторное списание или потерять событие после фиксации транзакции.
В нашей модели.md и агенты — обязательные условия
Под SDD здесь понимается не любое «сначала требования, потом код». Целевая модель строится на двух обязательных условиях: спецификации хранятся в Markdown, а AI‑агенты участвуют в анализе, планировании, реализации и проверке изменений.
Это меняет роль документа. Файл specification.md одновременно читают аналитик, архитектор, менеджер и агент. Для людей он должен сохранять контекст и объяснять решения. Для агента — задавать достаточно точные правила, чтобы из них можно было построить план работ и проверить результат.
«Спецификация становится интерфейсом между человеческим намерением и машинным исполнением.»
Markdown удобен именно как нейтральный носитель: он хранится рядом с кодом, версионируется через Git, проходит review и не привязывает процесс к одному инструменту. В него можно включать таблицы, ссылки, примеры, Mermaid‑диаграммы и структурированные блоки требований.
Конфликт
Документ должен быть одновременно удобен человеку и однозначен для агента. Чем сильнее текст оптимизируется под машину, тем труднее содержательный контроль со стороны бизнеса; чем свободнее он написан для людей, тем больше пространство трактовок.
Почему обычный Markdown ещё не является спецификацией?
Сам формат.md не создаёт управляемости. Репозиторий можно быстро наполнить сотнями файлов, которые устаревают, дублируют друг друга и не имеют понятного приоритета. В этом случае агент получает много контекста, но не получает источник истины.
Рабочая спецификация должна отвечать как минимум на семь вопросов:
Какую бизнес‑проблему решает изменение и для кого?
Какие сценарии входят в охват, а какие явно исключены?
Какие инварианты и ограничения нельзя нарушать?
Какие API, события, данные и системы затрагиваются?
Как должны обрабатываться ошибки, повторы и частичные отказы?
По каким критериям человек и агент признают результат готовым?
Какие файлы разрешено изменять и какие решения требуют отдельного согласования?
Агент масштабирует качество спецификации — и её дефекты
Разработчик, встретив двусмысленность, может остановиться и спросить аналитика. Агент чаще выбирает наиболее правдоподобную трактовку в доступном контексте. После этого он способен согласованно изменить десятки файлов, создать тесты под выбранную трактовку и обновить документацию.
Результат выглядит аккуратно и внутренне непротиворечиво. Именно поэтому ошибка смысла обнаруживается поздно: не как синтаксический дефект, а как несовпадение с реальным бизнес‑намерением.
Риск
Агент может не просто написать неверный код, а создать согласованный набор неверных артефактов: план, реализацию, тесты, миграцию и описание API. Такой пакет сложнее оспорить на ревью, потому что формально он выглядит завершённым.
Нужна иерархия источников истины
В крупной организации агент одновременно видит корпоративные стандарты, архитектурные решения, спецификацию процесса, локальный spec.md, OpenAPI и существующий код. Эти источники неизбежно расходятся. Поэтому недостаточно просто предоставить документы — нужно явно указать их приоритет.
Практическое правило: нижележащий артефакт конкретизирует вышележащий, но не может молча ему противоречить. Если локальная спецификация требует отступить от системного инварианта, агент обязан остановить реализацию и сформировать вопрос или запрос на исключение.
Конфликт
Старый код часто расходится с новой спецификацией. Если признать код источником истины, SDD не изменит систему. Если всегда считать спецификацию главнее, можно сломать фактические зависимости. Нужен явный процесс миграции, а не автоматический выбор стороны.
Не каждому изменению нужна одинаковая глубина
Попытка подробно специфицировать всё создаёт новый комитет предварительного согласования. Команды начинают считать.md бюрократией, обходить процесс и писать документы после кода. Поэтому глубина спецификации должна зависеть от цены ошибки.
Для справочного API достаточно контракта, владельца и базовых политик. Для внутреннего API с клиентскими данными понадобятся модель авторизации, SLA и контрактные тесты. Для финансовой операции — инварианты, идемпотентность, сценарии частичного отказа, аудит и миграционный план.
«Фиксировать до разработки нужно прежде всего то, ошибка в чём будет дорого стоить после разработки.»
Кто отвечает за спецификацию?
У спецификации может быть несколько авторов, но должен быть один владелец. Аналитик отвечает за бизнес‑сценарий, архитектор — за системные ограничения, разработчик — за реализуемость, безопасность — за обязательные политики. Владелец спецификации отвечает за целостность и разрешение конфликтов между этими слоями.
Агент не снимает эту ответственность. Он может найти противоречия, сформировать вопросы, предложить варианты и проверить покрытие требований. Но принять риск, выбрать компромисс или разрешить обратно несовместимое изменение должен человек с соответствующими полномочиями.
Риск
Если владелец не определён, агент будет работать с последней доступной версией текста, а организационный конфликт превратится в техническое решение по умолчанию.
Что меняется для API Management?
В агентном SDD API Management начинается не на шлюзе и даже не с публикации OpenAPI. Он начинается в момент изменения спецификации. Объектом управления становится весь путь от намерения до production:
структура и обязательные разделы.md‑спецификации;
связи с OpenAPI, AsyncAPI, данными и архитектурными решениями;
автоматический поиск неоднозначностей и противоречий;
проверка обратной совместимости и организационных политик;
ограничение области изменений для агента;
сопоставление реализации и production‑поведения с утверждённой версией спецификации.
Шлюз остаётся важным runtime‑компонентом, но главный управляемый объект теперь — изменение контракта и контекста, из которого агент строит систему.
Минимальный набор правил для старта
Определить единый шаблон spec.md, но оставить в нём только действительно используемые разделы.
Зафиксировать иерархию источников и правило обработки противоречий.
Разделить обязательные требования, пояснения и примеры.
Ограничивать контекст и область файлов, которые агент вправе менять.
Запускать clarify/analyze до implement, а не после первой неудачной генерации.
Связать acceptance criteria с автоматическими тестами и policy checks.
Назначить владельца спецификации и критерии человеческого подтверждения.
Вместо вывода
API‑First научил команды сначала договариваться об интерфейсе. Агентный SDD делает следующий шаг: сначала формализовать намерение и ограничения, затем передать их агенту как рабочий контекст и доказать соответствие результата.
Но скорость агента не компенсирует недостаток смысла. Она лишь быстрее показывает качество организационных договорённостей — или быстрее масштабирует их отсутствие.
«В агентной разработке плохая спецификация — это не слабая документация. Это исполняемая ошибка.»