Spec Kit - это один из самых амбициозных фреймворков для наведения порядка в разработке с использованием ИИ. В нашем предыдущем посте о spec driven development мы обсуждали его потенциал для закрытия давних пробелов в рабочих процессах с ИИ-ассистентами за счет обеспечения соблюдения стандартов проекта, контекста на уровне функций, принудительной декомпозиции для управляемого объема работ и контрольных этапов (review gates) для контроля качества.

Но исполнение - это то, где теория сталкивается с сопротивлением. Документация Spec Kit - это сильная отправная точка, с понятными видео, подробными руководствами и предписывающими шагами, которые позволяют развернуть его за считанные часы. Сложности начинаются, когда вы покидаете «песочницу». Подобно примерам Animal → Dog → Labrador в учебниках по ООП, примеры учат синтаксису, а не промышленной разработке программного обеспечения.

Пробел заключается не в документации, а в контексте и реальной экспертизе. Чистые примеры прекрасно работают для greenfield-проектов (проектов с нуля), но большинство команд работают с существующими (brownfield) кодовыми базами, сформированными месяцами эволюционирующих решений, компромиссами разработчиков, конкурирующими паттернами и не подлежащими обсуждению стандартами качества.

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

О нашем проекте и испытательном полигоне

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

• 280 000 строк кода

• 10 активных разработчиков

• Устоявшуюся архитектуру, паттерны и стандарты качества.

Это корпоративное ПО средней сложности со всеми типичными компромиссами и накопленными решениями, свойственными реальным системам.

Тестовым кейсом для Spec Kit стало добавление функции обратной связи от пользователей на наш портал.

Функция: кнопка обратной связи вызывает всплывающую форму, пользователь выбирает реакцию + добавляет текст + опциональное вложение файла, отправляется email команде поддержки. Она должна была интегрироваться с существующим трекингом использования (Amplitude) и следовать нашим установленным паттернам.

Задача проверки: сможет ли рабочий процесс Spec Kit справиться с интеграцией в существующий проект. Если он сможет справиться с функцией, включающей UI-компоненты, внешние интеграции и ограничения по качеству, это подтвердит, что подход работает за пределами туториалов - на реальных корпоративных проектах с реальными ограничениями.

Использование Spec Kit для разработки функций: Пошаговая реализация в существующем проекте

В ходе практической реализации мы поняли, что Spec Kit требует как человеческого контроля, так и предварительных усилий. Он не обеспечит полную сквозную автоматизацию. Каждый этап требует особого внимания и экспертизы.

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

Шаг 1 - Конституция (Constitution): Стандарты и соглашения проекта

Первым шагом во внедрении Spec Kit является создание вашей Конституции - основополагающего документа, кодирующего ДНК вашего проекта. Он определяет стандарты, соглашения и архитектурные принципы, которые формируют поведение вашей кодовой базы и то, как ИИ-ассистент работает внутри нее.

Вы можете сгенерировать начальную версию, запустив /SpecKit.constitution. Это даст вам быстрый обзор стека вашего проекта, соглашений об именовании, поверхностных паттернов и базовых шаблонов анализа кода.

PS: Ассистент отдает приоритет .md файлам в вашем репозитории - README, документации, markdown-контенту. Они сильно влияют на вашу конституцию. Устаревшая документация создаст устаревшие правила конституции. Приведите их в порядок перед генерацией конституции.

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

1. Определите вашу политику переиспользования кода

Наша команда быстро поняла, что «агент предпочитает писать, а не читать». Его поведение по умолчанию - создавать новый код вместо переиспользования существующих компонентов. Во время реализации он даже создал новую директорию «email-service» с дублирующей реализацией, вместо того чтобы сослаться на существующий код, который уже это делал (и более того, имел то же имя). Чтобы предотвратить это, добавьте явные инструкции по переиспользованию в вашу Конституцию:

Core Principles

Code duplication is prohibited.
You must search for existing functions before creating a new one.
If there are no functions to be reused, then a new one could be introduced.
This rule is especially important for _-data-client (data access layer for database)
and _-api-client (data access layer for external HTTP services).

