В первой статье я писал про SDD за один вечер — Telegram‑бот, шесть команд Spec Kit, восемь часов от первого speckit.constitution до рабочего MVP. Это была проверка методологии на маленькой задаче.

С тех пор я прошёл 17 спринтов SDD на FullStack‑приложении: B2C‑трекер привычек и целей, два репозитория (backend и frontend), 251 тест на бэке и 77 на фронте, релиз в продакшен. Это уже не вечер — это полный цикл разработки FullStack‑приложения по одной методологии.

Здесь — что не дало мне потерять контроль на этом масштабе. Не «как быстро я это сделал», а как методология держит управляемость, когда фич много, репозиториев два, спринты идут параллельно и каждая фича касается обеих сторон.

Что построено за 17 спринтов

Чтобы дальше говорить о методологии — короткий контекст того, что под ней.

LifeSync — пет‑проект, B2C‑трекер привычек и целей. Backend на Spring Boot 3.5 + Java 21, Hexagonal Architecture на 6 Maven‑модулях, jOOQ вместо JPA, Apache Kafka с шестью независимыми консьюмерами и идемпотентностью через таблицу processed_events, JWT RS256 с ротацией refresh‑токенов, OpenAPI 3.1 как источник правды для API. Frontend на React 19 + TypeScript 5.9, Vite 8, Tanstack React Query, Zustand, shadcn/ui + Tailwind CSS, тёмная тема, двуязычный интерфейс через react‑i18next, мобильная адаптация до 375px.

В цифрах:

• 17 спринтов SDD — 7 на backend, 10 на frontend.

• Два репозитория — lifesync-backend (v1.0.2) и lifesync-frontend (v1.3.0). Деплой: backend на Railway, frontend на Vercel.

• 149 000 слов спецификаций. На backend — около 61 000 слов на 6 фич (где третий спринт прошёл без SDD‑артефактов), на frontend — около 89 000 слов на 10 фич. Это не считая constitution.md обоих репозиториев и кода как такового.

• 251 тест на backend (170 unit + 81 integration на Testcontainers с PostgreSQL и Kafka) и 77 на frontend (55 unit на Vitest + 22 E2E на Playwright).

• 19 Liquibase‑миграций, JaCoCo подключён.

• Релиз в продакшен — backend на Railway (без Kafka в demo‑окружении ради бесплатного тира), frontend на Vercel: lifesync‑frontend‑ten.vercel.app.

Дальше — про то, что не дало этому всему разъехаться.

Опора 1. Три чата вместо двух

В первой статье я зафиксировал схему «два чата»: отдельный чат с Claude — для думания (обсуждение архитектурных решений, подготовка промтов), Claude Code в терминале IDE — для исполнения (генерация спек, написание кода, запуск команд).

На FullStack‑проекте эта схема не выдержала. Backend и frontend живут в разных репозиториях, у них разные стеки, разные конституции, разные циклы спринтов. Нельзя было держать оба контекста в одной голове и в одном думающем чате — рано или поздно я начал бы переносить решения с одного стека на другой по инерции.

В итоге сложилась схема «три чата», не считая Claude Code в терминале IDE — он по‑прежнему остаётся исполнителем в каждом репозитории:

• Думающий чат для backend. Здесь живёт всё, что касается серверной части: Hexagonal‑структура, Kafka‑консьюмеры, JWT, jOOQ‑запросы. Контекст этого чата — lifesync-backend/constitution.md + OpenAPI‑спецификация + актуальная фича в работе.

• Думающий чат для frontend. Сюда уходят React, TypeScript, React Query, shadcn/ui, темизация, i18n. Контекст — lifesync-frontend/constitution.md + ссылки на backend‑репо и Swagger UI, чтобы я мог обращаться к актуальному API‑контракту.

• Третий, координационный чат. Для тем, которые касаются обоих репозиториев одновременно: деплой (Railway + Vercel + переменные окружения), кросс‑репо фичи (например, сложная серверная валидация пароля), ретроспективы. В этом чате я готовил промты для двух других чатов, чтобы решения по общим фичам были согласованы.

То есть концепция «два чата на проект» из первой статьи сохраняется — думающий чат плюс Claude Code в терминале. Просто к ним добавился координационный, общий для двух репозиториев. Итого пять рабочих контекстов: думающий + Claude Code на backend, то же на frontend, и координационный на двоих.

