D3: Разработка, управляемая документацией

«Если фича не задокументирована — её не существует. Если она задокументирована неправильно — значит, она сломана».

Большинство команд пишут спецификации так же, как пишут тесты к легаси-коду: задним числом, для галочки. Настоящие проектные решения рождаются в переписке в Slack, в комментарии к макету в Figma, в чьей-то голове на стендапе. К тому моменту, когда что-то наконец доходит до бумаги, код уже написан, и документ оказывается лишь описанием сделанного — а не планом того, что предстоит сделать.

«Спецификация раньше кода» — идея не новая. Подходы вроде README-Driven Development (RDD — ввёл Том Престон-Вернер в 2010 году) и «документация прежде всего» существуют больше десяти лет, и все они упирались в одно и то же: написать полную и точную спецификацию вручную долго и скучно, поэтому команды этот шаг попросту пропускали. Дисциплина была правильной — не сходилась экономика.

Изменилось вот что: теперь бо́льшую часть этой дорогой работы берёт на себя LLM-агент — он читает кодовую базу, находит пробелы, расспрашивает команду, готовит черновик спецификации, а затем по ней же пишет код. Documentation Driven Development (D3) — это та самая старая дисциплина, ставшая дешёвой: команда готовит полную спецификацию до написания кода, а ИИ вплетён в каждый этап, а не только в финальное кодирование. В этом посте я разбираю весь процесс целиком на примере фичи, которую мы действительно так выпустили.

Если вы читали мой предыдущий пост Документация в эпоху ИИ, то D3 можно считать процессным продолжением той же мысли: если документация — это новый исходный код, то D3 — выстроенный вокруг неё процесс разработки.

Какую проблему мы решаем

Симптомы вы и так знаете: спецификации, размазанные по Slack, Figma и головам сотрудников; QA, который подключается уже после того, как код написан; ИИ, к которому обращаются при кодировании, но никогда — при планировании. Не буду на этом задерживаться.

Стоит запомнить лишь одно — про экономику. Неверное предположение, замеченное на этапе спецификации, стоит одного предложения; замеченное на код-ревью — целой ветки; замеченное в проде — инцидента. Чем дольше живёт недопонимание, тем дороже его исправлять, — поэтому самый выигрышный ход — перенести самые трудные размышления как можно ближе к началу. Раньше команды так не делали по простой причине: ранние, проработанные спецификации обходились слишком дорого. Ставка D3 в том, что ИИ изменил этот расклад.

Что такое D3?

D3 — это процесс, в котором команда готовит полную спецификацию фичи до написания кода. Вот что это даёт каждой стороне:

Для менеджмента Для разработчиков
Предсказуемые сроки — объём работ зафиксирован до начала кодирования Вы получаете финальный SRS ещё до того, как притронетесь к коду
Меньше переделок — QA планирует тесты заранее У Claude есть весь контекст — он генерирует и план, и код прямо из спецификации
Понятные точки передачи между Product, Engineering и QA Цикл ревью плана отлавливает ошибки проектирования до реализации
ИИ усиливает команду на каждом этапе, а не только при кодировании Никаких больше «а что Product вообще имел в виду?»

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

Сквозной процесс

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Product (идея → PRD → прототип)
        │
        ▼
Сбор требований  ←──────── Обратная связь
  [Аналитик/Technical Project manager + другие команды]
        │
        ▼
Черновик SRS ── Ревью (все стейкхолдеры + QA)
        │
        ▼
Финальный SRS (утверждён)  ───→  QA → Тест-план
        │                        (разработка идёт параллельно)
        ▼
ИИ генерирует спеки реализации (SRS × 3)
  UI SRS · Server SRS · Client SRS
  [ИИ-план ↔ ИИ-ревью → Ревью разработчика]
        │
        ▼
ИИ-код ↔ ИИ-ревью → Ревью разработчика
        │
        ▼
QA / VQA → PROD → Обратная связь

Пройдёмся по этапам.

Этап 1 — Идея и инициация

Ответственный: Product. Этот этап остаётся таким же, как в привычной работе большинства команд. Product берёт бизнес-потребность, запрос пользователя или стратегическую цель и превращает их в связку идея → PRD → прототип. Достаточно лёгкого PRD и/или прототипа — он напрямую питает этап сбора требований. В D3 меняется всё, что происходит после этого этапа.

Этап 2 — Сбор требований

