Зачем нужен specaflow

Управляемая разработка вместо непрозрачного чата

Посмотрите, какую проблему решает SF и на каких принципах строится работа.

Когда одного чата уже недостаточно

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

💬

ИИ без процесса

✖ Требования живут в чатах — и умирают вместе с сессией.
✖ Модель генерирует гигантский PR, который никто не в силах прочитать.
✖ Противоречия в требованиях всплывают уже в коде — самое дорогое место для правок.
✖ Смена модели или разработчика — потеря всего контекста.
✖ Почему сделано именно так — не помнит уже никто.

📋

specaflow

✔ Требования — в файлах и git: переживают любую сессию и смену модели.
✔ Вы проверяете небольшую понятную порцию изменений после каждого этапа.
✔ Фаза analyze сверяет спеку, план и задачи — противоречия ловятся на бумаге.
✔ Другой человек или другая модель продолжит с того же места — контекст в specs/.
✔ История решений — в плане, конституции и ретро, а не в чьей-то памяти.

До первого промпта

Замысел превращается в контекст проекта

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

specaflow · мастер-опросник проекта

Мастер-опросник specaflow: выбор типа продукта, прогресс по 21 вопросу и этапы Infrastructure, Backend, Design и Frontend

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

Весь цикл на одном примере

Приложение «Трекер привычек» — от идеи до закоммиченного кода. Кадры листаются сами, точками можно ходить вручную.

текущий этаппройденный путьподтверждённый результат

Драфт-чат · режим «у доски»

Вы и ИИ — у одной доски

Идею проще нарисовать, чем описать. Рядом с драфт-чатом открывается общее полотно — и рисуют на нём обе стороны. Вы набрасываете схему или вставляете скриншот с пометками; при отправке сообщения ИИ получает и структуру доски, и её снимок (vision). А отвечает тем же: «набросал архитектуру на доске — посмотрите».

drafts · Трекер привычек — доска + чат

Драфт-чат specaflow с общей доской: архитектурная схема React PWA → Go API → SQLite, нарисованная ИИ, под ней диалог

✏️

ИИ рисует структурно

Модель не двигает пиксели — она шлёт операции: add_node, connect, insert_between, group… Координаты сервер считает сам, модель ссылается на элементы по подписи. После каждого батча — свежая проекция доски и линт-находки: модель сама проверяет, что нарисовала то, что хотела.

🤝

Ваши элементы неприкосновенны

Протокол вежливости зашит в инструмент: свои узлы ИИ переставляет свободно, а нарисованное вами трогает только после явного разрешения — спросив через уточняющий вопрос. Общая доска не превращается в «ИИ всё переделал».

📄

Доска — тоже файл

Сцена — обычный excalidraw-файл рядом с черновиком, автосохранение. Как и весь драфт-чат: стенограмма «## You / ## specaflow» лежит в markdown и живёт в git вместе с проектом.

Контроль без микроменеджмента

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

🚦

Проверка после каждого этапа

Этап подготовил результат — работа останавливается. Вы смотрите изменения по файлам: принимаете их и сохраняете в Git либо возвращаете на доработку с пояснением.

📁

Файлы — источник истины

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

🔒

Код не покидает машину

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

🌿

Git-дисциплина

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

Когда реальность не совпала с планом

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

implement упёрся в реальность

Версия пакета не существует, команда падает, подход из плана не работает. Правило жёсткое: девиация — никогда не решение модели. Стоп, вопрос разработчику с вариантами: «применить фикс (recommended)» / «пропустить задачу» / «остановить ран».

Харнес не даст «починить молча»

Слабые модели любят «исправить и задокументировать» без спроса. Поэтому поверх промпта стоит жёсткий слой: правки plan.md отклоняются, пока вы не ответили хотя бы на один вопрос в этом ране.

Одобрено — сразу на диск

Ещё до продолжения кодинга: тег [deviation] у задачи в tasks.md и строка в «## Deviations» плана — «план: что предполагалось → факт: что сделали; причина». Если ран умрёт — одобрение уже на диске.

verify отличает девиацию от дрейфа

Код, совпадающий с записанной девиацией, — норма, «чинить обратно по плану» его нельзя. А вот незаписанное расхождение кода с документами — ровно тот тихий дрейф, ради ловли которого verify и существует.

↻

reconcile возвращает согласованность

Дашборд считает несинхронизированные девиации и предлагает запустить reconcile: каждая запись из «## Deviations» пропагируется в прозу плана, формулировки задач и — если изменилось видимое поведение — в спеку, после чего помечается [synced]. Записи никогда не удаляются: это история решений. Документы снова говорят правду — следующая фаза стартует от согласованного состояния.

