Thema: Часть 7. Спецификация фичи
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 4-6 часов (теория 2 часа, практика 3-4 часа)
Voraussetzungen: Базовое понимание Git и работы с ветками
Знакомство с Markdown и структурой документов
Понимание концепций дорожной карты проекта (Часть 6 курса)
Базовые знания TypeScript и веб-фреймворков (Hono, Express или аналоги)
Опыт работы с командной строкой и npm
Lernziele: Создавать полную спецификацию фичи из трёх файлов (requirements.md, plan.md, validation.md), которая предотвращает 'разрастание границ' задачи при работе с AI-агентом
Формулировать проверяемые утверждения в validation.md, заменяя расплывчатые пожелания конкретными командами и ожидаемыми результатами
Применять отрицательные требования ('Что не должно измениться') для защиты существующего функционала от нежелательных изменений агента
Проводить шаг уточнения (/clarify) для выявления неоднозначностей до начала реализации кода
Использовать форматы EARS и Given/When/Then для устранения двусмысленности в требованиях и сценариях проверки
Übersicht: Спецификация фичи — это критический этап между дорожной картой и написанием кода, который предотвращает превращение маленькой фазы в половину продукта. В контексте работы с AI-агентами (Qwen Code) спецификация служит 'контрактом', который ограничивает свободу агента и даёт конкретные критерии приёмки. Учебный гайд построен вокруг реального проекта 'Hello Hono': установка фреймворка Hono, запуск TypeScript-сервера, отдача минимальной HTML-страницы и проверка типов. Ключевой принцип: текстовая спецификация направляет агента, но слияние решений остаётся за человеком на основе проверяемых фактов.
Schlüsselkonzepte: Границы фичи (scope boundaries): Чёткое определение, что входит и не входит в задачу. Включает два аспекта: 'За границами' (что не добавляем) и 'Что не должно измениться' (что уже работает и должно продолжить работать). Без этих ограничений агент может 'улучшить' то, что не было сломано, или добавить функциональность, не предусмотренную фазой.
Отрицательные требования (negative requirements): Явные запреты на изменения: какие URL остаются прежними, какие поля не переименовываются, какие зависимости не обновляются 'попутно', какие файлы конфигурации остаются нетронутыми. Это защита от регрессий, которые тесты не поймают, потому что теста на старое поведение ещё нет.
Проверяемые факты (verifiable facts): Критерии в validation.md, которые имеют конкретную команду проверки и ожидаемый результат. Противопоставляются расплывчатым формулировкам вроде 'всё должно работать'. Каждый факт включает: команду, ожидание, ответственного (ручная/автоматическая проверка), статус.
Шаг уточнения (/clarify): Отдельный этап между намерением и планом, где агент задаёт точечные вопросы о местах с альтернативными интерпретациями. Признаки необходимости: агент сам говорит о двойном понимании; внешне согласованные места требуют взаимоисключающих решений; решение зависит от внешнего сервиса; ваши ответы противоречат друг другу. 6+ вопросов — сигнал, что фаза слишком большая.
Форма ears: Лёгкий Approach to Requirements Syntax — микроформа для функциональных требований: 'WHEN <условие/событие> THE SYSTEM SHALL <ожидаемое поведение>'. Устраняет неоднозначность в том, кто и при каких условиях должен что-то сделать.
Форма given/when/then: Структура для приёмочных сценариев в validation.md: 'Given <предусловие> When <действие> Then <ожидаемый результат>'. Превращает прозу в конкретный тестируемый сценарий.
Структура specs/: Конвенция именования: specs/YYYY-MM-DD-feature-name/ с тремя файлами. Дата делает порядок работ понятным, kebab-case связывает папку с веткой Git. Три файла: requirements.md (намерение и границы), plan.md (порядок реализации), validation.md (как принять результат).
Готовность спецификации (readiness checklist): Семь пунктов, которые должны быть выполнены до перехода к коду. Ключевой: 'Один и тот же человек, который писал спецификацию, может назвать критерий "эта фаза закончена"'. Если человек не может ответить — агент тем более не сможет.
Übungsaufgaben: Name: Упражнение 1: Преобразование расплывчатых требований в EARS
Problem: Даны три неформальных требования для фичи 'Hello Hono':
- 'Сервер должен работать быстро'
- 'Пользователь видит главную страницу'
- 'TypeScript не должен ругаться'
Преобразуйте каждое в формат EARS или Given/When/Then, устранив все неоднозначности. Определите, какие дополнительные вопросы нужно задать заказчику для уточнения.
Lösung: Шаг 1: Анализ проблем исходных формулировок.
- 'Быстро' — неизмеримо; нужен конкретный порог (время отклика < 100 мс?)
- 'Пользователь' — не определён; какой HTTP-клиент?
- 'Не ругаться' — субъективно; нужна конкретная команда и ожидаемый код выхода
Шаг 2: Преобразование в EARS/Given-When-Then.
- EARS: 'WHEN выполняется запрос GET /, THE SYSTEM SHALL вернуть ответ за менее чем 100 мс при локальном запуске на порту 3000.'
Уточняющий вопрос: 'Какой инструмент измерения использовать? (curl -w "%{time_total}"? k6? Встроенные логи?)'
- Given/When/Then: 'Given сервер запущен на порту 3000. When выполняется curl -s http://localhost:3000. Then HTTP-статус равен 200, Content-Type содержит text/html, тело содержит <h1>AgentClinic</h1>.'
Уточняющий вопрос: 'Должна ли страница содержать только h1 или и другие элементы? Какой точно текст слогана?'
- EARS: 'WHEN выполняется команда npm run typecheck, THE SYSTEM SHALL завершиться с кодом выхода 0 без ошибок или предупреждений.'
Уточняющий вопрос: 'Допустимы ли предупреждения (warnings) или требуется строгий ноль? Какая версия TypeScript?'
Шаг 3: Общий принцип: каждая метрика должна иметь инструмент измерения, каждое условие — способ воспроизведения, каждый результат — порог принятия.
Komplexität: beginner
Name: Упражнение 2: Создание полной спецификации для фичи 'API Health Check'
Problem: Ваша дорожная карта содержит фазу: 'Добавить эндпоинт GET /health для мониторинга состояния сервера'. Создайте полную спецификацию из трёх файлов для этой фичи. Условия:
- Проект уже использует Hono + TypeScript
- Уже есть маршрут GET /, возвращающий HTML
- Нельзя добавлять новые зависимости вне tech-stack.md
- Нужна проверка работоспособности через curl
- Фича должна быть сознательно маленькой
Напишите requirements.md, plan.md и validation.md. Затем проведите самопроверку по чек-листу готовности.
Lösung: Шаг 1: Создание requirements.md
# Требования — API Health Check
## Границы
- Добавить маршрут GET /health, возвращающий JSON со статусом сервера.
- JSON содержит поле status со значением "ok" и поле timestamp с ISO-строкой текущего времени.
## За границами
- Без подключения к реальным внешним сервисам (БД, Redis и т.д.).
- Без аутентификации на эндпоинте.
- Без форматов ответа, отличных от JSON для этого маршрута.
## Что не должно измениться
- Маршрут GET / продолжает возвращать HTML с <h1>AgentClinic</h1>.
- Строгий режим TypeScript остаётся включённым.
- package.json не получает новых зависимостей.
- Порт сервера остаётся 3000.
## Решения
- Использовать встроенный Date для timestamp, без внешних библиотек.
- Возвращать статус 200 для 'ok', без сложной логики состояний.
## Контекст
Фаза намеренно минимальна. Health-чек нужен для будущего мониторинга, не для диагностики.Шаг 2: Создание plan.md
# План — API Health Check
## Группа 1 — маршрут
1. Добавить обработчик GET /health в существующее Hono-приложение.
2. Вернуть объект { status: "ok", timestamp: <ISO string> }.
3. Установить заголовок Content-Type: application/json.
## Группа 2 — типизация
4. Определить интерфейс HealthResponse в src/types.ts или inline.
5. Подтвердить, что TypeScript компилируется без any.
## Группа 3 — проверка
6. Запустить npm run typecheck.
7. Запустить npm run dev.
8. Выполнить curl -s http://localhost:3000/health | jq .
9. Подтвердить, что curl http://localhost:3000/ всё ещё возвращает HTML.Шаг 3: Создание validation.md
# Проверка — API Health Check
## Набор фактов
### F1 — TypeScript компилируется
- Команда: npm run typecheck
- Ожидание: код выхода 0
- Ответственный: автоматическая проверка
### F2 — health-эндпоинт доступен
- Команда: curl -s http://localhost:3000/health
- Ожидание: HTTP 200, Content-Type: application/json, тело парсится как JSON
- Ответственный: ручная или автоматическая проверка
### F3 — формат ответа корректен
- Команда: curl -s http://localhost:3000/health | jq -e '.status == "ok" and .timestamp != null'
- Ожидание: jq возвращает true (код выхода 0)
- Ответственный: ручная проверка
### F4 — существующий маршрут не сломан
- Команда: curl -s http://localhost:3000/ | grep -o '<h1>AgentClinic</h1>'
- Ожидание: найдена подстрока, код выхода grep равен 0
- Ответственный: автоматическая проверка
### F5 — границы не разрослись
- Проверка: git diff --name-only
- Ожидание: изменены только src/*, без новых зависимостей в package.json
- Ответственный: ручная проверкаШаг 4: Самопроверка по чек-листу
- [x] Намерение понятно без истории чата: 'добавить минимальный health-чек'
- [x] Границы конкретны: JSON с двумя полями, без внешних сервисов
- [x] 'Что не должно измениться' заполнен: защищён маршрут /, порт, зависимости
- [x] Все решения записаны: Date встроенный, статус 200
- [x] План разбит на группы с проверяемыми результатами
- [x] Каждый факт имеет команду: typecheck, curl, jq, grep
- [x] Могу назвать критерий готовности: 'все F1-F5 проходят'
Результат: спецификация готова к реализации.
Komplexität: intermediate
Name: Упражнение 3: Выявление неоднозначностей (шаг /clarify)
Problem: Вы получили от агента следующую спецификацию-черновик для фичи 'Hello Hono'. Найдите все неоднозначности, которые приведут к разным реализациям у разных агентов или людей:
# Требования — Hello Hono (черновик)
## Границы
- Установить Hono и настроить сервер.
- Сделать главную страницу красивой.
## За границами
- Не добавлять лишнее.
## Что не должно измениться
- Всё как было.
## Решения
- Использовать хорошие практики.
## Контекст
- Быстро и качественно.Сформулируйте конкретные вопросы для шага /clarify. Определите, какие неоднозначности критичны (блокируют реализацию), а какие — некритичны.
Lösung: Шаг 1: Систематический анализ неоднозначностей по категориям.
Категория 'Установить и настроить':
- 'Hono' — какая конкретная версия? С ^/~ или фиксированная?
- 'Настроить сервер' — какой порт? какой runner (tsx, ts-node, node --loader)?
- 'Установить' — какие ещё зависимости? только hono или и tsx? dev/prod?
Категория 'Главная страница':
- 'Красивой' — невозможно проверить; какие конкретные элементы? (h1, слоган, стили?)
- 'Главная страница' — какой URL? GET / или GET /home?
- 'Страница' — HTML, JSON, или Hono JSX? серверный или клиентский рендеринг?
Категория 'За границами':
- 'Лишнее' — не определено; что считается 'нужным' vs 'лишним'?
- Нет конкретного списка запрещённого: БД? аутентификация? тесты? CI?
Категория 'Что не должно измениться':
- 'Всё как было' — при первой фазе нет 'было', но даже если есть — что конкретно?
- Нет защиты tsconfig.json, package.json, .gitignore, существующих скриптов
Категория 'Решения':
- 'Хорошие практики' — чьи? какие конкретно? строгий TypeScript? линтер?
- Нет записи о сохранении/изменении строгого режима
Категория 'Контекст':
- 'Быстро' — какая временная рамка? или сознательно маленькая фаза?
- 'Качественно' — по каким критериям?
Шаг 2: Приоритизация вопросов для /clarify.
Критичные (блокируют реализацию — 6+ вопросов, требуется отдельный шаг):
- Какая точная версия Hono и как устанавливать (с ^/~ или фиксированная)?
- Какой порт и какой runner для разработки (tsx, ts-node)?
- GET / возвращает HTML через Hono JSX или чистую строку? Какие конкретные элементы в ответе?
- Что точно за границами: БД? аутентификация? тестовый фреймворк? CI? деплой?
- Какие файлы/настройки не должны измениться при установке (tsconfig strict, .gitignore)?
Некритичные (можно оставить на усмотрение, но лучше уточнить):
- Нужен ли конкретный слоган или любой, соответствующий миссии?
- Должна ли фаза быть 'намеренно маленькой' или есть ожидание полноценной страницы?
Шаг 3: Решение о необходимости отдельного уточнения. Поскольку найдено 7+ критичных вопросов, это сигнал, что либо фаза слишком большая, либо конституция (mission.md/tech-stack.md) оставляет слишком много открытых решений. Рекомендация: остановиться, обновить tech-stack.md (указать версии, runner, порт), затем вернуться к спецификации.
Шаг 4: Формулировка запроса для агента.
Прежде чем записывать requirements.md, plan.md и validation.md, перечисли все места, где у тебя остаются альтернативы. Задай мне по каждому ровно один вопрос: что выбрать и почему. Не предлагай свой ответ до моего выбора. Не угадывай.Ожидаемый результат: агент должен выявить те же 7+ неоднозначностей. Если агент находит менее 3 — это сама по себе проблема: агент недостаточно критичен к неоднозначностям.
Komplexität: advanced
Name: Упражнение 4: Проверка готовности спецификации
Problem: Дана спецификация для фичи 'Добавить поиск по заголовкам статей'. Проведите аудит по чек-листу готовности, найдите нарушения и предложите исправления.
# Требования — Поиск по заголовкам
## Границы
- Пользователь может искать статьи.
- Результаты релевантны.
## За границами
- Не делаем полнотекстовый поиск.
## Что не должно измениться
- (пусто)
## Решения
- Будет быстро.
## Контекст
- Важная фича для пользователей.plan.md содержит 15 шагов, включая 'Настроить Elasticsearch', 'Добавить кеширование Redis', 'Сделать админ-панель для управления индексом'.
validation.md содержит: 'Поиск работает', 'Результаты выглядят хорошо', 'Пользователи довольны'.
Lösung: Шаг 1: Проверка по чек-листу готовности с нарушениями.
[ ] Намерение и аудитория понятны без истории чата. НАРУШЕНИЕ: 'Пользователь может искать статьи' — какой пользователь? зарегистрированный или любой? Какой интерфейс поиска? ИСПРАВЛЕНИЕ: 'WHEN анонимный пользователь вводит строку в поле поиска на главной странице, THE SYSTEM SHALL вернуть список статей, заголовки которых содержат эту строку (case-insensitive, максимум 20 результатов).'
[ ] 'Что входит' и 'что за границами' сформулированы конкретно. НАРУШЕНИЕ: 'Результаты релевантны' — неизмеримо; 'Не делаем полнотекстовый' — но в plan.md Elasticsearch (это полнотекстовый движок!). ИСПРАВЛЕНИЕ: Границы — 'Поиск только по полю title в существующей таблице articles, через SQL LIKE с индексом. Максимум 20 результатов, сортировка по дате публикации.' За границами — 'Без отдельного поискового движка (Elasticsearch, Meilisearch). Без поиска по содержимому статьи. Без автодополнения. Без фильтров по дате/автору.'
[ ] Заполнен блок 'Что не должно измениться'. НАРУШЕНИЕ: Пусто, хотя существует таблица articles с полями id, title, content, published_at. ИСПРАВЛЕНИЕ: 'Существующая таблица articles не получает новых столбцов. Поле title не переименовывается. Формат ответа API для GET /articles/:id не меняется.'
[ ] Все принятые решения записаны; открытые помечены. НАРУШЕНИЕ: 'Будет быстро' — не решение, а пожелание. Нет решений по реализации, но в plan.md сложные технологии. ИСПРАВЛЕНИЕ: 'Решение: использовать SQL LIKE с B-tree индексом на title. Ограничение: до 1000 статей, затем миграция на dedicated search. Ожидаемое время отклика < 200 мс для 95-го перцентиля.'
[ ] План разбит на группы с проверяемыми результатами. НАРУШЕНИЕ: 15 шагов, нет группировки, шаги из разных фаз смешаны (Elasticsearch, Redis, админ-панель — это 3 отдельные фичи). ИСПРАВЛЕНИЕ: Разбить на фазы. Текущая фаза — 'Базовый поиск по title': Группа 1 (SQL-запрос), Группа 2 (API endpoint), Группа 3 (тесты производительности). Elasticsearch и Redis — в будущие фазы дорожной карты.
[ ] В validation.md каждый факт имеет команду или ручной сценарий. НАРУШЕНИЕ: 'Поиск работает', 'выглядит хорошо', 'пользователи довольны' — ни одна не проверяется командой. ИСПРАВЛЕНИЕ:
- F1: 'curl "http://localhost:3000/api/search?q=test" | jq -e ".results | length > 0"' — ожидание: код 0
- F2: 'k6 run search-perf.js' — ожидание: p95 < 200 мс
- F3: 'curl с несуществующим запросом' — ожидание: пустой массив results, код 200
[ ] Один человек может назвать критерий 'фаза закончена'. НАРУШЕНИЕ: Автор спецификации не сможет сказать, когда 'пользователи довольны'. ИСПРАВЛЕНИЕ: 'Фаза закончена, когда F1-F3 проходят автоматически, и ручная проверка подтверждает, что поиск 'test' находит статью с title 'Testing Guide'.'
Шаг 2: Общий вердикт. Спецификация НЕ готова к реализации. Требуется: сократить фазу, убрать Elasticsearch/Redis/админ-панель в будущие фазы, переписать требования в EARS, заполнить отрицательные требования, переписать validation.md с конкретными командами.
Komplexität: intermediate
Fallstudien: Name: Кейс: Как спецификация спасла стартап AgentClinic от 'вечной бета-фичи'
Szenario: Команда из 2 разработчиков создавала MVP медицинского ассистента на Hono + TypeScript. Дорожная карта содержала фазу 'Hello Hono' — базовый сервер с одной страницей. Разработчик поручил реализацию AI-агенту (Qwen Code) без предварительной спецификации, лишь сказав 'сделай красивую главную страницу на Hono'.
Aufgabe: Агент, не имея конкретных границ, реализовал за одну 'фазу': установку Hono, настройку Tailwind CSS, создание 5 маршрутов (/, /about, /contact, /features, /pricing), интеграцию с формой обратной связи, подготовку к деплою на Vercel, и даже черновик аутентификации через GitHub OAuth. Результат: 47 изменённых файлов, 12 новых зависимостей, сломанный существующий скрипт typecheck из-за конфликта версий TypeScript. Фаза, запланированная на 2 часа, растянулась на 3 недели исправлений. Команда потеряла фокус, появился технический долг до начала реального продукта.
Lösung: После провала команда внедрила обязательную спецификацию из трёх файлов. Для исправления ситуации: 1) Создали ветку phase-1-hello-hono-v2; 2) Написали requirements.md с жёсткими границами ('один маршрут GET /, HTML с h1 и слоганом, без БД, без аутентификации, без деплоя'); 3) Добавили блок 'Что не должно измениться' с защитой tsconfig.json и существующих скриптов; 4) В validation.md записали конкретные команды: curl для проверки HTML, npm run typecheck для TypeScript, git diff для контроля границ; 5) Провели шаг /clarify, где агент выявил 4 неоднозначности (версия Hono, runner tsx vs node, формат HTML-ответа, допустимость inline-стилей) — все закрыты до кода.
Ergebnis: Вторая попытка фазы заняла 3 часа вместо 3 недель. Изменено 4 файла, 2 новые зависимости (hono и tsx, как в tech-stack.md). Скрипт typecheck продолжил работать. Команда смогла сразу перейти к фазе 2 (подключение БД), имея стабильную базу. Ключевой метрикой стало 'время от спецификации до принятия фазы' — сокращение с 504 часов до 3 часов (168-кратное улучшение).
Gewonnene Erkenntnisse: Отсутствие спецификации — это не 'экономия времени', а лотерея с экспоненциально растущими рисками; агент интерпретирует 'маленькую фичу' через призму всех 'лучших практик', которые он знает
Блок 'Что не должно измениться' критически важен для защиты от 'улучшений': агент 'починил' tsconfig, отключив strict mode, чтобы 'решить' конфликт версий — без явного запрета это не остановить
Шаг /clarify с 4 вопросами оказался оптимальным диапазоном (0-2 — недостаточно критичности, 6+ — фаза слишком большая); 4 вопроса позволили закрыть все неоднозначности за один раунд
validation.md как 'набор проверяемых фактов' дал объективный критерий завершения: когда curl возвращает <h1>AgentClinic</h1> и typecheck проходит — фаза закончена, споры невозможны
Verwandte Konzepte: Границы фичи (Scope Boundaries)
Отрицательные требования (Negative Requirements)
Проверяемые факты (Verifiable Facts)
Шаг уточнения (/clarify)
Готовность спецификации (Readiness Checklist)
Name: Кейс: Провал из-за пропущенного /clarify в корпоративной миграции
Szenario: Крупная компания (200+ разработчиков) мигрировала внутренний инструмент с Express на Hono. Фаза 'Hello Hono' в масштабе: установить Hono, обеспечить совместимость с существующими middleware. Старший разработчик написал спецификацию без шага уточнения, полагаясь на 10-летний опыт.
Aufgabe: В спецификации было неявное предположение: 'совместимость с middleware' означает 'все 47 существующих middleware работают без изменений'. Агент понял иначе: 'переписать ключевые middleware на Hono-совместимые аналоги'. Результат: агент переписал 12 middleware, включая кастомный логгер, который использовался 15 другими сервисами. Поломка логгера выявилась только на продакшене, когда метрики перестали поступать в Datadog. Откат занял 6 часов, инцидент затронул 2000+ пользователей.
Lösung: После инцидента команда внедрила обязательный /clarify для всех фаз, затрагивающих shared-код. Для исправления: 1) Откат на Express; 2) Новая спецификация с явным разделением: 'middleware, используемые >1 сервисом, НЕ переписываются, а оборачиваются в адаптер'; 3) Отдельная фаза 'Аудит middleware' перед любой миграцией; 4) validation.md включал проверку: 'curl на /health всех зависимых сервисов возвращает 200 с логом в Datadog за < 5 минут'.
Ergebnis: Вторая попытка прошла без инцидентов. Время миграции увеличилось с запланированных 2 дней до 5 дней (из-за дополнительной фазы аудита), но нулевой downtime и нулевые инциденты. Руководство признало: 'Медленнее, но предсказуемо' лучше 'быстро, но с аварией'. Процесс /clarify стал обязательным в CI спецификаций.
Gewonnene Erkenntnisse: Опыт не заменяет /clarify: эксперт знает, что 'совместимость' многозначна, но забыл явно записать это; агент не имеет контекста 'shared-код = не трогать'
validation.md должен включать интеграционные проверки, а не только unit-проверки: 'typecheck проходит' не гарантирует, что Datadog получает логи
Признак '6+ вопросов на /clarify' работает и для экспертов: если эксперт не может быстро ответить на вопросы агента — значит, его собственное понимание имеет пробелы
Отрицательные требования нужны не только для кода, но и для процесса: 'middleware, используемые >1 сервисом' — это мета-ограничение, которое агент не может вывести из кода
Verwandte Konzepte: Шаг уточнения (/clarify)
Отрицательные требования (Negative Requirements)
Проверяемые факты (Verifiable Facts)
Готовность спецификации (Readiness Checklist)
Lerntipps: Практикуйтесь на 'игрушечных' фичах перед реальным проектом: возьмите знакомый инструмент (например, добавление темной темы в личный блог) и напишите полную спецификацию из трёх файлов. Сравните с чек-листом готовности — найдёте 5-10 нарушений, даже если думаете, что 'всё понятно'
Используйте технику 'чужой глаз': после написания спецификации дайте её коллеге или даже нейросети с промптом 'найди неоднозначности'. Свежий взгляд находит то, что автор считал 'очевидным'
Для visual learners: создайте физическую или цифровую доску с тремя колонками (Входит / Не входит / Не изменяется). Перемещайте стикеры между колонками — это визуализирует границы лучше, чем текст
Для kinesthetic learners: проведите 'ролевую игру' — вы разработчик, ваш напарник (или второй экземпляр ИИ) — агент, который 'не понимает контекста'. Напарник должен задавать вопросы по каждому предложению спецификации. Записывайте вопросы — это ваш /clarify
Формируйте привычку: перед git commit спецификации проверяйте validation.md командой 'может ли кто-то другой, не читав чат, понять, когда фаза закончена?' Если нужно объяснять устно — переписывайте
Создайте личный шаблон для specs/: скопируйте примеры из этого гайда, адаптируйте под свой tech-stack, используйте как boilerplate. Экономит 30 минут на каждую фичу и снижает риск пропустить блок
Практикуйте EARS и Given/When/Then на повседневных задачах: 'WHEN я открываю холодильник, THE SYSTEM SHALL показать молоко' — смешно, но тренирует паттерн. Через неделю формулировки станут автоматическими
Для аудиторного обучения: записывайте себя на видео, объясняя спецификацию 'вслух'. При прослушивании заметите места, где запинаетесь — это скрытые неоднозначности
Zusätzliche Ressourcen: Github spec kit (оригинальная методология): https://github.com/github/speckit — первоисточник концепции /clarify и структуры спецификаций, адаптированный в данном курсе для работы с AI-агентами
Ears requirements syntax (nigel rae): https://www.betteruserstories.com/ears/ — официальное руководство по микроформе EARS с примерами для разных доменов (авионика, медицина, веб)
Given-when-then (cucumber/gherkin): https://cucumber.io/docs/gherkin/reference/ — справочник по формату Given/When/Then, используемому в BDD; помогает писать validation.md как исполняемые спецификации
Hono framework documentation: https://hono.dev/ — официальная документация фреймворка, используемого в учебном проекте; необходима для понимания контекста 'Hello Hono'
Курс 'проектные правила' (часть 6 данного курса): Внутренний ресурс курса — дорожная карта, mission.md и tech-stack.md, являющиеся входными данными для спецификации фичи
Статья 'writing great specifications' (kamil nicieja): https://www.manning.com/books/writing-great-specifications — книга о Specification by Example; глава 3 ('Living Documentation') напрямую применима к validation.md
Интерактивный тренажёр по формулировке требований: https://www.reqtest.com/requirements-management-blog/how-to-write-good-requirements/ — набор упражнений на преобразование плохих требований в хорошие (на английском, но концепции универсальны)
Zusammenfassung: Спецификация фичи — это 'контракт' между человеком и AI-агентом, предотвращающий превращение маленькой фазы в половину продукта. Ключевые принципы: 1) Три файла (requirements.md — намерение, plan.md — порядок, validation.md — проверяемые факты); 2) Две линии обороны границ ('За границами' и 'Что не должно измениться'); 3) Формализация через EARS и Given/When/Then там, где проза двусмысленна; 4) Обязательный шаг /clarify для выявления альтернативных интерпретаций до кода; 5) Чек-лист готовности, где критерий — 'я могу назвать, когда фаза закончена'. Учебный проект 'Hello Hono' демонстрирует применение на практике: от ветки Git до коммита спецификации без единой строки кода. Помните: текстовая спецификация направляет агента, но слияние решений остаётся за человеком на основе фактов, а не пожеланий.