Когда я открывал второй чат для frontend, я переносил в него контекст backend через явные промты: ссылку на репозиторий, ссылку на Swagger UI, файл OpenAPI‑спецификации, краткое описание архитектуры. Это работает как информационный мостик — frontend‑чат получает не «общую идею», а конкретные точки опоры.

Что важно про этот мостик: он однонаправленный. Backend‑чат не получает обратной связи от frontend‑чата автоматически — если в процессе разработки UI я обнаруживал несоответствие в API, я возвращался в координационный чат, прорабатывал там, и оттуда уже шёл новый промт в backend‑чат. Это медленнее, чем «один чат на всё», но это и есть та структура, которая не даёт двум стекам перепутаться.

Третий чат — это не просто удобство. Это разделение зон ответственности на уровне ИИ‑собеседника. Когда вопрос конкретно про backend — backend‑чат уже в контексте, не надо его поднимать с нуля. Когда вопрос про деплой — координационный чат знает обе стороны.

Опора 2. Две конституции, живущие по‑разному

Конституция в SDD — это .specify/memory/constitution.md, документ‑договор между мной и проектом: какие архитектурные принципы соблюдаются, какие технологии в стеке, какие правила разработки. Spec Kit генерирует на её основе подсказки для всех остальных команд: speckit.specify, speckit.plan, speckit.tasks опираются на конституцию, чтобы не предлагать решения, противоречащие зафиксированным правилам.

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

Backend constitution. Стартовая ратификация — пустой шаблон в первый день проекта, затем версия 1.1.0 с полным набором принципов. Дальше — 12 правок, документ вырос от 50 строк до 437. Что добавлялось:

• v1.2.0 — стандарт работы с Liquibase (формат миграций, нумерация, структура changelog).

• v1.2.1 — правила атомарных коммитов.

• v1.2.2 — порядок code style правил.

• v1.2.4 — naming convention для веток.

• v1.3.0 — стандарт документирования OpenAPI как двенадцатый принцип.

• v1.3.1, v1.3.2 — execution rules: как именно интерпретировать tasks.md при имплементации.

После Sprint 5 (Kafka) constitution.md backend больше не правился. Это не значит, что он умер — это значит, что в раннюю фазу я зафиксировал все правила, которые регулируют дальнейшую разработку. Когда правила работают, документ перестаёт расти. Это и есть здоровое состояние.

Frontend constitution. Стартовая версия — 50 строк, затем ратификация 1.0.0 со всеми пятью принципами (API‑Layer Isolation, Server State via React Query, Component‑Logic Separation, Type Safety NON‑NEGOTIABLE, Design System Fidelity). Дальше — всего 4 коммита. Финальный размер — 137 строк.

Эволюция точечная: смена React Router v6 → v7 в Technology Constraints, позже — расширение под i18n с добавлением src/locales/ в обязательную структуру (Sprint 9). Никаких больших переписываний.

Почему две конституции эволюционируют так по‑разному? Потому что бэкенд решает больше неочевидных вопросов на старте. Какой формат миграций? Как нумеровать коммиты? Какая структура OpenAPI? Каждый раз, когда в спринте всплывал новый вопрос, к которому конституция не давала ответа — я добавлял туда правило. На фронте таких вопросов было меньше: shadcn/ui задаёт паттерны, React Query — серверное состояние, TypeScript строгий — а остальное оказалось в существующих принципах.

Здесь важен один тезис: конституция — это живой документ. Когда в проекте появляется новая ситуация, не покрытая правилами — документ адаптируется. Это не «нарушение» — это часть методологии. Spec Kit прямо об этом пишет: конституция должна быть живой, иначе она становится мёртвой буквой, которую все игнорируют.

Adapting the rule, not breaking it. Разница принципиальная.

Опора 3. speckit.analyze как контур обратной связи

speckit.analyze — одна из шести команд Spec Kit, и формально она называется «cross‑artifact consistency analysis report». На практике это команда, которая проверяет согласованность между четырьмя артефактами фичи: spec.md, plan.md, tasks.md, и фактическим кодом после имплементации. Если в спецификации описано требование, которое не отражено в плане, или в плане есть фаза, не разложенная на задачи, или код реализован в обход того, что было спланировано — analyze это находит.