С этим правилом Spec Kit теперь генерирует списки задач, которые включают шаг «поиск существующей функциональности», побуждая агента искать переиспользуемый код перед реализацией. Результаты заметно лучше, хотя и не безупречны. Агент все еще может иногда пропускать переиспользуемый код или использовать неподходящие паттерны, поэтому разработчикам необходимо продолжать проверять результаты.

2. Задокументируйте архитектуру ВАШЕГО проекта

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

В нашем случае UI-приложение не использует сервисный слой, потому что содержит минимальную бизнес-логику. Наше соглашение - избегать создания сервисов для сущностей. Однако, так как паттерн router→service широко используется, Spec Kit, управляемый ИИ, автоматически внедрял сервисные слои во время генерации.

Нам пришлось исправить это, четко задокументировав нашу архитектуру в Конституции. Это лишь один пример; у вашего проекта могут быть свои собственные паттерны, требующие аналогичного разъяснения. Вот как мы внедрили это в нашу архитектуру:

Solution Architecture Patterns

Standard API Implementation Structure:

- Router function with request validation
- Router calls data client and/or API client directly
- NO business logic layer/service layer - Simple logic can stay in router; complex logic in data clients

3. Определите запрещенные паттерны вашего проекта

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

Например, наша конституция четко гласила: «Никаких блоков try-catch в обработчиках маршрутов. Используйте глобальный middleware», однако агент все равно добавлял блоки try-catch во время реализации.

Вот как мы определили наш запрещенный паттерн для блоков try-catch:

Backend (BFF) Rules

Routers should not contain try/catch blocks with “log and rethrow” logic, especially for validation. Exception handling is centralized and handled by express.js middleware.

Распространенные ошибки

Два критических урока о том, что НЕ следует включать в вашу конституцию:

• Избегайте ссылок на внешние стандарты: Может показаться полезным написать «следуйте RFC 9457 для обработки ошибок», но это часто вызывает проблемы. Ваш проект может следовать только части этого стандарта, а LLM не узнает разницы. Она будет предполагать полное соответствие и предлагать реализации, согласованные со всем стандартом, даже если это противоречит вашим реальным практикам. Будьте конкретны в отношении паттернов, которые ваш проект действительно использует, а не теоретических.

• Используйте точную терминологию: Избегайте упоминания концепций, которые ваша система на самом деле не реализует. Например, если вы не используете транзакции базы данных, избегайте называть последовательность связанных операций «транзакцией». Этот термин подразумевает свойства ACID, и ассистент будет моделировать реализацию соответствующим образом. Придерживайтесь точных терминов, описывающих то, что ваша система делает на самом деле, чтобы предотвратить путаницу и сохранить согласованность.

Ключевые выводы

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

• Выделите 2-3 дня на первоначальный черновик и продолжайте уточнять его в ходе реального использования. Большинство наших правок касались удаления ненужного сгенерированного кода, а не добавления недостающих частей. Со временем конституция становится живым документом, который эволюционирует вместе с системой.

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

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

Шаг 2 - Спецификация (Spec): Требования и критерии приемки

Фаза спецификации определяет, что вы хотите построить, прежде чем решать, как это строить.

Запуск /SpecKit.specify генерирует структурированные спецификации на основе последовательного шаблона, разбивая каждую функцию на четкие пользовательские истории (user stories) и критерии приемки. Эта документация формирует основу для последующего технического планирования и реализации.

? Важное замечание: Spec Kit нативно не интегрируется с инструментами управления проектами или дизайном, такими как Jira, Azure DevOps, Figma или Lucid. Хотя интеграция технически возможна через MCP-сервер, она не поддерживается «из коробки». Spec Kit функционирует независимо через структуру файлов .md, что означает, что синхронизация с другими системами должна управляться вручную.

Еще одним критическим моментом является разрыв в знаниях и контексте. Большая часть знаний о вашем проекте уже существует в инструментах типа Jira, ADO Wiki или Confluence. Spec Kit не имеет прямого доступа к этой информации, поэтому ваша ответственность - подключить или перенести соответствующий контекст в его рабочий процесс для обеспечения полноты. Вот как создать спецификацию:

1. Подготовьте сильный бриф функции в качестве входных данных

Высококачественные спецификации начинаются с четких входных данных. Предоставьте все релевантные активы, описывающие функцию: экраны дизайна (мы использовали аннотированные скриншоты), вспомогательную документацию и любые существующие материалы, такие как задачи в JIRA или функциональные наброски.

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

