Часть 7. Спецификация фичи

После проектных правил у вас есть дорожная карта, но ещё нет разрешения писать код. Следующий шаг — спецификация первой фичи. В нашем учебном проекте первая фаза называется Hello Hono: установить Hono, запустить TypeScript-сервер, отдать минимальную HTML-страницу и проверить типы.

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

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

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

Структура спецификации фичи

specs/
  2026-05-01-hello-hono/
    requirements.md
    plan.md
    validation.md

Дата делает порядок работ понятным. Имя в kebab-case связывает папку с веткой.

Создание ветки

git checkout -b phase-1-hello-hono

Или попросите Qwen Code:

Найди следующую незавершённую фазу в @specs/roadmap.md.
Создай для неё ветку.
Код пока не реализуй.

Сначала спроси меня о спецификации фичи.

Проверьте git status, чтобы не начинать фичу поверх незавершённой работы.

Запрос для Qwen Code

Найди следующую фазу в @specs/roadmap.md и создай спецификацию фичи.

Создай:
- specs/YYYY-MM-DD-feature-name/requirements.md
- specs/YYYY-MM-DD-feature-name/plan.md
- specs/YYYY-MM-DD-feature-name/validation.md

Перед записью файлов задай мне ровно три сгруппированных вопроса:
1. Границы: что должно и не должно входить в фичу
2. Решения: ключевые решения реализации
3. Контекст: тон, ограничения, риски и ожидания от проверки

Используй @specs/mission.md и @specs/tech-stack.md как опору.
Код реализации не пиши.

Отдельный шаг уточнения

В GitHub Spec Kit между намерением и планом выделен отдельный шаг /clarify: агент задаёт серию точечных вопросов о тех местах, где требования допускают разные интерпретации. Мы воспроизводим этот шаг внутри блока «три сгруппированных вопроса», но при крупной фиче полезно вынести уточнение отдельно — особенно если первые ответы открыли новые неоднозначности.

Признак, что нужно отдельное уточнение:

• агент сам говорит «я могу понять X как A или как B»;

• два места спецификации внешне согласованы, но требуют взаимоисключающих решений в коде;
• решение зависит от внешнего сервиса/договорённости, о которой агент не знает;
• ваши собственные ответы противоречат друг другу.

Запрос для уточнения:

Прежде чем записывать requirements.md, plan.md и validation.md, перечисли все места,
где у тебя остаются альтернативы. Задай мне по каждому ровно один вопрос: что выбрать
и почему. Не предлагай свой ответ до моего выбора. Не угадывай. Если альтернатив нет,
напиши «уточнений не требуется».

Если агент возвращает 0–2 точечных вопроса, обычно стоит ответить и продолжить. Если 6+ — это сигнал, что фаза слишком большая или что конституция оставляет слишком много открытых решений; лучше остановиться, обновить mission.md/tech-stack.md и вернуться к спецификации позже.

Пример requirements.md

# Требования — Hello Hono

## Границы

Установить и настроить Hono с сервером разработки через tsx. Добавить один маршрут GET /, который возвращает минимальную HTML-страницу через Hono JSX. Подтвердить, что TypeScript работает от начала до конца.

## За границами

- Без базы данных.
- Без аутентификации.

- Без настройки тестового фреймворка.
- Без развёртывания в рабочей среде.
- Без многостраничной навигации.

## Что не должно измениться

- Строгий режим в `tsconfig.json` остаётся включённым.
- `package.json` не получает зависимостей, не указанных в `tech-stack.md`.
- `.gitignore` не уменьшается; добавлять туда можно, удалять — нет.
- Существующие скрипты `npm run typecheck` продолжают работать.

## Решения

- Зафиксировать версию Hono без ^ или ~.
- Оставить строгий режим TypeScript.
- Использовать HTML с серверным рендерингом, а не клиентский фреймворк.

## Контекст

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

Отрицательные требования: блок «Что не должно измениться»

Раздел «За границами» отвечает на вопрос «что мы не добавляем». Раздел «Что не должно измениться» отвечает на другой вопрос — «что уже работает и должно продолжить работать». Эти два списка пересекаются, но не совпадают.

Простой пример. «За границами» говорит: «не добавляем аутентификацию». «Что не должно измениться» говорит: «существующий маршрут GET / продолжает возвращать HTML с <h1>AgentClinic</h1>».

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

Хорошие пункты в этом блоке:

• какие публичные URL остаются прежними;
• какие имена полей и таблиц не переименовываются;
• какие форматы ответов не меняются;
• какие зависимости не обновляются «попутно»;
• какие файлы конфигурации остаются нетронутыми.

