---
name: workflow-kit-specify
description: Создание self-contained spec.md для одного atomic change Workflow Kit. Используй когда нужно зафиксировать WHAT/WHY, границы, проверки и открытые вопросы перед workflow-kit-plan.
metadata:
  title: "Создание спецификации"
---

# Workflow Kit: specify

Создай спецификацию для изменения: `$ARGUMENTS`.

Цель: создать self-contained `spec.md` для следующего AI-этапа `workflow-kit-plan`. Spec должна описывать один atomic change: WHAT/WHY, границы, проверки, out-of-scope и открытые вопросы. Не проектируй HOW.

## Порядок работы

### 1. Preflight: один change

Цель preflight — понять, можно ли завести workspace для одного atomic change без гадания. На этом этапе не нужно собрать все требования.

`change` — одна логическая единица управляемого изменения проекта: feature, bugfix, refactor, docs-change, migration, процессное изменение или их смесь.

Atomic change может быть целой фичей с несколькими сценариями, если они ведут к одному desired result. Не дроби feature только потому, что внутри несколько user stories/cases. Дроби только независимые desired results, которые можно планировать или выпускать отдельно.

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

Проверь:

- что пользователь просит изменить;
- что должно стать правдой после изменения хотя бы в черновом виде;
- кто или что потребляет результат: пользователь, API, CLI, агент, документ, внутренняя система;
- какое наблюдаемое поведение добавляется, меняется или удаляется, если применимо;
- есть ли критичное неизвестное, без которого нельзя честно описать desired result.

Если `$ARGUMENTS` не задаёт один проверяемый desired result — остановись: не создавай workspace и не пиши spec из догадок.

Дальше:

- если не хватает ключевой информации — задай 1–3 блокирующих вопроса;
- если запрос объединяет несколько changes — предложи разрез на atomic changes и спроси, какой специфицировать первым;
- если неизвестность некритична — создай workspace и зафиксируй безопасное предположение в spec.

### 2. Создай workspace

Перед созданием файлов проверь доступность `template/SPEC-TEMPLATE.md`. Если шаблон недоступен — остановись и сообщи, что отсутствует обязательный шаблон; workspace не создавай.

- Сгенерируй `change-name`: 2–5 слов в kebab-case.
- Получи timestamp: `date +%Y%m%d_%H%M`.
- Создай директорию: `ai/specs/YYYYMMDD_HHMM_change-name/`.
- Если директория уже существует, не перезаписывай её: получи новый timestamp или добавь короткий suffix к `change-name`.
- Создай `spec.md` по `template/SPEC-TEMPLATE.md`.

Workspace — это контейнер работы, а не награда за идеально собранные требования. Но он должен соответствовать одному atomic change.

### 3. Собери минимальный контекст

Цель контекста — понять текущие термины, наблюдаемое поведение и ограничения результата. Не превращай specify в проектирование реализации.

Правила:

- Project instructions не перечитывай, если они уже есть в контексте. Если change зависит от соглашений проекта и инструкций нет — прочитай ближайший `AGENTS.md` или аналог.
- Если нужно понять публичное поведение или термины проекта — проверь README/project docs и минимально релевантный код.
- Код читай только для понимания текущего поведения, терминов и ограничений результата.
- Не редактируй код на этапе specify.
- Старые `ai/specs/*`, `plan.md` и `tasks.md` можно читать только как справочный контекст, не как источник требований, если пользователь явно не указал связанный workspace.
- При конфликте старых specs/plans с запросом пользователя или текущим поведением ориентируйся на запрос и текущее поведение; конфликт фиксируй как открытый вопрос или кандидат для `research.md`.
- Если README/project docs отсутствуют — не блокируй specify; работай от запроса пользователя и минимально нужного кода.
- Если нужен выбор технологии или глубокое расследование — не решай это внутри specify. Зафиксируй открытый вопрос, риск или кандидат для `research.md`.

### 4. Собери требования

`spec.md` отвечает на **WHAT/WHY**, не на **HOW**.

- WHAT — что должно стать правдой после изменения, какое поведение появляется/меняется/удаляется, какие правила и инварианты выполняются.
- WHY — зачем это нужно сейчас, какая проблема решается, кто потребляет результат.
- HOW запрещён в `spec.md`: классы, функции, библиотеки, архитектурные решения, internal APIs, пошаговая реализация, команды реализации, перечисление файлов как план работы.

Пиши spec так, чтобы следующий AI мог продолжить работу без доступа к этому диалогу. Не используй ссылки вида “как обсуждали”, “это”, “тот вариант” без явного контекста.

Конкретные артефакты, публичные контракты или пути указывай только если они сами являются частью desired result или границей change.

Если появляется техническая идея — записывай её только как ограничение результата, риск, открытый вопрос или кандидат для `research.md`.

Минимально выясни или зафиксируй в `spec.md`:

- кто или что потребляет результат;
- какое наблюдаемое поведение добавляется, меняется или удаляется, если применимо;
- что входит в scope и что явно вне scope;
- какие ограничения результата важны: совместимость, производительность, безопасность, стиль, данные, зависимости;
- как будет проверяться результат: тест, команда, ручной сценарий, review документа, expected output, invariant или наблюдаемый результат;
- как будет понятно, что change успешен, если это отличается от локальных проверок;
- какие вопросы блокируют plan/implement.