2. Проверьте и уточните вывод спецификации

Spec Kit обычно генерирует 3-4 пользовательские истории на спецификацию, с примерно 10 функциональными требованиями на каждую историю - в итоге получается 40-50 функциональных требований на спецификацию. Этот паттерн исходит из структуры шаблона спецификации и остается довольно последовательным для разных функций.

Чтение 40-50 требований, сгенерированных LLM, утомительно - но это обязательно, если вы ожидаете качественного результата от вашего ИИ-ассистента. Убедитесь, что разбивка покрывает ваши реальные граничные случаи (edge cases), а не только счастливые пути (happy paths). Если чего-то не хватает, вставьте дополнительные критерии приемки.

3. Запустите clarify для раннего выявления неясностей

Spec Kit включает команду /SpecKit.clarify, которая систематически задает вопросы о недостаточно специфицированных областях.

Мы обнаружили, что этот шаг критически важен - запуск clarify перед переходом к фазе планирования выявлял неясности на ранней стадии, значительно сокращая переделки на последующих этапах. Пропустите его, и вы обнаружите те же самые неясности во время реализации, когда их исправление будет стоить дорого. Первоначальная генерация спецификации занимает минуты, но инвестируйте 10-20 минут в уточнение и 30-60 минут в проверку. Вложение времени на старте напрямую уменьшает проблемы в дальнейшем.

4. Интегрируйте с вашим трекером задач

Большинство команд используют инструменты вроде JIRA как авторитетный источник требований. Задача состоит в том, чтобы определить, как это сосуществует со Spec Kit. Исходя из нашего опыта, JIRA остается необходимой для видимости статуса и планирования, управления релизами и отслеживания прогресса, в то время как Spec Kit берет на себя детальную работу над спецификациями. Наше текущее разделение ответственности:

• JIRA: Поддерживает высокоуровневую иерархию (Эпик → Спецификация → Пользовательские истории) с краткими описаниями, ожидаемым поведением и привязанными визуальными активами.

• Spec Kit: Берет входные данные из JIRA и генерирует детальную разбивку - около 40–50 функциональных требований на спецификацию, хранящихся в markdown. Бизнес-аналитик или аналогичный проверяющий валидирует эти выходные данные на точность.

Spec Kit - это не замена инструментам трекинга и планирования; это дополнение. Инструменты вроде JIRA остаются сфокусированными на том, что они делают лучше всего: статус, релизы и видимость, в то время как Spec Kit берет на себя тяжелую работу по детальной, основанной на markdown разбивке исполнения.

5. Оценивайте размер функций на основе объема и сложности

По нашему опыту, Spec Kit лучше всего работает с функциями, которые один разработчик может завершить за 1-5 дней. Его структура по умолчанию из 3-4 пользовательских историй подходит для работы низкой и средней сложности, где 40-50 функциональных требований обеспечивают достаточную детализацию. Группировка не всегда может быть идеальной, но она, как правило, следует логическому паттерну.

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

? Предупреждение о качестве: Spec Kit МОЖЕТ обрабатывать более крупные функции или эпики, но качество вывода снижается. Подача больших, сложных функций в одну спецификацию часто приводит к неполным или фрагментированным результатам, что ослабляет качество последующей реализации.

Ключевые выводы

• Инвестируйте время в шаг уточнения (clarification). Его пропуск ведет к дорогостоящим переделкам позже. Хотя генерация спецификации может занять минуты, трата 10–20 минут на уточнение и 30–60 минут на проверку радикально сокращает исправления на последующих этапах.

• Назначьте четкое владение со стороны BA. BA (или разработчики, выступающие в роли BA) должны оценивать размер функций, определять требования JIRA, запускать /SpecKit.specify и валидировать сгенерированные разбивки. Spec Kit повышает эффективность BA, но не может заменить человеческое суждение.

• Возьмите обязательство проверять все сгенерированные требования. Ожидайте чтения 40–50 сгенерированных LLM пунктов на функцию. Объем может быть утомительным, но последовательная проверка человеком остается необходимой для поддержания точности и контекста.

Шаг 3 - План (Plan): Технический дизайн и архитектура