Так это выглядит

Настоящие снимки интерфейса на демо-проекте «Трекер привычек» — том самом, что в анимации выше. В шапке — менеджер проектов: переключение между проектами и подключение новых, не выходя из specaflow.

Менеджер проектов — с него начинается работа

specaflow — библиотека проектов

Менеджер проектов specaflow: библиотека из трёх проектов, создание нового и подключение существующего

Один запущенный specaflow ведёт все ваши проекты: переключение из шапки, подключение существующей папки без перезаписи или создание нового проекта.

Features — фичи по слоям, статус выведен из файлов

specaflow · habit-tracker — localhost:4820

Борд фич specaflow: группы по слоям Frontend/Backend/Infrastructure, у каждой фичи полоса фаз

Каждая карточка — фича с полосой фаз: зелёное пройдено, янтарное — в работе. Слои сворачиваются; сверху всегда актуальный.

Фича изнутри — фазы, запуск, документы

specs/101-habit-streaks — implement 57%

Раскрытая карточка фичи: фаза implement 57%, кнопка запуска, вкладки spec.md / plan.md / tasks.md

Фаза запускается одной кнопкой, рядом — заметки для агента. Ниже все документы фичи: spec, plan, research, tasks — с историей правок.

Briefs — очередь будущих фич по трекам

specaflow · habit-tracker — briefs

Вкладка briefs: карточки брифов по трекам со статусами и зависимостями

Брифы со статусами и зависимостями: у READY-брифа загорается ⚡ start specify — из него рождается фича.

Всегда рядом

Спекки знает продукт и понимает текущий экран

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

Спекки

моргает, наблюдает за прогонами и меняет позу по состоянию

Спекки · вопрос с поиском в интернете

Ассистент Спекки отвечает на вопрос об актуальных версиях Python на основе данных из интернета

контекст · что сейчас на экране

Спекки объясняет текущий прогон: фичу, фазу tasks, модель и файлы, которые агент читает прямо сейчас

Контекст по запросу

«Что сейчас происходит?» — без пересказа руками

Вы включаете чип «что сейчас на экране», и Спекки получает снимок рабочего состояния. В примере он видит, что для 105-analyzer-agent идёт фаза tasks, знает выбранную модель и объясняет, какие файлы агент уже изучил.

✓контекст прикладывается явно и виден отдельным чипом;
✓ответ опирается на живое состояние прогона, а не на догадку;
✓чип можно снять одним кликом — следующий вопрос снова будет общим.

↔️

Разговор движется в обе стороны

Быстрый вопрос можно открыть в drafts и развить в полноценное обсуждение. И наоборот: разговор из drafts продолжается в компактном ассистенте — история и контекст не теряются при переходе.

📎

Контекст прикладываете вы

Без вложений Спекки отвечает как обычный советник. Одним нажатием можно показать ему текущий экран, активную фичу, вопрос фазы, журнал прогонов или файл — никакого скрытого гигантского промпта.

🛡️

Советник, а не второй пилот

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

Под капотом

Собственный AI-харнес, а не обёртка

Внутри specaflow — агентный харнес, написанный с нуля на Go (только стандартная библиотека, ни одного стороннего пакета). Он ведёт модель по фазам через фиксированный набор из дюжины инструментов и берёт на себя всё то, из-за чего «просто подключить LLM» не работает в проде.

Инструменты — фиксированный набор

Никакого «дай модели всё и надейся»: набор маленький, известный заранее, права зависят от фазы.

read_file list_files grep write_artifact edit_file ask_clarification board_apply write_file · implement run_shell · implement web_search / web_fetch search_project · RAG

ask_clarification — фирменный инструмент уточнений: один вопрос, 2–5 кликабельных взаимоисключающих вариантов, ровно один помечен «recommended», поле свободного ответа всегда рядом. Лимит на фазу, чтобы модель не превращала работу в анкету. Из тупика агент выходит вопросом, а не фантазией.
board_apply — восемь структурных операций рисования на общей доске; сервер сам раскладывает геометрию и возвращает модели проекцию с линт-находками.
run_shell — белый список команд; всё вне списка ждёт вашего разрешения, у команд жёсткий таймаут.
search_project — поиск по смыслу по всем документам проекта: один вызов вместо цепочки grep → read_file. Как он устроен — блок ниже.

Защита от реальных LLM-болезней

Каждый механизм появился из настоящего сбоя — и после него этот класс сбоев перестал убивать раны.