Ответственный: Аналитик/Technical Project manager. Время: ~20 минут, с помощью ИИ.

Именно здесь ИИ впервые по-настоящему окупается. Процесс состоит из трёх шагов:

  1. Свести все источники в один файл .md — PRD, макеты, существующую документацию, API-контракты.
  2. Claude ищет пробелы — сверяет документацию с существующей кодовой базой, выявляет белые пятна и собирает список открытых вопросов.
  3. Claude расспрашивает команду — задаёт точечные вопросы, чтобы закрыть пробелы, и выдаёт чистовой черновик.

Важная деталь: Claude не строит догадки на основе одного лишь PRD. С помощью инструментов изучения кода и документации, а также Figma MCP он читает настоящую кодовую базу и сверяет требования с тем, что уже реализовано. Он знает, какие модули существуют, какие паттерны стоит переиспользовать и куда встроится новая фича.

Claude в реальном времени собирает требования — спрашивает про аналитику, проверяет спецификации и ведёт список открытых вопросов

На скриншоте выше агент сбора требований нашёл четыре открытых вопроса по итогам изучения кодовой базы и, вместо того чтобы выдумывать ответы, обращается к команде — например, спрашивает, переиспользовать ли для нового drawer существующие события аналитики или завести собственные.

Этап 3 — Ревью и утверждение финального SRS

Ответственные: Аналитик/Technical Project manager + QA + стейкхолдеры.

Черновой SRS из этапа 2 разбирают всей командой, пока его не утвердят все. Результат — единый финальный SRS, согласованный со всеми стейкхолдерами. Как только он утверждён, сразу происходят две вещи:

  • QA пишет тест-план прямо по финальному SRS. Тесты продумываются до начала реализации, поэтому баги ловятся в спецификации, а не в коде.
  • Разработка может стартовать параллельно. Финального SRS достаточно, чтобы начать; детальные спеки по доменам (следующий этап) старт не блокируют.

Хороший финальный SRS содержит:

  • Требования к фиче и критерии приёмки
  • Граничные случаи и обработку ошибок
  • API-контракты и потоки данных
  • Цепочки фолбэков и зависимости

Как выглядит финальный SRS

Под абстрактные описания процесса легко кивать, поэтому вот конкретный пример (на обобщённой, обезличенной фиче). Допустим, мы добавляем drawer со списком партнёров за промо-баннером.

В модуле feature-promo-banners сделать drawer со списком партнёров из API. Реализацию drawer переиспользовать из feature-item-details. Drawer открывается только по deep link.

Цепочка фолбэков:

  1. Основной сценарий: запустить промо-действие (основной партнёрский поток).
  2. Фолбэк 1: открыть Quick Access Drawer.
  3. Фолбэк 2: перейти на экран «Все партнёры».

Критерии приёмки:

  • Если основной промо-API падает (используется захардкоженный конфиг) — продолжать показывать скелетон и вызвать Drawer API.
  • Если Drawer API отвечает успешно → показать баннер; по тапу открывается Quick Access Drawer.
  • Если Drawer API тоже падает → показать баннер; по тапу — переход на /partners.

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

Этап 4 — Спеки реализации, сгенерированные ИИ (SRS × 3)

Ответственные: разработчик + Claude.

Финальный SRS говорит, что делать, но ещё не описывает, как. Это следующий шаг — и здесь за дело берётся LLM. С помощью скилла plan-feature (плюс инструменты изучения кода и документации и Figma MCP) Claude разворачивает финальный SRS в три детальные спецификации реализации по доменам:

Документ Ответственный За что отвечает
UI-спецификация Frontend / Design Экраны, компоненты, пользовательские сценарии, дизайн-токены
Server-спецификация Backend API, модели данных, бизнес-логика, коды ошибок
Client-спецификация Android / iOS Платформенная интеграция, deep links, нативное поведение

Эти документы гораздо детальнее финального SRS: они ссылаются на реальные файлы и модули, следуют существующим паттернам кодовой базы и содержат конкретные примеры реализации, а не описывают фичу в вакууме. На практике агент читает финальный SRS, запускает суб-агентов, чтобы покопаться в кодовой базе, и пишет каждую спецификацию, повторяя структуру кода, который уже есть в репозитории.

Этап идёт циклом:

