Thema: Часть 11. Вторая фаза фичи
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 6-8 часов (теория: 2 часа, практика: 4-6 часов)
Voraussetzungen: Завершённая первая фаза фичи в проекте
Базовые знания Git (ветвление, слияние, fast-forward)
Опыт работы с реляционными базами данных (SQLite)
Знакомство с фреймворком Hono или аналогичным веб-фреймворком
Базовое понимание серверного рендеринга компонентов
Опыт работы с Vitest или аналогичным тестовым фреймворком
Понимание концепции миграций баз данных
Знакомство с методологией Specification-Driven Development (SDD)
Lernziele: Применять контрольный список чистого старта для подготовки второй фазы фичи, включая проверку состояния репозитория и отсутствия незавершённых изменений
Формулировать спецификацию второй фазы через структурированное интервью с тремя группами вопросов: границы, решения и контекст
Разбивать реализацию второй фазы на управляемые группы задач (5-7 задач в группе) с промежуточными коммитами для снижения когнитивной нагрузки
Создавать спецификации исправлений (bugfix.md) с обязательными разделами «Что не должно измениться» и сценариями регрессии
Проводить валидацию границ фазы с помощью целевых запросов на проверку, фокусируясь на безопасности миграций, тестовом покрытии и соответствии техническому стеку
Übersicht: Вторая фаза фичи — это критический этап в методологии Specification-Driven Development, который проверяет, стал ли процесс разработки повторяемым. Если первая фаза часто проходит на энтузиазме, то вторая демонстрирует способность команды начинать работу чисто, удерживать границы, обновлять журнал изменений и не уставать от объёма изменений. В контексте проекта AgentClinic вторая фаза получает название «Агенты и недуги» и вводит значительную функциональность: SQLite-базу данных, таблицы агентов и недугов, начальные данные, новые страницы /agents и /ailments, тесты и навигацию. Главная сложность второй фазы — когнитивная нагрузка: агент за один проход может изменить десятки файлов, и человек физически не успевает их осмыслить. Поэтому центральное место в этой фазе занимают техники управления сложностью: группировка задач, промежуточные коммиты, регулярная проверка границ и отказ от изменений, не соответствующих спецификации.
Schlüsselkonzepte: Чистый старт: Обязательная процедура перед началом новой ветки фичи: переключение на main, обновление через fast-forward, проверка отсутствия незакоммиченных изменений, запуск тестов и проверка типов. В контексте работы с AI-агентом включает очистку контекста (/clear) и проверку дорожной карты. Начинать новую фазу при наличии незавершённых изменений запрещено — иначе сгенерированные агентом изменения будет трудно объяснить и интегрировать.
Интервью для спецификации: Метод создания спецификации через три группы вопросов, задаваемых агенту перед записью файлов: (1) Границы — какие доменные сущности и страницы входят в фазу; (2) Решения — база данных, начальные данные, соглашения интерфейса, тесты; (3) Контекст — тон, ограничения, риски и что должно остаться за границами. Этот подход предотвращает утечку реализации в фазу обсуждения требований.
Когнитивная нагрузка: Феномен, при котором человек не способен осмыслить десятки одновременно изменённых файлов. Глаз скользит, ошибки проскакивают. Приёмы снижения: реализация групп задач по одной или парами, промежуточные коммиты, запросы на суммирование изменений, использование /review, отказ от принятия изменений, не соответствующих спецификации.
Группы задач: Логическое разбиение реализации фазы на 5-7 задач в группе. Примерные группы для «Агентов и недугов»: запуск базы данных, доменная схема, начальные данные, маршруты и компоненты, тесты и проверка. Каждая группа завершается промежуточным коммитом и проверкой.
Спецификация исправления (bugfix.md): Альтернативный шаблон спецификации для веток исправления ошибок. Включает: текущее поведение, ожидаемое поведение, доказательство первопричины, что не должно измениться, сценарии регрессии. Главное отличие от фичи — обязательные разделы защиты существующей функциональности.
Регрессионные сценарии: Проверки, гарантирующие, что исправление не сломало работающее. Для фикса валидации формы: POST с непустым message продолжает работать, POST с пустым name но непустым message сохраняется, существующие записи не изменяются.
Факт-репро в validation.md: Команда или сценарий, который до исправления падает, а после проходит. Пример: npm test -- feedback с ожиданием, что POST с пустым message возвращает 400. Это объективная проверка, что починили именно то, что было сломано.
Журнал изменений перед слиянием: Обязательное обновление CHANGELOG.md с заголовком текущей даты, кратким перечислением доменной схемы, маршрутов, страниц, тестов и обновлений спецификаций. Пишется кратко, но полнота важнее лаконичности.
Визуальное направление в спецификациях: Требование фиксировать стилевые решения (цвета, типографику) в спецификациях, а не оставлять только в чате. Пример: фирменные цвета AgentClinic — оранжевый и чёрный, используются как акцент, страницы остаются читаемыми.
Переработка вместо исправления: Сигнал переноса работы из режима исправления в режим фичи: несколько связанных багов, новая схема, переписывание модуля. Нормальный процесс, требующий закрытия ветки исправления и перепланирования как обычной фичи.
Übungsaufgaben: Name: Проверка готовности к чистому старту
Problem: Вы собираетесь начать вторую фазу фичи «Агенты и недуги» в проекте AgentClinic. Выполните полный контрольный список чистого старта и определите, можно ли начинать работу. Исходные данные: вы находитесь в ветке feature/first-phase, имеете 3 незакоммиченных файла в git status, тесты падают с ошибкой типизации, в директории specs/ есть черновик спецификации без даты. Опишите последовательность команд и решение о готовности.
Lösung: 1. git stash push -m 'WIP: first-phase' — сохранить незакоммиченные изменения. 2. git checkout main — переключиться на main. 3. git pull --ff-only — обновить без слияния. 4. git status --short — проверить чистоту (должно быть пусто). 5. npm test — запустить тесты (ожидаем: проходят). 6. npm run typecheck — проверить типы (ожидаем: без ошибок). 7. В Qwen Code: /clear — очистить контекст. 8. Прочитать @specs/roadmap.md и определить следующую незавершённую фазу. 9. Проверить, что черновик без даты не является активной спецификацией. Решение: работу начинать нельзя до устранения ошибки типизации в main и оформления черновика спецификации. Если ошибка типизации существует в main — это блокер, требующий исправления отдельной веткой bugfix.
Komplexität: intermediate
Name: Формулирование интервью для спецификации
Problem: Вы начинаете фазу «Агенты и недуги». Сформулируйте три группы вопросов для интервью спецификации, основываясь на контексте проекта: AgentClinic — сатирическая клиника для AI-агентов, технический стек включает Hono, SQLite, серверный рендеринг, Vitest, без клиентского JavaScript. Первая фаза реализовала главную страницу и форму обратной связи. Дорожная карта указывает на необходимость справочников агентов и недугов.
Lösung: Группа 1 — Границы: Какие доменные сущности входят в фазу? (агенты, недуги, связь agent_ailments). Какие страницы реализуем? (список /agents, детали /agents/:id, список /ailments). Что явно исключаем? (запись на приём, формы создания/редактирования, клиентский JavaScript). Группа 2 — Решения: Какую базу данных использовать? (SQLite с better-sqlite3). Как организовать миграции? (ручные, повторно запускаемые). Какие начальные данные? (вымышленные агенты и недуги с сатирическими описаниями). Какие тесты? (маршруты на Vitest, рендеринг компонентов). Какие соглашения интерфейса? (маршруты Hono, компоненты серверного рендеринга, адаптивный дизайн). Группа 3 — Контекст: Какой тон содержания? (сатирический, но реализация понятная). Какие ограничения? (без клиентского JS, интерфейс адаптивный, страницы читаемы для демонстрации). Какие риски? (когнитивная нагрузка от объёма изменений, утечка границ в формы). Что остаётся за границами? (аутентификация, админ-панель, поиск и фильтрация).
Komplexität: intermediate
Name: Разбиение на группы задач с учётом когнитивной нагрузки
Problem: Перед вами план из 15 задач для фазы «Агенты и недуги». Задачи: установка better-sqlite3, модуль подключения к БД, механизм миграций, таблица agents, таблица ailments, таблица agent_ailments, вымышленные агенты, вымышленные недуги, связь агентов с недугами, страница /agents, страница /agents/:id, страница /ailments, тесты маршрутов, тесты компонентов, запуск npm test и typecheck. Сгруппируйте задачи оптимально для снижения когнитивной нагрузки и обоснуйте группировку.
Lösung: Группа 1 — Инфраструктура БД (задачи 1-3): Установка better-sqlite3, модуль подключения, механизм миграций. Обоснование: фундамент, без которого невозможна работа схемы. Проверяется отдельно: подключение работает, миграции идемпотентны. Группа 2 — Доменная схема (задачи 4-6): Три таблицы agents, ailments, agent_ailments. Обоснование: логическая целостность схемы видна сразу, проще проверить связи. Группа 3 — Начальные данные (задачи 7-9): Сидеры для всех трёх таблиц. Обоснование: требует готовой схемы, даёт тестовые данные для ручной проверки страниц. Группа 4 — Маршруты и компоненты (задачи 10-12): Три страницы. Обоснование: визуальный результат, можно демонстрировать. Риск когнитивной нагрузки — здесь возможно дробление на подгруппы по одной странице. Группа 5 — Тесты и валидация (задачи 13-15): Тесты маршрутов, компонентов, финальный запуск. Обоснование: проверка всей фазы, обнаружение регрессий. Каждая группа — отдельный коммит, между группами — запрос агенту на суммирование изменений.
Komplexität: intermediate
Name: Создание спецификации исправления
Problem: В фазе «Агенты и недуги» обнаружен баг: страница /agents отображает агентов в порядке создания (по ID), но ожидается алфавитная сортировка по имени. При этом существует риск, что «исправление» затронет страницу /ailments, которая уже корректно сортирует по названию недуга. Создайте bugfix.md с обязательными разделами защиты.
Lösung: bugfix.md: Текущее поведение — страница /agents отображает агентов в порядке возрастания id (порядок создания), что приводит к непредсказуемому расположению при демонстрации. Ожидаемое поведение — агенты отсортированы по полю name в алфавитном порядке ASC, с учётом кириллицы (locale-aware сортировка). Доказательство первопричины — в src/routes/agents.ts запрос db.query('SELECT * FROM agents') без ORDER BY, видно в коммите фазы. Что не должно измениться — маршрут GET /ailments и его сортировка по name ailments, существующие записи в таблице agents (пересортировка без миграции), пагинация (ещё не реализована), формат ответа (HTML-страница). Сценарии регрессии — GET /agents возвращает агентов в алфавитном порядке; GET /ailments сохраняет свою сортировку; POST и другие методы для agents не затронуты; тесты /agents проверяют порядок.
Komplexität: intermediate
Name: Валидация границ фазы
Problem: Агент предложил внести в фазу «Агенты и недуги» дополнительную функциональность: форму поиска агентов по имени (клиентский JavaScript), страницу администратора для редактирования недугов, JWT-аутентификацию для админ-страницы. Сформулируйте запрос на проверку текущей ветки и определите, какие изменения следует отклонить.
Lösung: Запрос проверки: /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 (клиентский JavaScript запрещён). Файлы не изменяй. Отклоняемые изменения: форма поиска с клиентским JavaScript — прямое нарушение tech-stack.md (без клиентского JS); страница администратора — выход за границы фазы (только чтение, без форм); JWT-аутентификация — выход за границы и несоответствие фазе (справочники только для чтения). Принимаемые изменения: если поиск реализован серверно через query-параметр ?q= с обработкой на Hono — обсуждается, но скорее откладывается в следующую фазу, так как не в плане. Решение: отклонить все три предложения, зафиксировать в спецификации причину (выход за границы/технический стек), возможно создать specs/backlog/search-agents.md для будущей фазы.
Komplexität: advanced
Fallstudien: Name: AgentClinic: Провал второй фазы из-за пропущенной проверки чистого старта
Szenario: Команда из двух разработчиков работает над сатирическим проектом AgentClinic — клиникой для AI-агентов. Первая фаза (главная страница и форма обратной связи) прошла успешно, вдохновлённая энтузиазмом. Вторая фаза «Агенты и недуги» должна ввести SQLite, три таблицы, три страницы, тесты и навигацию. Разработчик А начинает работу в пятницу вечером, пропустив проверку git status.
Aufgabe: Разработчик А начал ветку от коммита, содержащего незакоммиченные экспериментальные изменения формы обратной связи (добавлено поле priority, изменена валидация). Агент Qwen Code, получив контекст с этими изменениями, включил их в генерацию второй фазы. К концу сессции в ветке оказалось 47 изменённых файлов. При попытке слияния обнаружилось: (1) форма обратной связи содержит поле priority, не описанное в спецификации первой фазы; (2) миграции базы данных конфликтуют с экспериментальной схемой; (3) тесты падают из-за пересечения изменений; (4) разработчик Б не может провести ревью — глаз скользит по 47 файлам, ошибки проскакивают.
Lösung: Команда применила аварийный протокол: 1. Создана отдельная ветка emergency/clean-state от чистого main. 2. Спецификация второй фазы пересоздана через интервью с тремя группами вопросов. 3. Реализация разбита на 5 групп задач с жёстким ограничением: не более 7 задач в группе, промежуточный коммит обязателен. 4. Введён запрет на работу с агентом после 20:00 — когнитивная нагрузка несовместима с усталостью. 5. Добавлена проверка /review после каждой группы. 6. Незавершённые изменения формы обратной связи оформлены как отдельная фича в бэклоге.
Ergebnis: Вторая попытка заняла 3 рабочих дня вместо одной пятничной вечерней сессии, но результат был: (1) 23 файла вместо 47 — управляемый объём; (2) все тесты проходят; (3) слияние прошло без конфликтов; (4) ревью заняло 45 минут вместо невозможности; (5) обнаружены 2 ошибки в миграциях на этапе групповой проверки, а не после слияния. Проект получил стабильную базу для третьей фазы.
Gewonnene Erkenntnisse: Незавершённые изменения — блокер для начала фазы, не формальность. Проверка git status --short должна быть нулевой.
Когнитивная нагрузка от 40+ файлов делает ревью физически невозможным. Группы по 5-7 задач с промежуточными коммитами — не оптимизация, а необходимость.
Время суток влияет на способность контролировать агента. Работа с большими фазами требует свежего состояния.
Агент усиливает существующий хаос, но не создаёт порядок сам. Чистый старт — ответственность человека.
Verwandte Konzepte: Чистый старт
Когнитивная нагрузка
Группы задач
Интервью для спецификации
Name: AgentClinic: Успешное применение спецификации исправления для валидации формы
Szenario: После слияния второй фазы «Агенты и недуги» пользователь обнаружил, что форма обратной связи с первой фазы пропускает пустые сообщения. Сервер возвращает 302 и сохраняет пустую строку в таблицу feedback. Команда решает не смешивать исправление с третьей фазой, а применить спецификацию исправления.
Aufgabe: Исправление кажется простым (добавить валидацию), но существует риск: (1) агент может «улучшить» соседний код формы, сломав стиль или логику; (2) изменение ответа с 302 на 400 может затронуть клиентскую обработку, если она есть; (3) существующие пустые записи в таблице требуют решения; (4) формат ошибки 400 должен совпадать с остальными маршрутами проекта.
Lösung: Создана ветка 2026-05-12-feedback-empty-message-bug со спецификацией исправления: bugfix.md с разделами текущее/ожидаемое поведение, доказательство первопричины (отложенная валидация с TODO в коммите 3a7c1b9), что не должно измениться (GET /feedback, существующие записи, имена полей, формат 400), сценарии регрессии. plan.md содержит две группы: фикс валидации и регрессионный тест. validation.md включает факт-репро: npm test -- feedback с ожиданием 400 для пустого message. Агенту явно запрещено изменять стиль страницы, добавлять клиентскую валидацию, модифицировать таблицу feedback.
Ergebnis: Исправление заняло 2 часа вместо потенциальных дней отладки побочных эффектов. Регрессионный тест поймал попытку агента изменить обработку поля name (сделать его обязательным) — изменение отклонено как выход за границы. Существующие пустые записи оставлены без изменения (решение: отдельная задача по очистке данных, не связанная с багом). Формат ошибки 400 совпал с маршрутом /agents благодаря явной спецификации.
Gewonnene Erkenntnisse: Спецификация исправления дороже краткого фикса: 30 минут написания экономят часы отладки регрессий.
Раздел «Что не должно измениться» — главный инструмент защиты от «улучшений» агента.
Факт-репро в validation.md даёт объективный критерий готовности, не зависящий от человеческой оценки.
Исправление, растущее в переработку, следует признавать рано и перепланировать как фичу — это не поражение.
Verwandte Konzepte: Спецификация исправления (bugfix.md)
Регрессионные сценарии
Факт-репро в validation.md
Переработка вместо исправления
Lerntipps: Практикуйте чистый старт как ритуал: выполняйте полный набор команд перед каждой сессией с агентом, даже если «вчера всё было нормально». Автоматизируйте через alias в shell.
Ведите личный журнал когнитивной нагрузки: записывайте, после скольких файлов глаз начинает «скользить». Индивидуальный порог обычно 15-25 файлов — используйте его как лимит для группы задач.
Создавайте шаблоны спецификаций в своём редакторе: snippets для requirements.md, bugfix.md, plan.md, validation.md. Экономия времени на форматировании увеличивает время на мышление.
Тренируйтесь формулировать «Что не должно измениться» даже для фич, не только для багфиксов — это развивает навык защиты границ.
Используйте Git визуально: git log --graph --oneline --all для понимания структуры веток, git diff --stat для оценки объёма изменений перед коммитом.
Проводите саморевью перед запросом к агенту: прочитайте свою спецификацию вслух — неясные места станут очевидны.
Изучайте чужие спецификации: разбирайте примеры из курса, выделяйте структуру, сравнивайте с собственными попытками.
Практикуйте отклонение: когда агент предлагает «улучшение», формулируйте причину отказа по спецификации, а не по интуиции — это укрепляет дисциплину.
Zusätzliche Ressourcen: Документация git по ветвлению: https://git-scm.com/book/ru/v2/Git-Branching-Основы-ветвления-и-слияния — основы для понимания чистого старта и fast-forward
Документация better-sqlite3: https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md — API для работы с SQLite в Node.js
Документация hono: https://hono.dev/docs/getting-started/basic — веб-фреймворк, используемый в проекте
Документация vitest: https://vitest.dev/guide/ — тестовый фреймворк для маршрутов и компонентов
Руководство по миграциям баз данных: https://flywaydb.org/documentation/concepts/migrations.html — концепции повторно запускаемых миграций
Курс «specification-driven development»: Исходные материалы курса, части 1-10 — для понимания контекста первой фазы и эволюции методологии
Интерактивный тренажёр git: https://learngitbranching.js.org/?locale=ru_RU — визуальное обучение ветвлению для подготовки к чистому старту
Шаблоны спецификаций проекта agentclinic: specs/templates/ в репозитории проекта — готовые заготовки для requirements.md, bugfix.md, plan.md, validation.md
Zusammenfassung: Вторая фаза фичи — это экзамен на повторяемость процесса разработки. Она отличается от первой фазы критическим требованием управления когнитивной нагрузкой: агент генерирует больше изменений, а человек должен сохранять контроль. Ключевые практики: чистый старт как невозможный без проверки, спецификация через структурированное интервью с тремя группами вопросов, разбиение на группы задач с промежуточными коммитами, спецификация исправления с защитой существующего поведения, валидация границ перед слиянием. Успех второй фазы измеряется не скоростью, а предсказуемостью: ревью возможно, тесты проходят, слияние чистое, журнал изменений актуален. Провал второй фазы — обычно результат пропущенного чистого старта или принятия непроверенных изменений. Методология SDD во второй фазе переходит от «сделать красиво» к «сделать так, чтобы третья фаза не страдала от последствий второй».