Я запускаю speckit.analyze после реализации задач спринта — это обязательная часть моего цикла. Иногда — ещё и перед реализацией, после того как появился tasks.md, когда хочется убедиться, что задачи действительно закрывают спецификацию. За 17 спринтов analyze ловил несколько критичных вещей и регулярные мелкие. Самый яркий пример — Sprint 5 backend, события через Kafka.

Я закончил имплементацию шести консьюмеров со встроенной идемпотентностью, прогнал тесты, всё зелёное. Запустил speckit.analyze post‑impl. Нашёлся неочевидный недочёт: в нескольких use case'ах публикация события в Kafka шла внутри транзакции, без try‑catch вокруг publishEvent. Это значило, что если Kafka в моменте недоступна — исключение поднимается наверх и откатывает успешно зафиксированную транзакцию БД.

То есть данные сохранились, потом откатились, событие не отправилось — система в неконсистентном состоянии.

Я бы это в комит‑ревью пропустил. Тесты были зелёные, потому что в Testcontainers Kafka всегда доступна. Сценарий «Kafka недоступна, БД доступна» в integration‑тестах не покрывался. speckit.analyze это поймал не потому, что прогнал какой‑то умный тест — а потому, что прошёлся по спецификации, увидел требование «события публикуются после успешной транзакции», и сравнил его с фактом «публикация внутри транзакции». Расхождение.

Поправил try‑catch, добавил тест на DLQ retry, и заодно — асинхронный IT‑тест на streak‑расчёт, который тоже всплыл в этом анализе.

Это не магия. Это формализованный контур обратной связи: каждая фича заканчивается тем, что артефакты сравниваются между собой и с кодом. Расхождения сигнализируются. Я их разбираю и фиксирую. Это ловит вещи, которые иначе уехали бы в продакшен.

Ключевое наблюдение про analyze: он не заменяет тесты или ревью. Он работает на другом уровне — на уровне согласованности артефактов между собой. Тесты проверяют, что код делает что‑то. analyze проверяет, что код делает то, что было обещано в спецификации. Это разные слои.

Опора 4. API‑first как договор между двумя репозиториями

Когда два репозитория существуют отдельно, главная угроза согласованности — API‑контракт. Если backend выкатывает новый endpoint и забывает про frontend, или frontend ожидает поле, которое в API называется иначе — координация ломается. На обычной командной разработке это решается переписками, JIRA‑тикетами, ревью. У меня была другая опция: API‑first.

В backend я завёл отдельный Maven‑модуль lifesync-api-spec, в котором лежит единственный файл — lifesync-api.yaml, OpenAPI 3.1 спецификация на все endpoint'ы. На сегодня это 2669 строк YAML, 32 endpoint'а. Backend генерирует Java‑интерфейсы из этого YAML через openapi-generator-maven-plugin (контроллеры реализуют сгенерированные интерфейсы — писать их вручную запрещено конституцией). Frontend читает тот же YAML как источник правды и пишет TypeScript‑типы в src/types/ руками: 5 файлов, около 230 строк типов.

Почему frontend пишет типы руками, а не генерирует? Это сознательное решение. Генератор TypeScript‑типов из OpenAPI — рабочая опция (openapi-typescript, orval, @hey-api), и я её рассматривал. Не пошёл по двум причинам:

1. Контроль над формой типов. Сгенерированные типы часто буквально повторяют структуру API, со всей nullability и opt'ами. Для UI часто удобнее немного перекомпонованный тип, который ближе к тому, что отрисовывается на экране. Ручное написание оставляет это под контроль.

2. Типов мало, изменений ещё меньше. 230 строк типов на 32 endpoint'а — это контролируемый объём. Каждое изменение API сопровождалось ручной правкой типов на фронте, и это не превращалось в трудоёмкую задачу.

Внутри specs/ каждой фичи фронта лежит локальный contracts/‑каталог с markdown‑описанием endpoint'ов, которые эта фича использует — auth-api.md, goals-api.md, habits-api.md. Это не дублирование YAML и не альтернативный контракт, а навигационный срез под конкретную фичу для думающего чата: какие endpoint'ы я зову, какие поля жду, какие ошибки могут прилететь. Источник правды — по‑прежнему YAML на 2669 строк, но его не нужно держать перед глазами целиком, когда работаешь над одной фичей.