⚡Circuit breaker: тот же самый вызов упал несколько раз подряд — харнес перестаёт его выполнять и требует сменить подход или спросить разработчика.
⚡Детектор петель: генерация выродилась в повторение — стрим обрывается, модель получает жёсткую коррекцию «одно конкретное действие прямо сейчас»; после N коррекций ран честно падает.
⚡Сторожевой таймер стрима и повтор раундов на сетевых обрывах — многочасовой implement не умирает от одного моргнувшего соединения.
⚡Компактизация истории: старые объёмные результаты инструментов сворачиваются — длинные раны влезают в контекст локальных моделей.
⚡Спасение обрезанных ответов: tool call, оборванный лимитом токенов, чинится, а не выбрасывается — написанный артефакт не теряется.
⚡Тест провайдера: «проверить соединение» шлёт пробный tool call и говорит заранее, потянет ли эта модель работу: нативные инструменты, отделение reasoning, каталог моделей.

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

Встроенный RAG

Проект в контексте с первого токена

Обычный агент начинает фазу вслепую и десятки раундов листает файлы, наполняя контекст тем, что успел найти. В 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 не может сломать ни одну фазу.

[index] 94 файла · 739 чанков · bge-m3 · sha-сверка 40 мс
[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 делит ту же функцию на небольшие порции изменений, которые можно внимательно проверить

Гибкая конфигурация

Одна модель может делать всё. Или каждая — то, в чём сильна

SF разделяет не обязательные подключения, а три понятные роли. Можно назначить одну и ту же модель на все роли либо подобрать сочетание по качеству, скорости и стоимости.

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

Разбирает требования, задаёт вопросы, строит решения и проверяет согласованность документов. Здесь особенно важно качество рассуждения.

Создание результата

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

Помощник

Объясняет текущее состояние проекта и допустимые следующие действия. Работает только на чтение и не меняет проект за вашей спиной.

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

Zero Dependencies

Один бинарь. Одна команда.

specaflow — единый исполняемый файл на Go без внешних зависимостей: ни Docker, ни Node, ни Python. Скачали, запустили — открылось окно со встроенным менеджером проектов. Подключите существующую папку без перезаписи или создайте новый проект прямо в интерфейсе.

$ ./specaflow
[web] http://localhost:4820 — окно открыто
[projects] 3 проекта · активный: habit-tracker
[run] plan → артефакт записан
[review] ожидает решения · изменено 2 файла

Любая OpenAI-совместимая модель

Локальный инференс или облачный API — на выбор. Встроенный тест соединения проверит, что провайдер держит tool calls.

llama.cpp Ollama vLLM LM Studio OpenAI Anthropic Gemini GLM OpenRouter DeepSeek

🧠 Раздельные модели

Умная думает — планы, конституция, анализ. Быстрая пишет — спеки, задачи, код по готовым материалам. Экономия без потери качества.

🛡 Контроль исполнения

Shell-команды вне белого списка требуют вашего разрешения. Отступления от плана фиксируются только после вашего одобрения.

Метрики

Сколько стоит разработка — в цифрах

Каждый ран фазы оставляет след в вечном журнале: модель, токены, раунды, ретраи, машинное время и сколько ран ждал ваших ответов. Вкладка «статистика» собирает из этого живой дашборд — плитки, бары по фазам, донат токенов по моделям, цикл-таймы фич — на чистом SVG, без единой внешней библиотеки, с фильтром по периоду и обновлением в реальном времени на каждом гейте.

⏱

Машинное время ≠ календарное

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

🧪

Эффективность моделей

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

🕰

Прошлое достраивается из git

Проекты, начатые раньше, ничего не теряют: каждый approve всегда был коммитом specaflow: <фаза> <фича> — из истории восстанавливаются времена фаз, финализации и возраст проекта. Никакой базы: append-журнал плюс git.

specaflow · habit-tracker — статистика

статистика трудозатрат 7д 30д всё время

18двозраст проекта28.06.2026

46фазовых ранов41 ✓ · 5 ✕

14ч 20ммашинное времяработа модели, без ожиданий

6ч 05можидание разработчикаклэрифаи + гейты

18.4Mтокены16.9M in · 1.5M out

машинное время по фазам

implement6ч 40м ×9

plan2ч 10м ×8

specify1ч 50м ×8

verify1ч 05м ×7

analyze48м ×11

reconcile40м ×9

tasks25м ×8

токены по моделям

glm-5.211.1M · 60%

qwen3-coder-30b4.6M · 25%

deepseek-v3.22.7M · 15%

007-swagger2д 4ч ✓

008-eng-rules13ч в работе

Фильтр по периоду пересчитывает всё мгновенно — данные уже на клиенте. Закрыли гейт — цифры обновились сами по SSE.