Фаза планирования переводит требования в подход к технической реализации. На этом шаге Spec Kit анализирует вашу кодовую базу, извлекает контекст из конституции и создает файл plan.md, в котором перечислены детали реализации, изменения на уровне файлов и точки интеграции.

? Для небольших репозиториев или простых функций ассистент может сгенерировать надежный план только на основе описания функции. Однако в больших, зрелых системах, как наша, с кодовой базой 1.5-летней давности и 180 тысячами строк, вам нужно будет предоставить детальный системный дизайн в качестве входных данных.

Вот наш рабочий процесс для эффективного выполнения этого:

1. Предоставьте архитектурный контекст заранее

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

В нашем рабочем процессе архитекторы решений создают детальные архитектурные диаграммы, используя Lucid, как часть фазы дизайна. При использовании этих диаграмм в качестве входных данных для Spec Kit хорошо работают два метода:

• Более простой метод: Предоставить скриншот архитектурной диаграммы непосредственно как входные данные.

• Наш подход: Использовать агента с контекстом проекта для преобразования диаграммы в детальное текстовое описание, обогащенное дополнительным техническим контекстом. Это дает планы более высокого качества.

Это текстовое описание становится одним из входных данных для /SpecKit.plan, наряду со спецификацией функции. Помимо архитектурных диаграмм, также включите:

• Контракты API с примерами форматов запросов и ответов

• Известные точки интеграции, такие как имена функций, файлы и папки

• Другие релевантные технические решения

2. Выполните команду plan с полным контекстом

Как только все архитектурные входные данные подготовлены, запустите /SpecKit.plan для генерации плана реализации. Агент объединяет вашу конституцию, спецификацию и контекст дизайна для создания детального чертежа разработки.

Вы получите:

• Техническое соответствие вашей конституции

• Шаги реализации, согласующиеся с вашей архитектурой

• Точки интеграции, сопоставленные с существующим кодом

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

План - это руководство, а не абсолютный свод правил. Во время реализации ассистент все еще может модифицировать файлы за пределами исходного объема, но дерево файлов остается надежным индикатором проектного замысла.

3. Проверяйте план совместно

Проверяйте сгенерированный план с архитекторами и старшими разработчиками. Убедитесь, что архитектура согласована, не вводятся несанкционированные слои, а точки интеграции точны. Отмечайте любые неоднозначные действия с файлами, такие как «modify utils», для ручной верификации, особенно для новых интеграций, новых моделей данных или недавно открытых контрактов API, требующих надзора архитектора или техлида.

После валидации заблокируйте план и относитесь к plan.md как к контракту между архитекторами и разработчиками. После этой проверки переходите к /SpecKit.tasks, зная, что структура выстоит во время исполнения.

Распространенные ошибки

• Определяйте спецификации интеграции точно: Высокоуровневые заметки об интеграции, такие как «modify the data client» или «integrate with publisher service», плохо транслируются в действенные планы. Spec Kit требует явного руководства для правильного соединения компонентов. Включайте точные имена файлов, имена функций и паттерны взаимодействия, чтобы агент понимал, как части системы коммуницируют.

• Пишите контракты API сами. Позволение Spec Kit выводить контракты вносит несоответствия, особенно в граничных случаях. Определите их в вашем системном дизайне с явными схемами запросов и ответов и ожиданиями по обработке ошибок, например:

POST /api/feedbacks
Description: Create a feedback entry and finalize attachments by referencing previously uploaded attachment Ids.
Request (application/json):
{
  "rating": "great",
  "comment": "I like your new AI Adoption Radar page",
  "attachments": ["3f786f3e-533b-4030-aa2a-47d03f6f5b62"]
}
Response: 201 with empty body 400 invalid payload (e.g., missing rating)

Этот уровень конкретики помогает Spec Kit генерировать более точные планы реализации.

Ключевые выводы

• Предоставляйте системный дизайн заранее: Предоставление архитектурного контекста на ранней стадии позволяет плану соответствовать вашей реальной архитектуре, минимизируя переделки. Без этих входных данных Spec Kit генерирует общие, часто неоптимальные структуры, которые приходится пересматривать позже.

