Spec-Driven Dev на практике

Попробовал два инструмента для Spec-Driven Development на своём pet project — delta-farmer (51 файл, 12k строк кода). Сравнивал spec-kit и cc-thingz: прогнал каждый через два кейса — аналитику по безопасности и обычный coding.

Инструменты

spec-kit (github) — open source тулкит для Spec-Driven Development. Помогает сосредоточиться на product scenarios и предсказуемом результате вместо vibe coding с нуля; работает поверх разных coding-агентов, генерирует под каждый этап отдельные файлы.

cc-thingz (github) — набор skills для Claude Code, который ставится через plugins / marketplace api. По сути это уже готовый workflow внутри Claude, а не отдельная внешняя обвязка над разными агентами.

Setup, workflow и артефакты

spec-kit задуман как более универсальная штука под разных агентов, но за это платишь отдельной CLI-обвязкой, своими шаблонами и своей структурой файлов. Flow у него устроен как последовательность отдельных команд: /speckit-specify -> /speckit-plan -> /speckit-tasks -> /speckit-implement, плюс отдельно /speckit-clarify для уточнения спеки. На одну задачу он создаёт несколько файлов.

Отдельная проблема spec-kit — папка .specify. Это его внутренняя служебная структура, в которой он хранит часть своих данных и метаданных по workflow. Непонятно, что из этого нужно добавлять в git, а что не нужно. В документации я не нашёл ни явных рекомендаций по этому поводу, ни внятных best practices для командной работы.

spec-kit также вставляет ссылку на текущую задачу прямо в CLAUDE.md / AGENTS.md. Любая новая Claude-сессия сразу видит её и работает в контексте этой задачи — просто поговорить по проекту или параллельно спланировать что-то другое уже не выйдет.

cc-thingz в этом смысле проще: он сразу завязан на Claude Code и ставится в его экосистему как набор skills. Pipeline у него тоже фиксированный: /brainstorm -> /plan:make -> /plan:review -> /plan:exec, но ощущается проще. На одну задачу у него получается один файл.

Планирование

У spec-kit планирование разбито на несколько отдельных команд. Сначала запускается /speckit-specify <task-description>: инструмент анализирует поставленную задачу, смотрит на исходный код, иногда задаёт уточняющие вопросы, на которые отвечать нужно в формате quiz в чат-режиме — буквально отправить букву A / B / C или свой вариант ответа (без интерактива, как в plan-mode).

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

Следующий этап — /speckit-plan. Агент по сгенерированному ранее описанию пытается написать техническую постановку задачи. Процесс тот же: генерация, ревью, комментарии — и так до удовлетворительного результата.

Финальная команда планирования — /speckit-tasks. Она раскладывает основную задачу на подзадачи. Формат работы с агентом остаётся прежним. По сути весь flow у spec-kit устроен одинаково на каждом этапе: запускается команда, инструмент пишет файлы на диск, а дальше их приходится валидировать вручную.

В итоге внутри specs/<task-name>/ собирается структура файлов вроде spec.md, plan.md, tasks.md, research.md, data-model.md, checklists/requirements.md и прочего. Каждый следующий этап дописывает туда новые файлы или обновляет старые, поэтому на одну задачу быстро нарастает большой объём текста, который нужно читать и валидировать руками.

Также есть /speckit-clarify — побрейнштормить решение перед написанием технической задачи и перед декомпозицией.

У cc-thingz процесс выглядит по-другому. Всё начинается с /brainstorm: после описания задачи инструмент задаёт вопросы в интерактивном режиме. Там можно выбрать готовый вариант ответа или ввести свой, то есть это не просто переписка в чате, а работа через меню с готовыми опциями (как в plan-mode).

После /brainstorm агент сразу предлагает следующие шаги: продолжить планирование, проверить результат вручную, отдать его на авторевью или сохранить. Если выбрать авторевью, дальше подключаются другие агенты, которые сами проверяют план, ищут в нём проблемы и вносят правки. За счёт этого значительная часть ревью встроена прямо в flow, ещё до ручной проверки.

Дальше можно либо сразу продолжить работу из того же окна, либо сохранить файл и вернуться к нему позже через /plan:make <file>. На этом этапе агент дописывает в файл технический план и список подзадач. Всё это собирается в один Markdown-файл в docs/tasks/, и новая информация просто дописывается в конец.

