Spec-driven development глазами архитектора: понятные спецификации

Эпиграф

«Систему, которую не понимают, нельзя безопасно развивать»

Meintjes, Rengaswamy, Katsande, Bikki, InfoQ, 2026

В этой статье я, Алексей Соболеков, архитектор решений, разберу зачем и как в агентской разработке формировать понятные спецификации. Ранее я разобрал Роль Solution Architect с приходом AI-агентов: что изменилось в 2026 году

Главное

• При работе с агентами я часто вижу две крайности: спецификации, перегруженные деталями, и описания, оторванные от контекста системы. И те и другие мешают человеку понять решение.

• Я рассматриваю понятность системы как архитектурную характеристику наряду с производительностью и надежностью: без нее систему нельзя безопасно развивать.

• Основа всех спецификаций системы — актуальные архитектурные документы, понятные человеку и агенту. На них ссылаются, а не пересказывают; решения уточняют по ходу реализации.

• Владение документами разделено по ролям: бизнес-требования готовит аналитик, знающий потребности заказчика; техническое решение — разработчик, знающий систему.

• Хорошая спецификация кратка: ревьюер понимает ее без автора, ключевые тезисы выделены, есть визуальные схемы, а агент получает необходимый контекст из текста и ссылок. Ее генерирует агент, но ответственность остается у человека.

1. Отрасль перешла к SDD

Спецификации научились генерировать. Кто их читает и кто за них отвечает — вопрос открытый.

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

Но SDD «из коробки» не гарантирует успеха. У подходов вроде OpenSpec, Spec Kit и Superpowers есть методологические проблемы:

Kent Beck · январь 2026

Описания SDD требуют написать всю спецификацию до реализации. Это предполагает, что в реализации команда ничему не научится.

Источник, LinkedIn

Addy Osmani · Anthropic / Google январь 2026

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

Источник, addyosmani.com

Markus Eisele · O’Reilly Radar · июль 2026

Спецификацию тоже нужно ревьюить. Запрос агенту «напиши требования» обычно дает «отполированный туман».

Источник, The Right Amount of Spec for Agentic Development

2. Крайность первая: множество файлов для агента

Агент выпускает документы для другого агента, но автор и ревьюер не получают понимания решения.

Возьмем Superpowers: процесс из семи этапов, на каждом агент генерирует отдельные документы или проверки:

Рисунок 1. Семь этапов Superpowers: на каждом агент выпускает документ или проверку.

Вряд ли автор сможет объяснить решение. Документ написал агент, человек его только принял. Это вайб-кодинг, оформленный .md-файлами.

3. Крайность вторая: узкое описание без контекста системы

Техническую часть пишет человек, не знакомый с кодом и данными системы. Документ расходится с реализацией.

Рисунок 2. Цикл классической технической постановки: версия → ревью → возврат.

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

А потом агент заполняет пробелы догадками.

Martin Fowler · июль 2026

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

Пересказ, Fragments: July 21

Вырожденный случай — вайб-кодинг с планом и протоколом сессии. Шаги видны. Требуемое поведение и причины решения — нет. Отладка и развитие такого решения равносильны повторному проектированию.

Причина второй крайности — автор системной части. Ее должен писать тот, кто знает систему, — разработчик.

4. Понятность как архитектурная характеристика

Архитектура — это «фундаментальные концепции или свойства системы в окружающей среде, воплощенные в ее элементах, отношениях между ними, а также в принципах ее проектирования и развития». ГОСТ Р 57100 / ISO/IEC/IEEE 42010.

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

И тут надо учитывать «аппаратное» ограничение человеческого мозга:

«Емкость центрального хранилища рабочей памяти у взрослых людей ограничена тремя-пятью смысловыми единицами». «The Magical Mystery Four: How is Working Memory Capacity Limited, and Why?» Nelson Cowan, 2010

Рисунок 3. Понимание и число смысловых единиц в документе.

Документ должен кратко и полно передавать понимание системы читателю без пояснений автора. Без пояснений — потому что читатель может быть и человеком, и агентом.

Когда команда сама проектирует и пишет код, понимание формируется в работе и в головах. Генерация агентом кода сокращает этот этап, но теперь понимание нужно описывать в документах и проводить их ревью, по аналогии с кодом. Иначе накапливается когнитивный долг.

Margaret-Anne Storey в 2026 году разложила здоровье системы на три долга.

Рисунок 4. Три долга системы и чем их снижает понятный формат.

Сигналы потери понимания:

• merge request слишком велик для осмысленного ревью;

• ревью сводится к «LGTM» (Looks Good To Me — «выглядит нормально») или держится на одном человеке;

• агент — единственный ревьюер;

• граница системы меняется без архитектурного решения;

• изменение ломает несвязанную область.

5. Архитектура: очерчивает границы и уменьшает размер изменений

Архитектура, сформированная вначале в виде HLD/LLD-схем и набора ADR (Architecture Decision Record), позволяет декомпозировать сложные требования на последовательные простые компоненты и взаимодействия между ними, задает технические ограничения.

Спецификации ссылаются на актуальную архитектуру, не пересказывают ее и не нарушают границ.

Чтобы избежать водопада, ограничивайте изменение архитектурными границами.

Рисунок 5. Один документ на всю систему и спецификации по границам.

• Границы сервисов, владельцы данных и контракты позволяют специфицировать, проверить и выпустить изменение отдельно.

• Одна спецификация описывает изменение в пределах одной такой границы.

• Изменение самой границы — отдельное архитектурное решение. Оно тоже правится по обратной связи.

Martin Fowler советует резать работу с LLM на тонкие срезы. Маленькая спецификация без обратной связи остается мини-водопадом. Поэтому при изменении решения правится спецификация (раздел 5).

6. Читаемость: меньше нагрузки на ревьюера

Оформление должно помогать ревьюеру оценить решение.

Рисунок 6. Анатомия читаемого ADR.

Пирамида Минто и BLUF задают порядок: сначала вывод, затем обоснование.

Контекст сокращается до фактов и вопроса. История вопроса уходит в отдельный разбор.

Эти правила — для читаемых человеком ADR (Architecture decision record). Другие документы имеют другую структуру, но похожие принципы.

Краткость полезна обоим читателям, пока не теряется контекст.

Критерии понятной спецификации:

• небольшая и «красивая» — со схемами, структурой, таблицами, выделениями шрифтом и построением по пирамиде Минто;

• человек читает и понимает ее без автора;

• ревьюер может проверить обоснованность решений (трассировка);

• агент без истории диалога получает необходимый контекст из текста и ссылок;

• агент ее генерирует и правит, а автор объясняет своими словами.

7. Итог

Понятная спецификация — это та, за которую автор и ревьюер готовы взять на себя ответственность. У агента ответственности нет.

Формат не доказывает, что автор понял решение. Это проверяет устная защита изменения своими словами. Не объяснил своими словами — не принято. Описание merge request автор тоже пишет сам, без генерации.

Проверки для любого документа изменения:

1. Второй человек читает и понимает его за разумное время.

2. Ссылки открываются и ведут на актуальные документы.

3. Автор объясняет решение своими словами.

4. Спецификации разделены на бизнес-требования и техническое решение.

5. Спецификация описывает поведение и решение, ссылается на архитектуру и не дублирует код.