Вайб-кодинг не масштабируется
Модель пишет код быстрее человека — и так же быстро уезжает не туда, если требования нигде не зафиксированы. specaflow меняет роль разработчика: не печатать код, а принимать решения. Каждый шаг маленький, проверяемый и утверждается вами.
ИИ без процесса
- ✖ Требования живут в чатах — и умирают вместе с сессией.
- ✖ Модель генерирует гигантский PR, который никто не в силах прочитать.
- ✖ Противоречия в требованиях всплывают уже в коде — самое дорогое место для правок.
- ✖ Смена модели или разработчика — потеря всего контекста.
- ✖ Почему сделано именно так — не помнит уже никто.
specaflow
- ✔ Требования — в файлах и git: переживают любую сессию и смену модели.
- ✔ Вы утверждаете короткий понятный diff на каждом гейте, а не разбираете месиво.
- ✔ Фаза analyze сверяет спеку, план и задачи — противоречия ловятся на бумаге.
- ✔ Другой человек или другая модель продолжит с того же места — контекст в specs/.
- ✔ История решений — в плане, конституции и ретро, а не в чьей-то памяти.
Весь цикл на одном примере
Приложение «Трекер привычек» — от идеи до закоммиченного кода. Кадры листаются сами, точками можно ходить вручную.
Два уровня: проект и фича
Сначала проект получает фундамент — план, конституцию, дорожную карту. Затем каждая фича проходит собственный цикл из девяти фаз на отдельной git-ветке.
конвейер проекта
цикл фичи — 9 фаз
Вы и ИИ — у одной доски
Идею проще нарисовать, чем описать. Рядом с драфт-чатом открывается общее полотно — и рисуют на нём обе стороны. Вы набрасываете схему или вставляете скриншот с пометками; при отправке сообщения ИИ получает и структуру доски, и её снимок (vision). А отвечает тем же: «набросал архитектуру на доске — посмотрите».
ИИ рисует структурно
Модель не двигает пиксели — она шлёт операции: add_node, connect, insert_between, group… Координаты сервер считает сам, модель ссылается на элементы по подписи. После каждого батча — свежая проекция доски и линт-находки: модель сама проверяет, что нарисовала то, что хотела.
Ваши элементы неприкосновенны
Протокол вежливости зашит в инструмент: свои узлы ИИ переставляет свободно, а нарисованное вами трогает только после явного разрешения — спросив через уточняющий вопрос. Общая доска не превращается в «ИИ всё переделал».
Доска — тоже файл
Сцена — обычный excalidraw-файл рядом с черновиком, автосохранение. Как и весь драфт-чат: стенограмма «## You / ## specaflow» лежит в markdown и живёт в git вместе с проектом.
Контроль без микроменеджмента
ИИ работает, вы принимаете решения. Ни один артефакт не попадает в проект без вашего approve.
Гейт после каждой фазы
Фаза записала артефакт — работа останавливается. Вы смотрите diff по файлам: approve = git-коммит, reject с комментарием = фаза переделает с учётом замечаний.
Файлы — источник истины
Никакой базы данных: статус каждой фичи пересчитывается из specs/ при каждом запросе. Правьте спеки любым редактором или агентом — дашборд следует за файлами.
Код не покидает машину
Сервер работает локально, с локальной моделью — полностью офлайн. Подойдёт для закрытых контуров: наружу не уходит ни строки, если вы сами не подключили облачный API.
Git-дисциплина
Каждая фича — на своей ветке. В историю git пишет только ваш approve на гейте: никаких скрытых коммитов, вся работа ИИ прозрачна и откатываема.
Когда реальность не совпала с планом
Главная болезнь ИИ-кодинга — тихий дрейф: план говорит одно, код делает другое, и документы врут уже через неделю. В specaflow отступление от плана — это протокол, а не случайность. Ни одна девиация не появляется без вашего одобрения, и ни одна одобренная не теряется.
Так это выглядит
Настоящие снимки интерфейса на демо-проекте «Трекер привычек» — том самом, что в анимации выше. В шапке — менеджер проектов: переключение между проектами и подключение новых, не выходя из specaflow.
Менеджер проектов — с него начинается работа
Один запущенный specaflow ведёт все ваши проекты: переключение из шапки, подключение существующей папки (brownfield подхватывается как есть) или создание новой с инициализацией.
Features — фичи по слоям, статус выведен из файлов
Каждая карточка — фича с полосой фаз: зелёное пройдено, янтарное — в работе. Слои сворачиваются; сверху всегда актуальный.
Фича изнутри — фазы, запуск, документы
Фаза запускается одной кнопкой, рядом — заметки для агента. Ниже все документы фичи: spec, plan, research, tasks — с историей правок.
Briefs — очередь будущих фич по трекам
Брифы со статусами и зависимостями: у READY-брифа загорается ⚡ start specify — из него рождается фича.
Собственный AI-харнес, а не обёртка
Внутри specaflow — агентный харнес, написанный с нуля на Go (только стандартная библиотека, ни одного стороннего пакета). Он ведёт модель по фазам через фиксированный набор из дюжины инструментов и берёт на себя всё то, из-за чего «просто подключить LLM» не работает в проде.
Инструменты — фиксированный набор
Никакого «дай модели всё и надейся»: набор маленький, известный заранее, права зависят от фазы.
- ask_clarification — фирменный инструмент уточнений: один вопрос, 2–5 кликабельных взаимоисключающих вариантов, ровно один помечен «recommended», поле свободного ответа всегда рядом. Лимит на фазу, чтобы модель не превращала работу в анкету. Из тупика агент выходит вопросом, а не фантазией.
- board_apply — восемь структурных операций рисования на общей доске; сервер сам раскладывает геометрию и возвращает модели проекцию с линт-находками.
- run_shell — белый список команд; всё вне списка ждёт вашего разрешения, у команд жёсткий таймаут.
- search_project — поиск по смыслу по всем документам проекта: один вызов вместо цепочки grep → read_file. Как он устроен — блок ниже.
Защита от реальных LLM-болезней
Каждый механизм появился из настоящего сбоя — и после него этот класс сбоев перестал убивать раны.
- ⚡Circuit breaker: тот же самый вызов упал несколько раз подряд — харнес перестаёт его выполнять и требует сменить подход или спросить разработчика.
- ⚡Детектор петель: генерация выродилась в повторение — стрим обрывается, модель получает жёсткую коррекцию «одно конкретное действие прямо сейчас»; после N коррекций ран честно падает.
- ⚡Сторожевой таймер стрима и повтор раундов на сетевых обрывах — многочасовой implement не умирает от одного моргнувшего соединения.
- ⚡Компактизация истории: старые объёмные результаты инструментов сворачиваются — длинные раны влезают в контекст локальных моделей.
- ⚡Спасение обрезанных ответов: tool call, оборванный лимитом токенов, чинится, а не выбрасывается — написанный артефакт не теряется.
- ⚡Тест провайдера: «проверить соединение» шлёт пробный tool call и говорит заранее, потянет ли эта модель работу: нативные инструменты, отделение reasoning, каталог моделей.
Плюс журнал каждого рана на диске, лимиты раундов и веб-запросов, контроль наполнения контекстного окна с предупреждением агенту — скучная сантехника, без которой агенты не доживают до конца фазы.
Проект в контексте с первого токена
Обычный агент начинает фазу вслепую и десятки раундов листает файлы, наполняя контекст тем, что успел найти. В specaflow встроен гибридный поиск по всему корпусу проекта — спецификациям, планам, брифам, конституции, документации: BM25 + вектора + Reciprocal Rank Fusion, написан с нуля на стандартной библиотеке Go. Без векторной БД и внешних сервисов: индекс — кэш в .specaflow/index/, целиком выводится из файлов, изменения подхватываются сверкой sha256 — в том числе после переключения git-ветки.
Фазы стартуют начитанными
Перед стартом фазы харнес сам достаёт релевантный срез корпуса и кладёт его в стартовый промпт (бюджет ~3000 токенов). Меньше раундов «прочитаю ещё файл», меньше токенов на перечитывание одного и того же — а analyze видит кросс-фичевые связи, которых нет в артефактах его фичи.
Поиск по смыслу — и по букве
Инструмент search_project понимает и «как у нас устроена ротация токенов», и точный идентификатор вроде T029: вектора ищут смысл, BM25 — букву, RRF сливает обе выдачи. Каждый сниппет подписан путём, заголовком и строками — модель обязана перечитать источник, прежде чем на него опереться.
Опционален и офлайн
Эмбеддинги — любой OpenAI-совместимый эндпоинт, включая локальные Ollama / LM Studio / llama.cpp: проект не покидает машину. Эмбеддер недоступен — индекс работает лексически и довекторизуется, когда тот вернётся. Тогл выключен — specaflow работает ровно как раньше: RAG не может сломать ни одну фазу.
[plan] pre-seed: 11 чанков · 2 987 токенов → <retrieved_context>
[agent] search_project("ротация refresh-токенов")
[hits] specs/210-auth/plan.md · «Token rotation» · lines 84–112 · +7
Почему бумага раньше кода
Чем позже найдена ошибка, тем дороже её исправить. specaflow сдвигает поиск ошибок влево — в спецификацию и план, где правка стоит минуты, — и режет ревью на порции, которые реально прочитать.
Стоимость исправления ошибки
относительно правки на этапе спецификации*
* классическая индустриальная оценка (Boehm; IBM Systems Sciences Institute)
Что вы читаете на ревью
строк за один присест, типичная фича
гейты specaflow дробят ту же фичу на 9 коротких проверяемых diff'ов
Один бинарь. Одна команда.
specaflow — единый исполняемый файл на Go без внешних зависимостей: ни Docker, ни Node, ни Python. Скачали, запустили — открылось окно со встроенным менеджером проектов: переключайтесь между проектами, подключайте новые и инициализируйте их, не выходя из интерфейса. Brownfield-проект с уже существующими фичами подхватывается как есть, ничего не перезаписывается.
[web] http://localhost:4820 — окно открыто
[projects] 3 проекта · активный: habit-tracker
[run] plan → артефакт записан
[gate] ожидает ваш approve · diff: 2 файла
Любая OpenAI-совместимая модель
Локальный инференс или облачный API — на выбор. Встроенный тест соединения проверит, что провайдер держит tool calls.
Сколько стоит разработка — в цифрах
Каждый ран фазы оставляет след в вечном журнале: модель, токены, раунды, ретраи, машинное время и сколько ран ждал ваших ответов. Вкладка «статистика» собирает из этого живой дашборд — плитки, бары по фазам, донат токенов по моделям, цикл-таймы фич — на чистом SVG, без единой внешней библиотеки, с фильтром по периоду и обновлением в реальном времени на каждом гейте.
Машинное время ≠ календарное
Ожидание разработчика — ответы на клэрифаи, паузы перед решением на гейте — считается отдельно и вычитается. Видно честную скорость: сколько работала модель, а сколько задача лежала на вас. Ночь до утреннего approve не портит метрику.
Эффективность моделей
Каждый ран атрибутирован моделью. Таблица по совокупным критериям: средние раунды, ретраи, доля reject на гейтах, токены, время на фазу — видно, какая модель дешевле и надёжнее доводит работу до approve, а какая гоняет инструменты по кругу.
Прошлое достраивается из git
Проекты, начатые раньше, ничего не теряют: каждый approve всегда был коммитом specaflow: <фаза> <фича> — из истории восстанавливаются времена фаз, финализации и возраст проекта. Никакой базы: append-журнал плюс git.
Фильтр по периоду пересчитывает всё мгновенно — данные уже на клиенте. Закрыли гейт — цифры обновились сами по SSE.
В планах
- 🧬RAG по исходному коду — этап 2 встроенного поиска: чанкинг исходников по границам функций, фильтр kind:code — implement и verify начнут стартовать с релевантным срезом кода, как документные фазы уже стартуют со срезом спек.
- 🪟Нативное окно — режим отдельного приложения без вкладки браузера (WebView2 на Windows), тот же единый бинарь.