После этого агент снова предлагает варианты действий в интерактивном режиме: можно ещё раз прогнать план через ревью, сохранить его или сразу перейти к реализации. Когда работа по задаче заканчивается, файл перемещается в docs/tasks/completed. За счёт того, что всё живёт в одном файле, здесь проще смотреть diff, проще читать изменения и не нужно каждый раз думать, какой файл открыть.

Выполнение задач

У spec-kit реализация запускается командой /speckit-implement specs/<spec>, после чего агент начинает работать над задачей и писать код.

У cc-thingz реализация запускается через /plan:exec. Её можно запустить с файлом в новой сессии или сразу продолжить после этапа планирования. Дальше агент последовательно идёт по подзадачам из плана, пишет код, по ходу работы дописывает тесты под свою реализацию и сам же их запускает для проверки результата, а в конце прогоняет всё через дополнительное ревью другим агентом.

Задача 1. Supply chain hardening

Python-проект для автоматизированной торговли, распространяется через git clone + uv run. Зависимости описаны в pyproject.toml через >=-диапазоны, uv.lock не закоммичен, поэтому при клонировании пользователи получают непонятные версии с PyPI без каких-либо гарантий.

Нужно было понять, как правильно защитить такой проект от supply chain проблем, без внешних сервисов типа Renovate или Dependabot. Какие файлы коммитить, как пинить версии и как потом обновлять их (примером взять то, как это реализовано в pnpm), как быть уверен что все депсы безопасны перед релизом. Плюс был дан референс на best practices.

Планирование

Сначала я дал обоим инструментам одно и то же описание задачи и запустил первый проход, чтобы они подумали над ней. У cc-thingz это был /brainstorm, у spec-kit — /speckit-specify.

Дальше предложенное агентом решение прогнал через агента-критика. У spec-kit для этого есть /speckit-clarify, а cc-thingz после первого прохода сам предложил три варианта: закоммитить план, сделать ревью самому или отдать ревью другому агенту. Выбрал последний вариант.

У cc-thingz в итоге получился понятный план. Задача свелась к четырём изменениям: закоммитить uv.lock — это даёт воспроизводимые установки и SHA256-верификацию; добавить exclude-newer = "7 days" — блокирует пакеты, опубликованные меньше 7 дней назад (защита от timing attacks в духе LiteLLM); включить only-binary = [":all:"] — запрещает выполнение setup.py при установке, только wheels; добавить uv audit для CVE-сканирования перед релизами.

У spec-kit на этапе /speckit-clarify агент начал задавать странные вопросы в стиле "что делать, если uv audit запущен в offline среде – пропускать PR или нет".

Он также зачем-то предложил отправлять нотификации про CVE через telegram-интеграцию в коде. Эта интеграция используется для trade start / stop, то есть робот увидел кусок кода, не понял, для чего он нужен, и смешал в одну кучу внутреннюю логику приложения и внешний security tooling.

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

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

Реализация

Сама задача простая, поэтому реализовать её по плану обоим было легко. Что напланировали, то и сделали.

Результат cc-thingz получился понятным, его легко читать и не страшно использовать дальше. spec-kit использовал непонятные пакеты, поэтому результат даже не запускался. Работает ли то, что он сделал — не проверял: результату не доверял и запускать не стал.

Задача 2. Реальная coding-задача

Описание задачи (580 слов, 5 кб): что нужно сделать, где брать данные и как проверить результат. Конкретные файлы намеренно не называл — всё на откуп разработчику, как в реальной жизни.

Коротко суть: есть три источника данных. Общая история сделок пользователя (1), история сделок провайдера по всем пользователям (2) и последние несколько дней сделок у провайдера по конкретному пользователю (3). Нужно скачать источник 2 и 3, отфильтровать по ним источник 1, закешировать это на диск и встроить в вывод программы вместо того, что в ней сейчас (по сути там просто источник 1).

Планирование

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

cc-thingz задал несколько нормальных вопросов по реализации, после чего предложил план. Дальше он дал два варианта: проверить план самому или отдать на проверку другому агенту. Выбрал второй вариант — получил файл на ревью, внёс несколько мелких правок и закоммитил план. Получился один файл на 10.6 Кб, 158 строк, 1479 слов и 7 задач. Плюс он спросил про вещи, которые я упустил в описании задачи. Например, как хранить кеш на диске и как выглядят типы данных. В этой задаче баг как раз был в том, что два источника по-разному представляют одни и те же данные: в одном месте 1000, в другом 1000.0, и напрямую это нормально не маппится.