Уточняющие вопросы:

- Обычно достаточно 1 раунда; максимум — 3 раунда.
- В одном раунде задавай только самые важные вопросы, обычно 1–7, сгруппированные по смыслу: цель, поведение, границы, приоритеты, проверки.
- Если вопрос блокирует заполнение spec — спроси, зафиксируй `ТРЕБУЕТ УТОЧНЕНИЯ` в `spec.md` и остановись до ответа пользователя.
- Если вопрос не блокирует spec, зафиксируй безопасное предположение в релевантной секции.

### 5. Заполни `spec.md` по шаблону

`template/SPEC-TEMPLATE.md` — единственный источник структуры `spec.md`. Не создавай структуру из памяти и не используй резервные шаблоны.

Правила заполнения:

- Сохраняй верхнеуровневые секции шаблона, их названия и порядок.
- Если секция не применима, не удаляй её: оставь короткое `Не требуется для этого change.` или `Нет.`
- В `## Требования / кейсы` выбери одну основную форму из шаблона и зафиксируй выбор строкой `> Формат: ...`.
- Не смешивай несколько основных форм требований. Edge cases добавляй только как дополнение, если они нужны.
- Приоритеты используй только когда требований больше трёх или scope спорный.
- Не добавляй JSON/XML/YAML-обёртки вокруг Markdown.
- Удаляй HTML comments, placeholders и неиспользованные варианты из итогового `spec.md`.
- Не добавляй новые верхнеуровневые секции без сильной причины; если нужна детализация — используй подсекции внутри существующих разделов.

### 6. Создай ранний `scope.md`, если нужен контроль скоупа до plan

`scope.md` обязателен перед tasks/implement и обычно создаётся на этапе `workflow-kit-plan`. На этапе specify создавай ранний `scope.md` только если change затрагивает несколько модулей или уже есть риск выйти за пределы.

Основания:

- change может задеть public surface: API, schema, migration, generated files, config, shared data;
- задача распределяется между несколькими модулями с разными владельцами;
- есть файлы, которые агент по ошибке может попытаться отредактировать;
- нужно явно запретить часть файлов или директорий.

Если `scope.md` нужен, используй `template/SCOPE-TEMPLATE.md` как единственный источник структуры. Если шаблон недоступен — не создавай `scope.md` из догадок, остановись и сообщи.

Если change маленький и локальный — не создавай `scope.md` на этапе specify. `workflow-kit-plan` позже создаст минимальный обязательный `scope.md`.

### 7. Проверь качество

Перед финалом проверь:

- [ ] Если workspace создан, stop/go решение принято до его создания.
- [ ] Если workspace создан, он создан после preflight и до полноценного сбора требований.
- [ ] `spec.md` самодостаточна для следующего AI-этапа.
- [ ] Spec отвечает на WHAT/WHY, не HOW.
- [ ] Верхнеуровневый формат соответствует `template/SPEC-TEMPLATE.md`.
- [ ] Конкретные пути/контракты указаны только как часть desired result или границы change.
- [ ] В `## Требования / кейсы` выбрана одна основная форма и зафиксирована строкой `> Формат: ...`.
- [ ] Каждый P0/обязательный пункт проверяемый.
- [ ] Out-of-scope есть.
- [ ] Неясности помечены `ТРЕБУЕТ УТОЧНЕНИЯ`, не додуманы молча.
- [ ] Технические ограничения не подменяют план реализации.
- [ ] Изменение не распухло сверх запроса.

### 8. Git и `.gitignore`

Нельзя добавлять в git файлы или директории, которые игнорируются `.gitignore`, без явного разрешения пользователя. Не используй `git add -f` для workflow artifacts.

Перед `git add`/commit проверь созданные и изменённые артефакты одним из способов:

```bash
git check-ignore -v -- <path>
git status --short --ignored
```

Политика коммита:

- Не выполняй `git add`, commit или push без явного запроса пользователя.
- Если пользователь попросил подготовить commit, добавляй только не ignored workflow artifacts (`spec.md`, `scope.md`, связанные plan/tasks) и сначала проверь `.gitignore`.
- Если workspace находится в ignored-директории, не добавляй его в git и явно скажи в финале: `не закоммичено, потому что путь игнорируется .gitignore`.
- Временные анализы, черновики и exploratory-артефакты не коммить без явного запроса.

### 9. Результат

Если workspace и `spec.md` созданы, в финале покажи:

- путь к workspace;
- путь к `spec.md`;
- путь к `scope.md`, если создан;
- краткую суть spec;
- выбранный формат требований/кейсов;
- количество `ТРЕБУЕТ УТОЧНЕНИЯ`;
- готовность к `workflow-kit-plan`: да/нет;
- если не готово к `workflow-kit-plan` — что нужно закрыть;
- статус git/commit или причину, почему артефакты не добавлены.

Если остановилась до создания workspace, в финале покажи:

- почему spec нельзя честно создать сейчас;
- блокирующие вопросы;
- что будет следующим шагом после ответа пользователя;
- явно укажи: workspace не создан.

## Связанные скиллы

- `workflow-kit-plan`
- `workflow-kit-tasks`
- `workflow-kit-implement`
- `workflow-kit-verify`