Spec-kit workflow

Адаптированный для solo-разработки с AI-ассистентом workflow. Пять фаз с явными воротами между ними: нельзя перепрыгнуть фазу без «ok» пользователя. Артефакты живут в .specify/specs/NNN-name/. Мелкие баги и точечные фиксы идут мимо spec-kit.

Пять фаз

1. Specify — что и зачем

Claude пишет spec.md по запросу пользователя. Документ содержит: контекст и проблему, user stories (US-N), функциональные требования (FR-NNN), acceptance scenarios (AS-N), edge cases, зависимости от других спек, open questions (OQ-N).

Вход: идея или запрос пользователя. Выход: spec.md с заполненной строкой **Status**: Specify draft — awaiting Clarify. Кто пишет: Claude, опираясь на конституцию и бриф пользователя.

2. Clarify — открытые вопросы

Пользователь отвечает на OQ-N из spec.md — или Claude задаёт уточняющие вопросы. Ответы фиксируются прямо в spec.md в секции «Clarifications».

Вход: spec.md со списком OQ-N. Выход: все OQ получили статус RESOLVED, строка **Status**: Clarified — awaiting Plan. Правило: не переходить к Plan, пока OQ открыты. Если пользователь настаивает — один раз возразить, потом принять.

3. Plan — как реализовать

Claude пишет plan.md: архитектурные решения, схема данных, компоненты, запросы, порядок работы. Ссылается на spec.md по номерам FR.

Вход: spec.md с закрытыми OQ. Выход: plan.md, **Status**: Plan ready — awaiting Tasks.

4. Tasks — последовательность шагов

Claude пишет tasks.md: пронумерованный список задач T001, T002, … с чекбоксами [ ]. Каждая задача — один атомарный кусок работы (файл, миграция, тест). (tail) помечаются задачи, которые сознательно откладываются.

Вход: plan.md. Выход: tasks.md, **Status**: Tasks ready — awaiting Implement.

5. Implement — по одной задаче

Claude берёт первый незакрытый [ ] в tasks.md, делает, отмечает [x], коротко докладывает. Останавливается и ждёт подтверждения перед следующей задачей.

Вход: tasks.md. Выход: **Status**: Done — in prod (после деплоя).

Артефакты и структура

.specify/
  specs/
    014-approval-flow/
      spec.md
      plan.md
      tasks.md
    NNN-name/
      …
    _archive/      ← закрытые спеки
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
    constitution-template.md
  memory/
    constitution.md
    bookkeeping-roadmap.md
    …
  epics/
    rpg-engine/
      constitution.md
      …

Все артефакты (.specify/) коммитятся прямо в main — они мета-файлы, не код (см. git-and-staging.md).

Что считается одной спекой

Одна спека — одна связная пользовательская возможность или инфра-задача, которую можно описать одним spec.md. Эмпирическое правило: если tasks.md разрастается за 30–40 задач — это, вероятно, два scope'а, и стоит разбить.

Примеры: spec-014 (approval flow) — одна спека. spec-023–027 (инфра-эпик) — пять спек, по одной на инфра-milestone.

Жёсткое правило: не прыгать через фазы

Каждая фаза ждёт явного «ok» / «continue» / «next» от пользователя. «Continue» означает «продолжай текущую задачу», не «переходи к следующей фазе». Если пользователь пытается пропустить фазу — Claude возражает один раз с причиной, затем исполняет.

Во время Implement: после каждой выполненной задачи Claude помечает [x], докладывает коротко и ждёт. Не делает следующую задачу автоматически.

Когда отступать от spec-kit

Spec-kit не для всего. Допустимо обойти его для:

Мелких багов — точечный фикс в 2–3 строки. Фиксируется в backlog.md как BUG-NNN, исправляется прямо в PR, chatlog-запись всё равно создаётся.
Точечных правок мета-файлов — chatlog, документация, NEXT.md.
Инфра одноходовки — например, обновить cron-скрипт по уже готовому runbook.

Признак того, что нужна спека: задача затрагивает схему БД, новый роут или компонент, или её нельзя объяснить одним предложением.

Per-session chatlog

Каждая сессия работы по спеке заканчивается записью в chatlog/. Chatlog-файл создаётся через bash scripts/dev/close-session.sh <slug>. Что фиксировать: контекст (откуда пришли), что сделано, миграции, коммиты, action items для пользователя, что важно следующему чату.

См. также: chatlog-and-memory.md, versioning.md.