# Часть 11. Вторая фаза фичи

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

В AgentClinic вторая фаза может называться «Агенты и недуги». Она вводит SQLite, таблицы агентов и недугов, начальные данные, страницы `/agents` и `/ailments`, тесты и навигацию.

## Контрольный список чистого старта

Перед новой веткой фичи:

```bash
git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck
```

В Qwen Code:

```text
/clear
```

Проверьте дорожную карту:

```text
Прочитай @specs/roadmap.md.
Какая следующая незавершённая фаза?
Файлы не изменяй.
```

Если есть незавершённые изменения, не начинайте новую фазу. Иначе изменения, сгенерированные агентом, будет трудно объяснить.

## Создание спецификации для второй фазы

Запрос:

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

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

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

Ответы могут быть такими:

```text
Границы:
Добавить агентов и недуги только для чтения. Включить страницы списков и страницу агента.
Пока без записи на приём и без форм.

Решения:
Использовать SQLite с миграциями, написанными вручную. Добавить вымышленные начальные данные.
Использовать маршруты Hono и компоненты, которые рендерятся на сервере.
Добавить тесты маршрутов и компонентов на Vitest.

Контекст:
Содержание должно быть сатирическим, но реализация — понятной.
Интерфейс должен быть адаптивным. Без клиентского JavaScript.
```

## Когнитивная нагрузка и границы проверки

Вторая фаза обычно больше первой. Когда агент за один проход меняет десятки файлов, человек физически не успевает их осмыслить — глаз скользит, ошибки проскакивают. Чтобы не утонуть в этом потоке:

- реализуйте группы задач по одной или парами;
- делайте промежуточные коммиты;
- просите Qwen Code суммировать изменения по группе задач;
- используйте `/review`, если ваша версия Qwen Code поддерживает встроенный процесс проверки;
- не принимайте изменения, которые не соотносятся со спецификацией.

Пример запроса для проверки:

```text
/clear
Проверь текущую ветку по @specs/2026-05-02-agents-ailments/plan.md
и @specs/2026-05-02-agents-ailments/validation.md.

Сфокусируйся на:
1. выходе за границы фазы;
2. безопасности миграций базы данных;
3. пробелах в тестовом покрытии;
4. противоречиях с @specs/tech-stack.md.

Файлы не изменяй.
```

## Пример групп задач

```markdown
# План — Агенты и недуги

## Группа 1 — запуск базы данных

1. Установить better-sqlite3.
2. Добавить модуль подключения к базе данных.
3. Добавить повторно запускаемый механизм миграций.

## Группа 2 — доменная схема

4. Добавить таблицу агентов.
5. Добавить таблицу недугов.
6. Добавить связующую таблицу agent_ailments.

## Группа 3 — начальные данные

7. Добавить вымышленных агентов.
8. Добавить вымышленные недуги.
9. Связать агентов с недугами.

## Группа 4 — маршруты и компоненты

10. Добавить страницу списка /agents.
11. Добавить страницу деталей /agents/:id.
12. Добавить страницу /ailments.

## Группа 5 — тесты и проверка

13. Добавить тесты маршрутов.
14. Добавить тесты рендеринга компонентов.
15. Запустить npm test и npm run typecheck.
```

## Стилевые решения тоже должны быть в спецификациях

Если вы решаете, что фирменные цвета — оранжевый и чёрный, это не должно остаться только в чате. Запишите:

```markdown
## Визуальное направление

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

Запрос для Qwen Code:

```text
Обнови нужные спецификации: фирменные цвета AgentClinic — оранжевый и чёрный.
Затем обнови CSS только там, где это нужно.
Не меняй стиль несвязанных страниц.
```

## Спецификация исправления, а не фичи

Не всякая ветка — это новая фича. Часть работы — исправление ошибок: пользователь нашёл, что список агентов сортируется не в том порядке, или что валидация формы пропускает пустое сообщение. Для таких изменений шаблон `requirements.md` плохо подходит: вопрос «что должно появиться» здесь второстепенный, главные — «что уже сломано», «почему» и «что не должно сдвинуться при починке».

В таких случаях полезно использовать отдельный режим — спецификацию исправления. Структура папки та же:

```text
specs/
  2026-05-12-feedback-empty-message-bug/
    bugfix.md
    plan.md
    validation.md
```

Только вместо `requirements.md` у вас `bugfix.md` с другим набором разделов.

```markdown
# Исправление — POST /feedback пропускает пустое сообщение

## Текущее поведение

При отправке формы с пустым полем `message` сервер возвращает 302 и сохраняет
строку с пустым сообщением в таблицу `feedback`. На странице /feedback такая
запись отображается как пустой блок.

## Ожидаемое поведение

При пустом `message` сервер возвращает 400 и страницу `/feedback/new`
с подсветкой поля и текстом ошибки «Сообщение обязательно». Запись в базу
не создаётся.

## Доказательство первопричины

В `src/routes/feedback.ts` маршрут POST принимает тело без вызова валидации:
тело сразу передаётся в запись. Это видно в коммите 3a7c1b9 фазы
2026-05-10-feedback-form, где валидация была отложена с пометкой `// TODO`.

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

- Маршрут GET /feedback продолжает возвращать страницу со списком.
- Существующие записи в таблице `feedback` не редактируются и не удаляются.
- Имена полей формы (`name`, `message`) остаются прежними.
- Формат ошибки 400 совпадает с остальными маршрутами проекта.

## Сценарии регрессии

- POST с непустым `message` по-прежнему сохраняет запись и возвращает 302.
- POST с пустым `name`, но непустым `message` сохраняется (если до бага так и было).
- Страница /feedback показывает все ранее сохранённые записи без изменений.
```

`plan.md` для исправления обычно короче: одна группа на сам фикс, одна — на регрессионный тест, ловящий именно этот баг.

`validation.md` обязательно содержит факт-репро: команду или сценарий, который **до** исправления падает, а **после** проходит. Это и есть проверка, что починили именно то, что было сломано:

```markdown
### F1 — пустое сообщение отклоняется

- Команда: `npm test -- feedback`
- Ожидание: POST /feedback с пустым message возвращает 400 и не создаёт строку
- Ответственный: автоматическая проверка
- Статус: черновик
```

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

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

## Журнал изменений перед слиянием

```text
Обнови @CHANGELOG.md по работе в этой ветке.
Используй заголовок с текущей датой.
Упомяни доменную схему, маршруты, страницы, тесты и обновления спецификаций.
Пиши кратко.
```

## Практика

- [ ] Начните вторую ветку фичи с чистого `main`.
- [ ] Создайте спецификацию через интервью.
- [ ] Реализуйте группы по частям.
- [ ] Проверьте отклонение от границ.
- [ ] Обновите журнал изменений.
- [ ] Сделайте слияние только после проверки.

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

1. Откуда берётся когнитивная нагрузка при работе с агентом и какие приёмы SDD её снижают?
2. Почему стилевые решения нужно записывать в спецификациях?
3. Какие признаки показывают, что фаза слишком большая?