Flownix
Начать
Разделы
На этой странице

Спецификация, которая не отстаёт от кода

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

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

Два режима — один явный выбор

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

Обычный

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

Подходит для: Прототипы, личные проекты и команды с внешним процессом документации.

Строгий

Для закрытия task или plan нужна применённая doc-delta либо явный no-impact вывод.

Подходит для: API, регламентируемые продукты и команды, где документация служит контрактом.

Spec-first

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

Подходит для: Команды, которые прорабатывают решение до реализации, а не описывают его после.

Три политики, а не три значения одного поля

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

ПолитикаВопрос, на который отвечаетЧто происходит при включении
spec_mode: strictОбязана ли задача закрыться спекой?done требует применённой дельты либо объявленного отсутствия влияния.
require_proposal_approvalСмотрел ли человек до начала работы?Неодобренная дельта не пускает задачу в in_progress и не применяется.
spec_firstВ каком порядке идёт работа?Дельта рождается черновиком; задачи под фичей не заводятся, пока её документ не одобрен.

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

Как проходит фича в spec-first

  1. Агент заводит фичу — это и есть change, её content несёт proposal.
  2. propose_doc_delta создаёт черновик: он не стоит в очереди ревью и никого ни о чём не спрашивает.
  3. Агент и человек прорабатывают документ — update_doc_delta полным телом, сколько нужно. Отвергнутые решения остаются комментариями на фиче.
  4. submit_doc_delta — и агент останавливается. Теперь дельта адресована человеку.
  5. Человек одобряет или отклоняет. При отказе правится та же дельта, и отклонённая редакция остаётся читаемой в истории раундов.
  6. Только после одобрения агент нарезает задачи — по принятому документу.

Попытка завести задачу раньше отклоняется с spec_first_not_approved. Отказ называет фичу, состояние её дельт и оба выхода: довести документ до одобрения либо объявить, что описанное поведение не меняется.

Как проходит задача в strict

  1. Агент читает spec_mode из .flownix и действующую документацию.
  2. Выполняет работу и решает, изменился ли документированный контракт или поведение.
  3. Если изменился — предлагает полное новое состояние документа и применяет ревизию.
  4. Если не изменился — записывает конкретную причину через declare_no_spec_impact.
  5. Сервер проверяет доказательство и только после этого разрешает статус done.

Не патч и не кнопка «пропустить»

Спека изменилась

Delta содержит документ целиком. Так optimistic lock видит версию, история остаётся читаемой, а apply не может случайно затереть неизменённые разделы фрагментом.

Спека не изменилась

No-impact — проверяемое решение с содержательной причиной, а не автоматический обход гейта. Короткие заглушки сервер не принимает.

Формат: OpenSpec как индустриальный стандарт

Спека Flownix — не вольный markdown. Документ пишется в формате OpenSpec, открытого стандарта spec-driven development: агент пишет спеку по одним правилам в любом проекте, сервер умеет проверить её структурно, а проект обменивается спеками с внешним миром без потери смысла.

shell
# Авторизация

## Purpose
Аутентификация и управление сессиями.

## Requirements

### Requirement: Выдача токена
Система SHALL выдавать JWT после успешного входа.

#### Scenario: Верные учётные данные
- GIVEN пользователь с верными учётными данными
- WHEN он отправляет форму входа
- THEN возвращается JWT

Одно требование — одно наблюдаемое поведение и одно ключевое слово RFC 2119 (SHALL, MUST, SHOULD, MAY) заглавными. У каждого требования хотя бы один сценарий: требование, которое нельзя проверить, — это пожелание, а не контракт. Как именно оно реализовано — очередь, библиотека, схема таблицы — живёт в плане, а не в спеке.

Инструмент validate_spec проверяет документ по слагу или сырое тело, ещё нигде не сохранённое, и отвечает списком того, что поправить. Ничего не меняет — его можно звать до того, как заводить под спеку ноду.

Храповик: ухудшать нельзя, жить со старым можно

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

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

Соответствие сущностей OpenSpec

OpenSpecFlownix
openspec/specs/<domain>/spec.mddoc-нода, spec_domain — имя каталога
### Requirement: / #### Scenario:секции внутри тела doc-ноды
дельта-спека (## ADDED/MODIFIED/REMOVED Requirements)строка doc_revisions (полное тело) плюс вычисленные операции
changes/<name>/proposal.mdнода feature
changes/<name>/design.mdнода plan
changes/<name>/tasks.mdноды task под планом
openspec archiveapply_doc_delta плюс закрытие ноды
openspec validate --strictvalidate_spec плюс гейт spec_mode=strict

Обмен каталогом openspec/

Проект выгружается в дерево openspec/ и загружается обратно — в том числе из чужого репозитория, собранного самим инструментом OpenSpec.

  • export_openspec отдаёт список файлов: specs/<domain>/spec.md по документам, changes/<slug>/ по незакрытым фичам, changes/archive/<дата>-<slug>/ по закрытым. Файлы на диск пишет агент своими инструментами — MCP-сервер работает по HTTP и до вашего репозитория не дотягивается.
  • import_openspec принимает то же дерево обратно. Идемпотентен по домену документа и имени каталога changes/<name>: повторная загрузка неизменённого дерева не создаёт дублей и не плодит пустых дельт, поэтому его безопасно звать после каждого pull.

Обратимость проверяется тестом, а не декларируется: import(export(проект)) в пустой проект даёт тот же канонический рендер каждой спеки, тот же состав веток и те же состояния дельт.

MCP-инструменты

Четырнадцать операций покрывают чтение и запись политики, жизненный цикл ревизии вместе с черновиком, проверку формата, обмен деревом openspec/ и честное отсутствие влияния.

ИнструментНазначение
get_project_policyУзнать текущий режим проекта и условие закрытия работы.
set_project_policyВключить или выключить строгий режим — например, при онбординге проекта в flownix-init.
propose_doc_deltaПредложить полное новое состояние документа от имени task или plan.
list_doc_deltasПосмотреть предложенные, применённые и отклонённые ревизии; фильтр по review_status находит собственные черновики.
get_doc_deltaПрочитать одну ревизию целиком вместе с историей раундов ревью.
update_doc_deltaПравка черновика или отклонённой ревизии на месте — полным телом документа.
submit_doc_deltaОтправить черновик на ревью: единственный переход draft → pending.
apply_doc_deltaПрименить ревизию, если версия документа не успела измениться.
approve_doc_delta / reject_doc_deltaРешение человека по предложению; из агентской сессии отклоняются.
discard_doc_deltaОтклонить предложенную ревизию, сохранив её в истории.
declare_no_spec_impactЯвно объяснить, почему работа не изменила документируемое поведение.
validate_specПроверить формат спеки — по слагу документа или по сырому телу; ничего не меняет.
export_openspecВыгрузить проект деревом openspec/ для записи в репозиторий.
import_openspecЗагрузить дерево openspec/ обратно в проект; идемпотентно.

Кому нужен строгий режим

Контрактные API

Схемы ответов и интеграционные обещания обновляются в том же цикле, что и реализация.

Несколько AI-агентов

Следующий агент получает актуальную спецификацию, а не восстанавливает намерение по коммитам.

Аудит и соответствие

Каждое изменение документа связано с источником, версией, причиной и временем применения.

Дальше