Если фича вообще ничего не должна сохранять (например, первая фаза проекта, где ещё нет ни URL, ни таблиц), оставьте раздел пустым с пометкой «нет существующего поведения для защиты».

Форма формулировок: EARS и Given/When/Then

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

EARS (Easy Approach to Requirements Syntax) — для функциональных требований:

WHEN <условие/событие>
THE SYSTEM SHALL <ожидаемое поведение>.

Например: «WHEN пользователь открывает GET /, THE SYSTEM SHALL вернуть HTTP 200 и HTML с <h1>AgentClinic</h1>».

Given / When / Then — для приёмочных сценариев в validation.md:

Given <предусловие>
When  <действие>
Then  <ожидаемый результат>.

Например: «Given сервер запущен на порту 3000. When выполняется curl -s http://localhost:3000. Then ответ содержит подстроку <h1>AgentClinic</h1> и код выхода curl равен 0».

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

Готовность спецификации к реализации

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

• [ ] Намерение и аудитория фичи понятны из requirements.md без истории чата.
• [ ] «Что входит» и «что за границами» сформулированы конкретно.

• [ ] Заполнен блок «Что не должно измениться» (или явно помечено «нет существующего поведения для защиты»).
• [ ] Все принятые решения записаны; открытые помечены и закрыты до реализации.
• [ ] План разбит на группы задач, каждая из которых заканчивается проверяемым результатом.
• [ ] В validation.md каждый факт имеет команду или ручной сценарий; нет пунктов «всё должно работать».
• [ ] Один и тот же человек, который писал спецификацию, может назвать критерий «эта фаза закончена».

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

Пример plan.md

# План — Hello Hono

## Группа 1 — настройка пакетов

1. Установить hono.
2. Установить tsx как зависимость для разработки.
3. Подтвердить строгие настройки TypeScript.

## Группа 2 — точка входа приложения

4. Заменить src/index.ts минимальным Hono-приложением.
5. Добавить маршрут GET /.
6. Привязать сервер к порту 3000.

## Группа 3 — домашняя страница

7. Добавить домашнюю страницу с серверным рендерингом.
8. Вывести h1 с AgentClinic.
9. Добавить короткий слоган, согласованный с миссией.

## Группа 4 — проверка

10. Запустить npm run typecheck.
11. Запустить npm run dev.
12. Подтвердить, что curl localhost:3000 возвращает HTML.

Пример validation.md

# Проверка — Hello Hono

## Набор фактов

### F1 — TypeScript компилируется

- Команда: `npm run typecheck`
- Ожидание: код выхода 0
- Ответственный: автоматическая проверка
- Статус: принято

### F2 — сервер запускается

- Команда: `npm run dev`
- Ожидание: сервер слушает порт 3000 без ошибок запуска
- Ответственный: ручная проверка
- Статус: принято

### F3 — домашний маршрут возвращает HTML

- Команда: `curl -s http://localhost:3000`
- Ожидание: ответ содержит HTML с `<h1>AgentClinic</h1>`
- Ответственный: ручная или автоматическая проверка
- Статус: принято

### F4 — границы не разрослись

- Проверка: посмотреть различия в ветке
- Ожидание: не добавлены база данных, аутентификация, CI или лишние продуктовые маршруты
- Ответственный: ручная проверка
- Статус: принято

## Ручная проверка

- Подтвердить, что слоган соответствует миссии.
- Подтвердить, что несвязанные файлы не переписаны.

## Критерии готовности

- Все пункты набора фактов реализованы или явно отложены.
- Обязательные автоматические факты проходят.

- Ручные факты проверены.
- Фазу дорожной карты можно отметить завершённой.

Проверка спецификации до реализации

Сначала попросите агента найти слабые места:

Проверь @specs/2026-05-01-hello-hono/requirements.md,
@specs/2026-05-01-hello-hono/plan.md и
@specs/2026-05-01-hello-hono/validation.md.

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

Если агент нашёл неоднозначность, исправьте спецификацию до кода.

Практика

1. Выберите первую фазу дорожной карты.
2. Создайте ветку.
3. Проведите интервью через Qwen Code.
4. Создайте три файла спецификации.
5. Проверьте спецификацию на неоднозначность.
6. Сделайте коммит только со спецификацией:

git add specs/2026-05-01-hello-hono
git commit -m "Add Hello Hono feature spec"

Контрольные вопросы

1. Почему спецификация фичи должна появиться до реализации?
2. Что должно быть в validation.md, кроме npm test?
3. Чем requirements.md отличается от plan.md?