Третья, заключительная статья из цикла.

Часть 1 — где LLM теряет межсервисный контекст и почему локальных спек недостаточно.

Часть 2 — archspec как контракт вместо свободного Markdown.

Часть 3 — archspec investigate: исследование фичи, обновление контрактов и реализация.

В части 1 я показал, что spec-driven development с LLM начинает ошибаться, когда фича проходит через несколько микросервисов: по отдельности каждый сервис выглядит аккуратно, а вместе система работает не так, как нужно. Модель теряет межсервисный контекст — правила, которые живут на границах между сервисами, не записаны в одном месте, и LLM их пропускает. В части 2 я собрал archspec: на каждый сервис генерируется машиночитаемый контракт SERVICE_MAP.yaml, который делает эти правила явными.

В этой части я беру ту же фичу — автоматическое переназначение задачи после отказа фрилансера — и прогоняю её заново через /archspec:investigate, но уже поверх контрактов. Тот же промпт, та же модель (Claude Sonnet 4.6). Вопрос один: поймает ли план те межсервисные ошибки, на которых в первый раз фича не сошлась, ещё до написания кода — и где спотыкается уже сам инструмент.

В первой части я разбирал, почему spec-driven development начинает ошибаться, когда фича проходит через несколько микросервисов. Проблема не в том, что LLM плохо читает код или не умеет писать спеку. На уровне отдельных сервисов всё может выглядеть аккуратно: есть описание, план, реализация и тесты. Но правила, которые связывают сервисы между собой, часто не записаны в одном месте. Часть таких правил спрятана в реализации, часть известна только команде, а часть всплывает уже на ревью. Обычный Markdown не решает эту проблему: его легко написать неполным, сложно проверить автоматически и почти невозможно ревьюить как структурный контракт.

Отсюда родилась идея: нужен машиночитаемый контракт на каждый сервис, который фиксирует межсервисные правила, проверяется на коммите и даёт LLM структурный контекст вместо набора Markdown-файлов. Для этого я собрал open source плагин для Claude Code — archspec.

В этой части я покажу, как работает /archspec:init на одном сервисе из демо-проекта freelance-marketplace, разберу сгенерированные артефакты и объясню, как archspec поддерживает их в актуальном состоянии. Напомню, это Go-проект с 12 микросервисами для поиска фрилансеров. Вот схема сервисов, которую я использую на протяжении всего цикла:

Я работаю в большой продуктовой компании с тысячей микросервисов. В такой системе даже небольшая фича часто проходит через несколько сервисов, событий и внутренних контрактов. Spec-driven development с LLM уже применяется в некоторых командах для планирования и ревью фич, поэтому мне было важно понять, где этот подход помогает, а где начинает ошибаться. Пока задача живёт внутри одного сервиса, всё обычно идёт быстро: спека короткая, описание и реализация помещаются в контекст модели. Но как только фича проходит через несколько сервисов, начинаются проблемы. По отдельности каждый кусок выглядит нормально: разбиение на слои, именование по код стайлу, прохождение тестов и ревью. Но в целом система не работает должным образом. Типичные ошибки: нет идемпотентности, LLM упускает сценарии и edge case-ы, появляются циклические вызовы сервисов. Чем больше делаешь правок, тем больше ошибок она допускает.

Для эксперимента я собрал отдельный стенд: Go-проект - платформа для поиска фрилансеров. Внутри 12 микросервисов, связанных через gRPC и брокер сообщений; в этом проекте брокером выступает NATS. Одни сервисы хранят задачи и профили исполнителей, другие подбирают кандидатов, считают расстояния, проверяют портфолио и отправляют уведомления. Проект специально спроектирован с шестью категориями архитектурных ловушек: они проявляются не внутри одного сервиса, а на границах между сервисами.

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

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

На это можно ответить, что нужен end-to-end тест на весь сценарий, но это не закрывает проблему целиком. End-to-end тесты есть не везде, их дорого поддерживать, и они не покрывают все развилки: особенно редкие edge case-ы, дубликаты событий, гонки и редкие комбинации условий. Главное же в другом: на этапе spec-driven разработки модель должна помочь собрать требования, ограничения и контекст, а именно там она часто ошибается.

Разработчик тоже не всегда заранее знает, где спрятана проблема. Он может помнить про Outbox, дедупликацию уведомлений или особые требования конкретного сервиса к входным данным, но не сформулировать это как ограничение для новой фичи. LLM читает документы по сервисам, задаёт уточняющие вопросы и всё равно может пропустить связь между ними.

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

Я Go-разработчик из крупной Bigtech-компании и один из основателей ИИ-помощника по налаживанию отношений Ближе. По сути это телеграм-бот, который принимает вопрос от пользователя по long-polling модели, обогащает его промтом, идёт в LLM, получает ответ, отправляет обратно пользователю. Контекст диалога и пользователи хранятся в Postgres, всего один инстанс приложения на Go, также cron, который отправляет уведомления с просьбой оставить обратную связь о продукте. Docker Compose для запуска нескольких контейнеров.

Также в моей команде есть product-manager, который отвечает за развитие продукта. Ему необходимо быстро тестировать гипотезы, понимать эффективность каналов продвижения, считать вовлечённость, удержание пользователей и желательно делать это всё с минимальными тратами.