• Признайте, что качество плана определяет все: Точность вашего плана напрямую влияет на качество задач и реализации. Команды, у которых уже есть проектная документация, всегда должны включать ее в качестве входных данных, чтобы Spec Kit мог транслировать ее в детали реализации на уровне кода.

• Инвестируйте усилия в точные проектные входные данные: Делитесь четкими контрактами API с примерами запросов/ответов, явными точками интеграции (имена файлов, имена функций), хорошо определенными критериями приемки («эндпоинт возвращает 200 с валидными данными» вместо «эндпоинт работает») и примерами выходных данных для сложной логики.

• Используйте фазу планирования надлежащим образом: Для greenfield-функций Spec Kit помогает генерировать структуру с нуля. Для существующих проектов с разработанным дизайном он преобразует высокоуровневую документацию (архитектурные диаграммы, контракты API) в конкретные файловые структуры, модификации кода и шаги реализации. Трата нескольких лишних минут на уточнение плана экономит часы во время разработки и проверки.

Шаг 4 - Задачи (Tasks): Декомпозиция реализации

Фаза задач трансформирует планы реализации в конкретные, упорядоченные, исполняемые шаги. Запустите /SpecKit.tasks на вашем валидированном плане, чтобы сгенерировать разбивку. Каждая задача включает явные зависимости, области действия (файловые пути) и четкие цели - обычно 1-2 файла на задачу. Вот наш рабочий процесс:

1. Запустите /SpecKit.tasks на утвержденном плане

Команда парсит ваш валидированный plan.md и выдает чеклист, сгруппированный по фазам (модель данных, клиент, API, тесты и т.д.). Каждая задача указывает точные пути к файлам, упорядоченные зависимости и объем реализации.

Phase 1: Project Setup & Dependencies
- [x] T001 Create git feature branch
    002-sidebar-feedback-integration from main
- [x] T002 [P] Add domain-driven feedback directory structure
    to packages/core/src/feedback/
...
Phase 2: Foundational Infrastructure
- [x] T006 Create Knex database migration for feedback tables in
    db/migrations/20241021_create_feedback_tables.js
- [x] T007 [P] Create shared feedback types in
    packages/core/src/feedback/
    (FeedbackSubmission, FileAttachment, FeedbackRating)
    REVISED: Types now follow core PEntity pattern
    without Zod dependencies
...
- [x] T010 Setup Express router with Backstage plugin integration in
    packages/backend/src/feedback-management/feedback-router.ts

2. Проверьте список задач

Мы выявили несколько повторяющихся ловушек:

• Добавляйте конкретику там, где необходимо. Некоторые задачи слишком общие (например, «реализовать клиент данных») и не имеют детализации на уровне методов. Добавление конкретики, такой как требуемые интерфейсы или потоки данных, улучшает качество реализации.

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

• Усиливайте переиспользование кода. Несмотря на политику переиспользования в конституции, задачи часто по умолчанию предлагают «создать новое». Редактируйте их, чтобы подчеркнуть «поиск, переиспользование или расширение» существующего кода, где это применимо.

3. Решите, когда перезапустить, а когда уточнить

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

• Уточняйте для мелких пояснений: Когда описания задач требуют лишь лучшей формулировки, дополнительного контекста или незначительных корректировок, уточняйте через промпты вместо ручного редактирования. Используйте уточнения на основе промптов и перезапускайте /SpecKit.tasks для регенерации. Эти уточнения сохраняются в будущих итерациях и поддерживают отслеживаемость рабочего процесса.

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

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

• Используйте правило «третьего уточнения» как сигнал: Если вы обнаружите, что делаете третье или четвертое «маленькое» исправление, остановитесь. Множественные микро-уточнения обычно маскируют структурную проблему выше по потоку. Перезапуск с правильной фазы экономит время, сохраняет качество и предотвращает накопление технического долга в вашей цепочке генерации.

Ключевые выводы

• Обеспечьте автономию в контролируемых границах: До разбивки задач агент реализовывал целые функции за один проход - создавая 10–15 файлов за 20–30 минут без видимости промежуточной логики. После разбивки задач работа сегментируется на небольшие, проверяемые блоки (обычно 1–2 файла на задачу), позволяя вам отслеживать прогресс, выявлять проблемы на ранней стадии и направлять исправления в середине реализации.

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

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

