--- title: Spec-Driven Development на практике slug: spec-driven-dev date: 2026-05-20 taxonomies: tags: ["tools", "ai"] --- Попробовал два инструмента для Spec-Driven Development на своём pet project — [delta-farmer](https://github.com/vladkens/delta-farmer) (51 файл, 12k строк кода). Сравнивал `spec-kit` и `cc-thingz`: прогнал каждый через два кейса — аналитику по безопасности и обычный coding. ## Инструменты **spec-kit** ([github](https://github.com/github/spec-kit)) — open source тулкит для Spec-Driven Development. Помогает сосредоточиться на product scenarios и предсказуемом результате вместо vibe coding с нуля; работает поверх разных coding-агентов, генерирует под каждый этап отдельные файлы. **cc-thingz** ([github](https://github.com/umputun/cc-thingz)) — набор 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 `: инструмент анализирует поставленную задачу, смотрит на исходный код, иногда задаёт уточняющие вопросы, на которые отвечать нужно в формате quiz в чат-режиме — буквально отправить букву `A` / `B` / `C` или свой вариант ответа (без интерактива, как в plan-mode). После этого `spec-kit` пишет файлы на диск, и дальше начинается ручное ревью. Нужно открыть эти файлы, прочитать их и понять, насколько адекватно агент описал задачу. Если что-то не нравится, нужно написать об этом в чате — инструмент генерирует обновлённую версию. Следующий этап — `/speckit-plan`. Агент по сгенерированному ранее описанию пытается написать техническую постановку задачи. Процесс тот же: генерация, ревью, комментарии — и так до удовлетворительного результата. Финальная команда планирования — `/speckit-tasks`. Она раскладывает основную задачу на подзадачи. Формат работы с агентом остаётся прежним. По сути весь flow у `spec-kit` устроен одинаково на каждом этапе: запускается команда, инструмент пишет файлы на диск, а дальше их приходится валидировать вручную. В итоге внутри `specs//` собирается структура файлов вроде `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 `. На этом этапе агент дописывает в файл технический план и список подзадач. Всё это собирается в один Markdown-файл в `docs/tasks/`, и новая информация просто дописывается в конец. После этого агент снова предлагает варианты действий в интерактивном режиме: можно ещё раз прогнать план через ревью, сохранить его или сразу перейти к реализации. Когда работа по задаче заканчивается, файл перемещается в `docs/tasks/completed`. За счёт того, что всё живёт в одном файле, здесь проще смотреть diff, проще читать изменения и не нужно каждый раз думать, какой файл открыть. ### Выполнение задач У `spec-kit` реализация запускается командой `/speckit-implement specs/`, после чего агент начинает работать над задачей и писать код. У `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](https://github.com/lirantal/pypi-security-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](https://github.com/vladkens/delta-farmer/compare/0fd999fa...1e62367e) (11 файлов, 1206 строк) и [cc-thingz](https://github.com/vladkens/delta-farmer/compare/5f92ecfa...9692d9f3) (9 файлов, 760 строк). У `spec-kit` изменений больше, но значительная часть — это его собственные spec-файлы, а не код. `cc-thingz` поработал плотнее с кодовой базой. ## Итог Перед тем как тестировать оба инструмента, я прогнал вторую задачу самостоятельно — просто в режиме диалога с Claude в edit-режиме, без какой-либо спеки. Нормальной постановки задачи у меня тогда ещё не было: я просто не понимал, где брать данные и как они устроены. Поэтому весь разбор шёл прямо в чате — дебажили вместе с агентом, смотрели что приходит из API, разбирались в структуре. На это ушло часа два-три. Когда задача стала понятна, я уже мог нормально её сформулировать — и именно эту формулировку потом дал обоим инструментам. **Мой финальный отзыв:** **`spec-kit`** — инструмент с понятной идеей, но неудобный в работе. Генерирует много файлов, которые нужно читать и ревьюить вручную. На планирование ушло около часа, потом ещё час работал агент, потом ещё час на разбор и доработку того, что не заработало. Тесты написал, но не запустил. Артефактов оставил больше, чем кода. Для несложной задачи это избыточно. **`cc-thingz`** — работать с ним проще. Один файл, интерактивный режим, встроенное ревью. Тот же ритм по времени: час на спеку, час на реализацию, час на доработку. Тесты написал и запустил. Ошибки были, но причина понятна — агент не уточнил структуру данных заранее и не взял sample из публичного API. Результату можно доверять больше, хотя идеально тоже не вышло. На то, чтобы прогнать оба инструмента на двух задачах и написать эту статью, у меня ушло два дня. Полные диффы по обеим задачам: [spec-kit](https://github.com/vladkens/delta-farmer/compare/e61bc2c0...1e62367e), [cc-thingz](https://github.com/vladkens/delta-farmer/compare/e61bc2c0...9692d9f3). ## Несколько мыслей напоследок Работать с агентами в таком режиме в целом удобно, но когнитивная нагрузка оказывается довольно высокой. Нужно заранее грамотно сформулировать задачу, внимательно прочитать всё, что агент для себя написал на этапе планирования, и убедиться, что он учёл все важные аспекты. Если это сделано хорошо, дальше он работает достаточно стабильно. Теоретически в это время можно писать спеку для следующей задачи — но пока это скорее иллюзия, чем реальный параллелизм. Идея полностью отдавать написание кода агенту мне не кажется однозначно хорошей. Во-первых, ты плохо понимаешь то, что в итоге написано. Во-вторых, агент плохо принимает самостоятельные решения — без явного направления со стороны человека он нередко делает логические ошибки или уходит не туда. По крайней мере, у меня так. Задачи в режиме диалога решаются быстрее: ты понимаешь, что происходит с кодом, контролируешь ход решения — и агент делает меньше ошибок. `cc-thingz` с `ralphex` стоит рассматривать для действительно простых задач. Расписал задачу в файл, запустил — и оно само. Для этого сценария это выглядит как реально рабочая вещь. Но у приложения тогда должна быть хорошая тестируемость и понятная структура.