spec-kit никаких дополнительных вопросов сам не задавал. После трех команд (specify / plan / tasks) уже лежала целая пачка файлов, которые нужно было читать и проверять: 40.5 Кб, 737 строк, 4761 слово и 13 задач. Читать это тяжело даже один раз, не говоря о том, что эти файлы меняются в процессе ревью.

Реализация

cc-thingz запускался не напрямую, а через ralphex: https://github.com/umputun/ralphex. По сути это Claude / Codex в YOLO mode в Docker. В моём случае команда была такая: ralphex --serve docs/plans/20260515-onyx-fills-filtering.md. Работает оно долго: на полный проход уходит час-полтора.

spec-kit запускался через /speckit-implement 002 (где 002 — номер задачи) в новой сессии.

Когда ralphex уже делал последнюю задачу, у меня закончился пяти-часовой лимит. Над какой задачей в этот момент работал spec-kit, так и не понял, потому что свои файлы во время работы он не обновлял. У cc-thingz в этом смысле было проще: он создавал коммит после каждого изменения, поэтому полная история осталась.

Возобновить работу в обоих инструментах можно по-разному. У spec-kit это обычная Claude-сессия: когда лимит сбросится, можно писать дальше в том же окне. Либо её можно закрыть и открыть заново через --resume. У ralphex иначе: его можно вызвать заново с тем же файлом задачи, и он сам понимает, где в прошлый раз остановился, потому что по ходу работы расставляет чекбоксы в todo-листе. Поэтому он продолжает выполнение с последней точки остановки. Понятно, что без ralphex — cc-thingz тоже работает как обычная Claude-сессия.

Результат

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

У cc-thingz проблема была в том, что агент не уточнил у меня всю важную структуру данных на этапе планирования и не сходил в источник данных, чтобы взять себе sample, хотя я писал, что эти данные публичные. В итоге он интерпретировал поле Time как timestamp, а не как строку в ISO-формате, из-за чего данные не парселись. Других проблем с запуском не было, но данные считались неправильно. После нескольких десятков минут дебага в отдельной Claude-сессии (не знаю, как подключиться к логам ralphex, поэтому открыл новую) выяснилось, что робот вызвал API с неверными параметрами. Из-за этого часть данных не удавалось правильно отфильтровать по источнику.

У spec-kit на этапе запуска были другие ошибки: он решил, что отчет нужно считать за 2025 год, хотя я явно указывал, что считать нужно с 1 января 2026 года. В итоге он очень долго скачивал данные и влетел в rate limit. Дальше была ошибка с lock/unlock при записи в файлы. Данные он решил хранить отдельным файлом на каждую дату, хотя я просил сохранять это в один файл и дописывать его при обновлении. После запуска — та же проблема с неправильными цифрами: пришлось идти в чат, включать дебажные логи, разбираться и исправлять.

Оба написали тесты. У cc-thingz они проходят. У spec-kit — нет, то есть он их не запускал и корректность сгенерированного кода не проверил.

Посмотреть на код, task-файлы и организацию изменений можно в диффах: spec-kit (11 файлов, 1206 строк) и cc-thingz (9 файлов, 760 строк). У spec-kit изменений больше, но значительная часть — это его собственные spec-файлы, а не код. cc-thingz поработал плотнее с кодовой базой.

Итог

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

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

Мой финальный отзыв:

spec-kit — инструмент с понятной идеей, но неудобный в работе. Генерирует много файлов, которые нужно читать и ревьюить вручную. На планирование ушло около часа, потом ещё час работал агент, потом ещё час на разбор и доработку того, что не заработало. Тесты написал, но не запустил. Артефактов оставил больше, чем кода. Для несложной задачи это избыточно.

cc-thingz — работать с ним проще. Один файл, интерактивный режим, встроенное ревью. Тот же ритм по времени: час на спеку, час на реализацию, час на доработку. Тесты написал и запустил. Ошибки были, но причина понятна — агент не уточнил структуру данных заранее и не взял sample из публичного API. Результату можно доверять больше, хотя идеально тоже не вышло.

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

Полные диффы по обеим задачам: spec-kit, cc-thingz.

Несколько мыслей напоследок

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

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

cc-thingz с ralphex стоит рассматривать для действительно простых задач. Расписал задачу в файл, запустил — и оно само. Для этого сценария это выглядит как реально рабочая вещь. Но у приложения тогда должна быть хорошая тестируемость и понятная структура.