Зачем нужна спецификация

Требования, которых нет

В команде «Синтез» шесть инженеров, семь микросервисов и один общий способ работать с ИИ-агентами: каждый по-своему. Олег пишет агенту длинные промпты и держит их в заметках. Даша объясняет задачу голосом в чате, а потом копирует переписку в задачу. Настя, владелица общих библиотек, узнаёт о новых требованиях к Syn.Contracts, когда чужой сервис ломается на её пакете.

Общее у всех одно: требования нигде не записаны так, чтобы их мог прочитать и человек, и агент. Они размазаны по чатам, головам и истории диалогов. Когда агент «уверенно строит не то», виноват не агент — ему честно дали неявное знание и попросили явный результат.

Промпт — пунктир, спецификация — сплошная линия

На архитектурных схемах есть полезная конвенция: сплошная линия — явный контракт (API, схема сообщения), пунктир — неявное знание («все знают, что эти сервисы связаны»). Пунктир — это то, что ломается молча.

Промпт — пунктирная линия между вами и агентом. Он существует один раз, в одном чате, в одной голове. Его нельзя отревьюить, нельзя переиспользовать, нельзя предъявить через месяц на вопрос «а почему сделано так?».

Спецификация — та же самая информация, превращённая в сплошную линию:

• она лежит в git рядом с кодом — у неё есть история, автор и ревью;
• она написана до кода — команда договаривается о поведении, пока менять его дёшево;
• её читает агент — не как контекст одного чата, а как источник истины для любого следующего изменения.

Spec-driven development (SDD) — подход, при котором изменение системы начинается с короткой спецификации: что меняем, зачем, какие требования и сценарии должны стать правдой. Код — производная от спеки, а не наоборот.

«Это же waterfall»

Первое возражение Олега — и оно по делу: аналитики уже писали многостраничные ТЗ, которые устаревали до конца спринта.

Разница — в размере и цикле жизни. SDD в исполнении OpenSpec (инструмент разберём в части 2) работает не с «документом на проект», а с дельтой на одно изменение:

proposal ──► specs ──► design ──► tasks ──► реализация
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            уточняем по мере того, как узнаём новое

• proposal.md — зачем и что меняем: 15 строк, а не 15 страниц;
• specs/ — требования и сценарии в формате «GIVEN — WHEN — THEN»;
• design.md — техническое решение, если оно неочевидно;
• tasks.md — чек-лист реализации, по которому идёт агент.

Артефакты можно править в любой момент, в любом порядке — фазовых ворот нет. Узнали новое во время реализации — вернулись и поправили спеку. Waterfall запрещал возвращаться; SDD на этом построен.

А когда изменение готово, его дельта вливается в общие спеки системы — и у команды появляется то, чего у «Синтеза» не было никогда: актуальное описание того, как система ведёт себя сейчас. Не вики, которая врёт, а файлы в git, которые обновляются тем же процессом, что и код.

Что это даёт именно команде с агентами

Без агентов SDD был бы просто дисциплиной документирования — полезной, но дорогой. Агенты меняют экономику:

1. Спеку пишет агент, человек ревьюит. Стоимость создания упала на порядок; стоимость непроверенного кода осталась прежней. Выгодно сместить внимание человека с ревью кода на ревью намерения.
2. Спека — это контекст, который не протухает. Новый чат, другой агент, другая модель — источник истины тот же. Прекращается «у меня в том диалоге он всё понимал».
3. Ревью намерения дешевле ревью реализации. Поймать «не то поведение» в пяти строках сценария дешевле, чем в пятистах строках диффа.

Кейс «Синтез». Последний инцидент: агент Олега «починил» возврат платежа, разрешив рефанд в любом статусе заказа — в промпте про статусы не было ни слова, а в чате три недели назад было. Спецификация из шести строк со сценарием «GIVEN заказ отгружен WHEN запрошен рефанд THEN отказ» стоила бы две минуты ревью.

Что дальше

В части 2 поставим инструменты: Qwen Code CLI как агента и OpenSpec как каркас спецификаций — и посмотрим, что именно они генерируют в репозитории.