• Используйте каскадный эффект для систематической регенерации: Фреймворк гарантирует, что исправления выше по потоку автоматически перетекают вниз. Исправление конституции регенерирует план, задачи и реализацию. Исправление плана регенерирует задачи и реализацию. Каждая коррекция распространяется вперед, сохраняя выравнивание по всем фазам - в этом истинная сила дизайна SpecKit.

Шаг 5 - Реализация (Implementation): Перевод дизайна в работающую систему

Реализация выполняет разбивку задач и генерирует код. Агент генерирует рабочий код для простых реализаций, с базовой структурой, следующей паттернам из конституции и существующего кода. Вы получаете видимость прогресса через выполнение задач, и агент может выполнять локальные команды CLI (npm, dotnet и т.д.) при необходимости.

Вот рабочий процесс:

1. Выполняйте контролируемыми фазами

Запускайте /SpecKit.implement позадачно или пофазно, а не все сразу. Команда поддерживает выборочное выполнение - конкретные задачи, целые фазы или все сразу.

Наш подход с контрольными точками:

• Реализовать Фазу 1 → Проверить → Валидировать → Исправить при необходимости

• Перейти к Фазе 2, то же самое: Реализовать → Проверить → Валидировать → Исправить при необходимости

Это трансформирует подавляющую сложность в управляемые инкременты.

2. Исправляйте отклонения ИИ-ассистента

Как мы уже подчеркивали, ИИ-ассистент не всегда следует инструкциям - даже когда конституция, план и задачи явны. Следите за этими отклонениями:

• Нарушения Конституции: Даже когда в конституции есть явные правила, агент не последовательно обеспечивает их соблюдение во время генерации кода. Наш пример: Конституция явно гласила «НИКАКИХ блоков try-catch в обработчиках маршрутов - используйте глобальный middleware». Тем не менее, агент все равно добавлял блоки try-catch в обработчики маршрутов.

• Отклонения от задач и плана: Spec Kit не гарантирует и не валидирует, что реализация действительно следует плану задач. Агент может добавить функции, которых нет в плане, пропустить запланированные шаги, обновить файлы, не упомянутые в плане, или реализовать иначе, чем спроектировано.

3. Справляйтесь с непредсказуемым качеством кода

Качество кода варьируется значительно - некоторый сгенерированный код великолепен, некоторый - тонко неверен. Это добавляет сложности проверке:

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

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

4. Переключайтесь на разработку с ИИ-ассистированием

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

Именно здесь вы возвращаете контроль от ИИ. Ваша роль становится похожей на роль технического лида, проверяющего реализацию джуниор-разработчика: внимательно проверьте реализацию, определите, что требует исправления, затем используйте ИИ-инструменты (GitHub Copilot, Cursor, Claude code или аналогичные), чтобы помочь эффективно реализовать эти исправления.

ВЫ управляете решениями, ИИ помогает с исполнением. Агент дал вам базовый код - последний шаг требует человеческого суждения, но вы все еще можете использовать ИИ-инструменты для ускорения уточнений.

Ключевые выводы

• Определите роль ИИ как помощь, а не автономию: SpecKit предоставляет структурированную поддержку ИИ, а не замену разработчикам. Человеческое суждение остается незаменимым, проверки (reviews) являются неотъемлемой частью процесса, а не признаком неудачи. По мере созревания конституции качество вывода улучшается, но надзор требуется всегда.

• Приоритезируйте интеллект модели над сложностью промпта: Сильная модель с простым промптом последовательно превосходит простую модель с хитроумным промптом. По нашему опыту, более новые модели (например, Claude Sonnet 4.5) выдают заметно более высокое качество, в то время как старые показывают явную деградацию.

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

• Установите реалистичные ожидания по уточнению: Сохранение 60–80% сгенерированного кода после проверки - это отличный результат. Ожидайте 20–40% уточнений для обработки пропущенных граничных случаев, корректировок интеграции, переусложненной логики или нарушений правил конституции.

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

Чему мы научились на всех фазах и этапах