Эта схема работает как простой договор: один YAML — источник правды, два репозитория его читают, координация идёт через документ, а не через переписку. Когда мне нужно поменять API — я меняю YAML, перегенерирую интерфейсы на бэке, реализую методы, потом правлю типы на фронте. Если что‑то рассинхронилось — это видно сразу, потому что TypeScript падает на компиляции.

Что важно понимать про эту схему: speckit.analyze не проверяет согласованность между репозиториями автоматически. Каждая команда Spec Kit работает в пределах одного репозитория. Я делал кросс‑репо проверки руками: после изменений API в backend — в координационном чате готовил промт «вот изменения в API, проверь типы и компоненты frontend на необходимость правок», и проходил по этому промту в frontend‑чате.

Где было трудно

Несколько мест за 17 спринтов, где SDD пробуксовывал — и где я остановился, переразобрался, продолжил.

Sprint 8 backend, рассинхрон plan.md vs spec.md. speckit.analyze показал расхождение: plan.md описывал три фазы имплементации, в spec.md была упомянута четвёртая. По коду я уже сделал все четыре, но в плане — синхронизации не было. Случай несложный (одна правка в plan.md), но показательный: методология не позволила мне забыть про эту синхронизацию. Без analyze я бы заметил это только в ретроспективе спустя три спринта.

Sprint 10 frontend, релизный с накопленными доработками. Это был последний спринт фронта, и он отличался от предыдущих: не одна большая фича, а набор мелких UX‑улучшений и багфиксов, которые накопились перед релизом. SDD‑цикл здесь работал иначе — короткий spec.md, плотный tasks.md на список доработок, обычный analyzeв конце. Главный урок: не каждый спринт идёт по идеальному циклу. Иногда фича — это «накопленные мелочи перед релизом», и она требует своих tasks.md и analyze, но без больших спецификаций.

Backend Sprint 3, который прошёл мимо SDD. В backend между Sprint 2 и Sprint 4 был короткий спринт настройки локального окружения для разработки — один fix‑коммит, без specs/003-*/. Тогда я не делал спецификацию: задача казалась слишком технической для SDD‑цикла. Сегодня бы я сделал спеку даже на это — specs/003-local-dev-setup/spec.md со списком требований к dev‑окружению занял бы 50 строк, но дал бы фиксацию: какие порты, какие переменные окружения, какой docker‑compose. Урок на будущее: SDD одинаково полезен на больших фичах и на маленьких настроечных задачах.

Что я забрал из этого опыта

Чувство контроля на 17 спринтах сохранилось до последней фичи. Это не потому, что я какой‑то особенный — это потому, что методология даёт систему обратной связи на нескольких уровнях одновременно.

• Спецификации фиксируют намерение. Что я хотел построить.

• Конституция фиксирует правила. Как я договорился это строить.

• speckit.analyze ловит расхождения. Что разъехалось между намерением, правилами и кодом.

• Три чата разделяют контексты. Backend, frontend, общая координация — каждый со своим документальным фундаментом.

• API‑first — договор между двумя репозиториями. Один YAML, два потребителя.

Когда эти пять компонентов работают вместе, масштаб проекта перестаёт быть угрозой управляемости. Спринтов может быть 17, может быть 50 — структура контроля не меняется. Меняется только содержание.

Главный сдвиг от первой статьи: методология масштабируется без потери качества. Один вечер с Telegram‑ботом и 17 спринтов с FullStack‑приложением — это одна и та же методология, отличающаяся в деталях (третий чат, две конституции вместо одной), но не в сути. Это и есть тот ответ на вопрос «работает ли SDD за пределами игрушек», который у меня после первой статьи был ещё открытым.

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

Что дальше

Это третья статья в серии материалов из моих проектов:

• Первая — про SDD на одном вечере на примере Telegram‑бота.

• Вторая — технический разбор архитектурных решений на парсере бизнес‑формул через ANTLR4.

В следующих статьях планирую разбирать конкретные технические темы из LifeSync:

• Hexagonal Architecture на Maven Multi‑Module — как разложить backend на шесть модулей с чистым domain без Spring и use case'ами через @Bean в конфигурации.

• jOOQ вместо Hibernate — почему я отказался от ORM и где это окупается, а где нет.

Репозитории проекта:

• Backend — github.com/zahaand/lifesync‑backend

• Frontend — github.com/zahaand/lifesync‑frontend

• Демо — lifesync‑frontend‑ten.vercel.app