Шаг Что происходит
ИИ генерирует Claude пишет детальные спеки реализации из финального SRS
ИИ ревьюит Claude проверяет собственные спеки на корректность и полноту
Разработчик ревьюит Разработчик проверяет, правит и утверждает их до написания кода

Цикл повторяется, пока разработчика всё не устроит, — и только тогда начинается кодирование. Ошибки проектирования отлавливаются здесь, на дешёвых текстовых артефактах, а не на ревью PR, когда код уже написан.

Этап 5 — Цикл кодирования с ИИ

Ответственные: разработчик + Claude.

Шаг Что происходит
ИИ пишет код Claude реализует фичу по утверждённым спекам и финальному SRS
ИИ ревьюит Claude проверяет получившийся код на ошибки и граничные случаи
Разработчик ревьюит Разработчик проверяет код, просит правки или утверждает

Поскольку спеки и план уже согласованы, этот цикл по большей части механический. Ту самую фичу с drawer собрали заметно меньше чем за час реального времени и примерно в три тысячи строк кода — и всё это соответствует спецификации, которую вся команда уже согласовала.

Этап 6 — QA, документация и релиз

Ответственный: QA.

  • QA прогоняет тест-план, который сам же и составил ещё на этапе 3.
  • Визуальный QA (VQA) сверяет UI с финальной UI-спецификацией.
  • Любые найденные проблемы возвращаются на этап ревью разработчика.
  • Claude анализирует, какую документацию нужно обновить после реализации.
  • Если всё проходит → деплой в PROD.

Шаг с документацией важнее, чем кажется. После выхода фичи Claude проводит анализ влияния на документацию: проверяет, какие файлы SRS, API-документация и спецификации аналитики разошлись с реальностью, помечает каждое изменение как крупное, мелкое или ненужное и предлагает конкретные правки — чтобы документация, с которой всё началось, оставалась актуальной к следующему разу.

После релиза реальная обратная связь от пользователей возвращается к Product — и цикл замыкается.

Что в итоге меняется

Если свести к сути, D3 сдвигает раньше по времени три вещи:

  • Спецификация перестаёт быть отчётом о сделанном и становится исходными данными, из которых вырастает разработка. Результат обсуждения — это и есть спецификация.
  • QA перестаёт тестировать постфактум и начинает писать тест-план уже по черновику SRS — то есть тесты продумываются до реализации, а не после.
  • ИИ перестаёт быть помощником-кодером в самом конце и становится участником каждого этапа: собирает требования, пишет спецификации, планирует, реализует, ревьюит и отмечает расхождения в документации.

Всё остальное — предсказуемый объём, меньше разговоров «давайте всё пересмотрим», более дешёвые ревью — вытекает уже из этих трёх сдвигов. Итог: меньше переделок и фичи, которые выходят ближе к тому, что задумывалось.

Несколько слов об инструментах

Я описываю всё на примере Claude и конкретного набора скиллов, потому что именно ими мы пользовались, но D3 не привязан к конкретной модели. В процессе нет ничего, что зависело бы от вендора, — нужен LLM-агент, который умеет читать вашу кодовую базу, искать в интернете, выполнять многошаговый промпт и, желательно, вызывать инструменты (для изучения кода и документации, для работы с дизайном). Подойдёт любая достаточно сильная модель: Claude, GPT, Gemini или локальная модель внутри агентного окружения вроде Cursor, Aider или ваших собственных скриптов.

Важны возможности, а не бренд: знание кодовой базы, чтобы спецификации ссылались на реальные модули; достаточно длинный контекст, чтобы вместить все сведённые требования; и доступ к инструментам, чтобы агент сверялся с реальностью, а не выдумывал. Поменяйте модель — семь этапов останутся прежними. Качество и скорость от модели к модели будут разными, так что считайте цифры выше одним частным примером, а не эталоном.

С чего начать

  1. Обкатайте на следующей новой фиче — пройдите D3 от начала до конца как пробный заход.
  2. Настройте скиллы — plan-feature, implement-feature и скилл для ревью PR.
  3. Подключите инструменты — изучение кода и документации, Figma MCP.
  4. Заведите шаблоны SRS — единую структуру для UI / Server / Client спецификаций.
  5. Разберите результаты пилота — соберите обратную связь, оцените сэкономленное время и доработайте процесс.

D3 — это не жёсткий фреймворк, а дисциплина. Цель простая: к тому моменту, когда кто-то садится писать код, все уже точно знают, что именно мы делаем.