Начнем с хороших новостей: Spec Kit не заменит разработчиков, дизайнеров или архитекторов в ближайшее время. Что он меняет, так это то, как они работают. Он автоматизирует механические, структурированные задачи и оставляет людям принятие контекстуальных, архитектурных и дизайнерских суждений, которые ИИ все еще не может воспроизвести. После прогона множества функций через все пять фаз, проявились пять последовательных уроков:

Правило 80/20 для автоматизации

На каждой фазе Spec Kit обрабатывал около 80% структурированной работы автоматически. Оставшиеся 20% требовали человеческого участия: решений, связанных с компромиссами, доменным контекстом и специфическими для проекта нюансами. Работа Spec Kit - справляться с предсказуемой, повторяющейся работой, чтобы инженеры могли сосредоточиться на контексте, суждениях, специфических нюансах проекта, логике, качестве и намерении. Лучшие результаты получались, когда мы относились к этому как к сотрудничеству, а не делегированию.

Проблема кумулятивного качества

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

0.8 × 0.8 × 0.8 × 0.8 × 0.8 = 0.33

К концу реализации кумулятивное качество упало бы примерно до 33 процентов без промежуточных проверок. Вот почему контрольные этапы (review gates) - это не бюрократические препятствия, а необходимые, подкрепленные данными меры предосторожности. Каждая фаза требует валидации перед движением дальше; иначе ранние неточности распространяются по рабочему процессу и разрушают качество финального результата.

Усталость от проверок - это неприглядная правда

Проверка сгенерированных ИИ Markdown-файлов необходима, но когнитивно утомительна. В отличие от кода или документации, написанный ИИ текст выглядит грамматически правильным и вроде бы разумным, но требует постоянного тщательного изучения на предмет фактической и архитектурной точности.

Естественно, ваш фокус будет смещаться, и ошибки могут начать накапливаться в правдоподобных формулировках.

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

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

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

Что делать? Как наша команда справилась с этим? Честно - у нас нет идеального решения. Делайте перерывы. Оставайтесь бдительными. Относитесь к этому как к код-ревью, а не как к легкому чтению. Ротируйте тех, кто делает проверки, если возможно. Но будьте готовы: это будет скучно. Это налог, который вы платите за помощь ИИ - ментальные усилия смещаются с набора текста на валидацию, но они не исчезают.

Качество модели - это решение о продуктивности, а не выбор стоимости

Интеллект модели напрямую влияет на соотношение 80/20. Обновление с Claude Sonnet 4.0 до 4.5 сократило наше время на переделки почти вдвое. Более умные модели сохраняют контекст на протяжении более длинных реализаций, лучше обнаруживают переиспользование кода, строже следуют правилам конституции и принимают более сильные архитектурные решения.

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

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

Через множество реализаций мы определили две эффективные стратегии для исправления ошибок рабочего процесса в Spec Kit:

• Итерируйте для исправления мелких отклонений: Перезапускайте ту же команду для регенерации частичных выходных данных при работе с проблемами ограниченного объема, такими как уточнение спецификаций, уточнение граничных случаев или корректировка мелких деталей дизайна. Итерация помогает выровнять выходные данные, не нарушая последующие фазы. Будьте избирательны, однако. Рутинное техническое обслуживание (например, чистка кода или депрекация старых API) редко выигрывает от Spec Kit. Для таких задач локальные инструменты или режим агента Copilot быстрее и точнее. Фокусируйте Spec Kit на средних и крупных функциях, где важны структура дизайна и контекст.

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

Эмпирическое правило: После трех или четырех итеративных попыток на одном артефакте прекратите исправлять и перезапустите фазу. Свежий контекст часто является самым чистым путем к восстановлению целостности кода и архитектуры.

Что дальше? Создавайте надежные инженерные функции со Spec Kit

Spec Kit - это не магия. Это серьезный инженерный инструмент, который вознаграждает подготовку, а не слепое доверие. С правильной настройкой: четкой конституцией, сильной архитектурой и исполнением на уровне задач, он делает разработку с помощью ИИ измеримой, предсказуемой и масштабируемой. Реальный сдвиг не в устранении людей, а в переопределении их роли. Spec Kit дает ИИ структуру, необходимую для поведения как части команды, а не генератора кода. Он превращает хорошую инженерную дисциплину в повторяемые, готовые к ИИ рабочие процессы.

UPD: Попробовал OpenSpec - мне ближе.