Учебный гайд: Часть 10. Перепланирование проекта

Тема: Часть 10. Перепланирование проекта

Уровень сложности: Средний

Расчётное время изучения: 3-4 часа (теория + практика)

Предварительные требования: Основы работы с Git (ветвление, слияние, коммиты)

Понимание структуры проектной документации SDD (mission.md, tech-stack.md, roadmap.md)

Базовый опыт работы с фреймворком Hono

Понимание концепции спецификаций фич (feature specs)

Базовые знания TypeScript и тестирования

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

Определять, какие наблюдения из реализации фичи следует кодифицировать в правила (QWEN.md), технические решения (tech-stack.md), шаблоны проверки (validation.md) или навыки агента

Формулировать запросы к AI-агенту для обновления спецификаций, журнала изменений и дорожной карты без реализации новых продуктовых фич

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

Обзор: Перепланирование проекта — ключевая фаза в методологии SDD (Specification-Driven Development), которая проводится между реализацией фич, а не внутри них. Это момент осознанной паузы, когда команда фиксирует полученные знания, обновляет проектные документы и превращает разовые наблюдения в постоянные правила. Чем быстрее AI-агент генерирует код, тем важнее регулярно возвращаться к проектной конституции и корректировать курс, пока отклонение ещё мало. Перепланирование отвечает на пять критических вопросов: что мы узнали, нужно ли обновить технологический стек, актуальна ли дорожная карта, какие проверки стать обязательными, и какие процессы стоит автоматизировать. Успешное перепланирование создаёт маховик обратной связи: каждое наблюдение из предыдущей фичи запускает обновление правил, которое снижает вероятность повторения той же проблемы в следующей итерации.

Ключевые концепции: Фаза перепланирования: Отдельная ветка Git, создаваемая после завершения фичи, предназначенная исключительно для обновления проектных документов без реализации новых продуктовых функций. Отличается от обычной разработки запретом на написание кода новых фич — фокус на рефлексии и кодификации.

Кодификация наблюдений: Процесс превращения разовых наблюдений из реализации фичи в постоянные артефакты проекта. Четыре типа артефактов: правила поведения агента (QWEN.md), технические решения (tech-stack.md), шаблоны проверки (validation.md), автоматизируемые навыки и хуки (.qwen/skills/).

Журнал изменений changelog.md: Документ, ведущийся с датами, который служит краткой историей проекта для людей и контекстом для AI-агента. Создаётся на основе истории Git и изменений текущей ветки, а не вручную с нуля.

Политика тестирования: Формализованное требование в tech-stack.md, определяющее инструмент (Vitest), команду запуска (npm test), и обязательность указания автоматических проверок в спецификациях фич.

Адаптивный дизайн как проектное правило: Требование уровня проекта, а не отдельной фичи: страницы должны работать на мобильной ширине 375px и настольной 1280px. После кодификации применяется ретроспективно ко всем существующим спецификациям.

Размер фазы дорожной карты: Критерий проверяемости: фаза не должна быть ни слишком широкой ('построить все фичи'), ни слишком мелкой ('добавить один CSS-отступ'). Оптимальная фаза имеет конкретную доменную цель и 3-5 проверяемых задач.

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

Обновление старых спецификаций: Процесс приведения завершённых спецификаций фич к новым проектным правилам без изменения реализации, если это не требуется обновлённой проверкой. Сохраняет историческую точность: спецификация объясняет, какие правила действовали на момент реализации.

Ветка перепланирования: Изолированная линия разработки (например, replanning-after-hello-hono), которая начинается от main, содержит только изменения документов, и сливается обратно через merge после проверки тестов и типов.

Практические упражнения: Название: Создание ветки перепланирования и формулировка запроса

Проблема: Вы завершили первую фичу 'Hello Hono' в проекте на Hono + TypeScript. Наблюдения: агент дважды забыл запускать тесты перед коммитом; макет выглядит плохо на телефоне; в спецификации не было раздела 'Проверка'; вы трижды просили агента прочитать mission.md перед работой. Создайте ветку перепланирования и сформулируйте запрос к агенту, который обновит проектные документы без реализации новых фич.

Решение: 1. Создать ветку: git checkout -b replanning-after-hello-hono

1. Сформулировать запрос с чёткими ограничениями:

/clear Прочитай @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md и завершённую спецификацию фичи Hello Hono. Мы проводим фазу перепланирования. Не реализуй новые продуктовые фичи. Предложи изменения для:

1. политики тестирования с обязательным запуском перед коммитом;
2. адаптивного дизайна как общего требования (375px/1280px);
3. шаблона проверки в спецификациях фич;
4. автоматизации чтения mission.md через навык.

Перед правкой перечисли предлагаемые изменения файлов.

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

Сложность: beginner

Название: Кодификация наблюдений в правильные артефакты

Проблема: После фичи 'Hello Hono' вы зафиксировали 6 наблюдений. Распределите их по типам артефактов и объясните выбор: (а) Агент изменил tsconfig.json без разрешения и сломал сборку (б) Vitest оказался удобнее, чем ручное тестирование (в) Для миграции базы данных не проверялась идемпотентность повторного запуска (г) Запрос 'сгенерируй спецификацию для фичи X по шаблону Y' использован 5 раз (д) Агент не нашёл файл с константами, хотя он был в проекте (е) Реализация добавила поле 'status', которого не было в requirements.md

Решение: 1. (а) → QWEN.md (правило поведения агента): 'Никогда не меняй tsconfig.json без подтверждения человека'

1. (б) → tech-stack.md (техническое решение): 'Используем Vitest для всех тестов, npm test запускает vitest run'
2. (в) → validation.md (шаблон проверки): 'Для миграции проверять идемпотентность повторным запуском'
3. (г) → .qwen/skills/spec-generation/SKILL.md (навык): автоматизировать запрос с параметрами фичи
4. (д) → QWEN.md (расширить список 'что прочитать в начале'): добавить файл констант
5. (е) → requirements.md через ветку перепланирования (обратная трассировка): задним числом зафиксировать решение
6. Обоснование: выбор определяется природой наблюдения — поведение агента, технический выбор, форма проверки, механическое повторение, структура проекта, требования.

Сложность: intermediate

Название: Оценка и исправление дорожной карты

Проблема: Проанализируйте три варианта фазы 2 дорожной карты и определите, какой соответствует критериям хорошей фазы. Предложите исправления для некорректных вариантов:

Вариант А:

Фаза 2: построить всё приложение

• [ ] Добавить базу данных
• [ ] Сделать все страницы
• [ ] Написать тесты

Вариант Б:

Фаза 2: добавить padding-top в заголовок Hello Hono

• [ ] Изменить CSS

Вариант В:

Фаза 2: Агенты и недуги

Цель: добавить базовую доменную модель и страницы только для чтения.

• [ ] Добавить SQLite-схему для агентов и недугов.
• [ ] Добавить начальные вымышленные данные.
• [ ] Добавить страницы /agents и /ailments.
• [ ] Добавить тесты маршрутов и компонентов.

Решение: 1. Вариант А — слишком широкий. Проблемы: 'всё приложение' непроверяемо; 'все страницы' не конкретны; объём изменений затруднит человеческую проверку. Исправление: разбить на 2-3 фазы с доменными границами (например, 'Агенты и недуги', 'Заявки и назначения', 'Администрирование').

1. Вариант Б — слишком мелкий. Проблемы: накладные расходы на ветку, код-ревью, merge превышают ценность; нет доменного смысла. Исправление: объединить с другими CSS-задачами в фазу 'Базовый макет и навигация' или включить как подзадачу в более крупную фазу.
2. Вариант В — корректный. Проверка: конкретная доменная цель ('базовая доменная модель'); 4 проверяемые задачи; чёткие границы ('только для чтения'); измеримый результат (4 чекбокса).
3. Общий принцип: фаза должна быть 'проверяема за вечер' и нести доменную ценность.

Сложность: intermediate

Название: Создание CHANGELOG.md и обновление через агента

Проблема: После завершения ветки перепланирования с изменениями в tech-stack.md, validation.md и roadmap.md сформулируйте запрос к агенту для создания или обновления CHANGELOG.md. Исходные данные: ветка создана 2026-05-01, коммиты содержат добавление Vitest, правило адаптивного дизайна, уточнение фаз 2-3 дорожной карты.

Решение: 1. Запрос к агенту: /clear Создай или обнови @CHANGELOG.md. Используй заголовки с датами в формате YYYY-MM-DD. Опирайся на историю Git ветки replanning-after-hello-hono и изменения текущей ветки. Пиши кратко и понятно для заинтересованных людей. Каждый пункт должен быть одной строкой, начинающейся с глагола.

1. Ожидаемый результат:

# Журнал изменений ## 2026-05-01

• Добавлена политика тестирования с Vitest (npm test → vitest run).
• Введено требование адаптивного дизайна (375px/1280px).
• Уточнены границы фаз 2 и 3 дорожной карты по доменным областям.
• Обновлён шаблон спецификации фичи разделом 'Обязательные проверки'.

1. Проверка: даты соответствуют коммитам, пункты атомарны, язык — для людей, но структурирован для парсинга агентом.

Сложность: beginner

Название: Применение маховика обратной связи

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

1. Агент сгенерировал миграцию, которая падает при повторном применении на той же базе
2. Агент не смог найти файл с типами доменной модели, хотя он лежал в /src/types/
3. Человек заметил, что страница /agents не отображается корректно на iPhone SE, хотя тесты прошли
4. Агент трижды спрашивал, какой формат ответа API использовать
5. В спецификацию фичи случайно попал пример с реальным именем клиента

Решение: 1. Миграция падает повторно → validation.md: новый шаблон 'Для миграции проверять идемпотентность повторным запуском' (уровень проверки повышается).

1. Не найден файл в /src/types/ → QWEN.md: расширить список 'что прочитать в начале' указанием на структуру директорий; возможно, добавить правило 'перед созданием типа проверь существующие в /src/types/'.
2. Тесты прошли, но реальное поведение неверно → validation.md: добавить факт 'Для страниц с данными проверять рендеринг на ширине 375px в addition к функциональным тестам'; возможно, ввести уровень визуальной проверки (см. часть 9).
3. Трижды спрашивал формат API → .qwen/skills/api-response-format/SKILL.md: закодифицировать стандарт ответа (JSON, поля, коды ошибок).
4. Реальное имя в спецификации → QWEN.md: правило 'Никогда не используй реальные данные клиентов в примерах' + validation.md: сценарий проверки на поиск PII (см. часть 18).
5. Проверка: для всех 5 случаев найдено место в существующей структуре — значит, структура адекватна. Если бы для какого-то наблюдения место не нашлось, это сигнал создать новый раздел.

Сложность: advanced

Кейсы: Название: Перепланирование после первой фичи в проекте медицинской платформы

Сценарий: Команда из двух разработчиков и продакт-менеджера внедряет SDD для внутренней платформы управления пациентами. Первая фича 'Hello Hono' — базовая страница приветствия с серверным рендерингом JSX — реализована за 2 дня с помощью AI-агента Qwen Code. Команда собирается сразу приступить к фиче 'Регистрация пациентов'.

Задача: Продакт-менеджер замечает, что страница приветствия отображается некорректно на его iPhone 12 mini (ширина 375px), хотя на десктопе всё в порядке. Разработчик А обнаруживает, что агент забыл запустить тесты перед финальным коммитом и пришлось исправлять ошибку TypeScript вручную. Разработчик Б трижды давал агенту один и тот же запрос: 'Прочитай mission.md, затем сгенерируй спецификацию для фичи X по шаблону из specs/templates/'. Дорожная карта содержит фазу 2: 'Реализовать весь модуль пациентов' без детализации. Команда понимает, что без паузы для рефлексии следующая фича повторит те же проблемы.

Решение: Команда создаёт ветку replanning-after-hello-hono и проводит фазу перепланирования длительностью 4 часа. Запрос к агенту содержит чёткий запрет на реализацию новых фич. Последовательность действий: (1) Агент анализирует завершённую спецификацию Hello Hono и предлагает изменения; (2) В tech-stack.md добавляется политика тестирования Vitest с обязательным npm test и требование адаптивного дизайна (375px/1280px); (3) В validation.md вводится шаблон 'Для страниц проверять рендеринг на мобильной ширине'; (4) Создаётся CHANGELOG.md с историей проекта; (5) Фаза 2 разбивается на 'Пациенты: чтение' (схема, страницы, тесты) и 'Пациенты: запись' (формы, валидация, безопасность); (6) Повторяющийся запрос кодифицируется в навык .qwen/skills/spec-generation/SKILL.md. Старые спецификации обновляются под новые правила без изменения реализации.

Результат: Время на ручные исправления при реализации фичи 'Пациенты: чтение' сокращается на 60%. Агент автоматически запускает тесты и проверяет адаптивность. Спецификация генерируется одним вызовом навыка вместо трёх итераций запросов. Человеческая проверка фазы занимает 2 часа вместо ожидаемых 6 часов для монолитной фазы. CHANGELOG.md позволяет новому разработчику, подключённому через месяц, понять историю проекта за 15 минут.

Извлечённые уроки: Перепланирование между фичами экономит больше времени, чем занимает, за счёт предотвращения повторения ошибок

Кодификация повторяющихся запросов в навыки агента имеет множительный эффект на каждой следующей фиче

Требование адаптивного дизайна на уровне проекта дешевле, чем исправление каждой страницы отдельно

Разбиение монолитной фазы на проверяемые итерации снижает когнитивную нагрузку человека-ревьюера

Журнал изменений полезен не только для людей, но и как контекст для будущих запросов к агенту

Связанные концепции: Фаза перепланирования

Кодификация наблюдений

Маховик обратной связи

Размер фазы дорожной карты

Журнал изменений CHANGELOG.md

Название: Неудачное перепланирование: последствия пропуска фазы

Сценарий: Стартап по разработке SaaS-инструмента для юристов использует SDD с агентом Qwen Code. После первой фичи 'Hello Hono' команда сразу переходит к фиче 'Документы: загрузка', пропуская перепланирование из-за 'дедлайна демо для инвесторов'.

Задача: В фиче 'Документы' агент повторяет три ошибки из Hello Hono: не запускает тесты (обнаружено в последний день), генерирует страницу без мобильной версии (юрист показывает демо с телефона — провал), использует другой формат API-ответа, чем в первой фиче (фронтенд ломается при интеграции). Команда тратит 3 дня на исправления вместо запланированных 2 дней на реализацию. Дорожная карта остаётся неизменённой: фаза 3 — 'Все остальные функции' — делает планирование бессмысленным.

Решение: После провала демо команда проводит вынужденное перепланирование в кризисном режиме. Анализ показывает, что 70% проблем были предсказуемы по наблюдениям из первой фичи. В tech-stack.md вводятся правила ретроспективно, но уже после двойной работы. Старые спецификации приходится обновлять с изменением реализации, так как интеграция сломана. Навык для генерации спецификаций создаётся, но теряет часть контекста из-за давления.

Результат: Проект отстаёт на 2 недели от плана. Команда вводит обязательную фазу перепланирования длительностью 1 день между любыми фичами как hard rule. Создаётся внутреннее правило: 'Нет перепланирования — нет ветки для следующей фичи'. Позитивный побочный эффект: сформирована культура кодификации, команда начинает вести CHANGELOG.md и регулярно обновлять маховик обратной связи.

Извлечённые уроки: Пропуск перепланирования ради скорости создаёт иллюзию экономии времени

Повторяющиеся ошибки агента — не случайность, а сигнал отсутствия правила

Кризисное перепланирование дороже планового: требуется изменение реализации, не только документов

Жёсткое правило 'перепланирование обязательно' защищает от оптимизации под краткосрочное давление

Связанные концепции: Маховик обратной связи

Кодификация наблюдений

Фаза перепланирования

Обновление старых спецификаций

Советы по изучению: Практикуйте создание веток перепланирования физически: откройте терминал, выполните git checkout -b replanning-after-..., напишите осмысленный коммит. Мышечная память важнее теоретического понимания для этого процесса.

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

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

Создайте шаблоны для четырёх типов артефактов кодификации в своём редакторе (сниппеты или фрагменты). Это ускорит переход от наблюдения к записи.

Проверяйте размер фазы дорожной карты правилом 'проверяем за вечер': если не можете представить, как за один вечер убедиться, что всё работает — фаза слишком большая.

Читайте CHANGELOG.md перед каждой новой фичей как контекст — так вы поймёте его ценность для агента и для себя.

Практикуйте различение 'правила уровня проекта' и 'решения уровня фичи': адаптивный дизайн — проект, конкретный padding — фича. Ошибка здесь приводит к непоследовательным спецификациям.

Используйте технику '5 почему' для каждого наблюдения: почему агент ошибся? Почему не нашёл файл? Почему повторил запрос? Корневые причины указывают на правильный артефакт кодификации.

Дополнительные ресурсы: Оригинальный курс sdd (части 1-18): Полный контекст методологии Specification-Driven Development с акцентом на работу с AI-агентами

Часть 9 курса (уровни проверки): Детальное рассмотрение шаблонов validation.md и повышения уровней проверки при обнаружении ошибок

Часть 14 курса (хуки и навыки): Механика создания .qwen/skills/ и автоматизации повторяющихся запросов

Часть 17 курса (защитные хуки): Предотвращение опасных команд через автоматизацию

Часть 18 курса (безопасность и секреты): Правила предотвращения утечки PII и конфиденциальных данных в спецификации

Документация vitest: https://vitest.dev — для глубокого понимания настройки политики тестирования

Руководство по conventional commits: Стандартизация сообщений коммитов, полезная для автоматического CHANGELOG.md

Keep a changelog: https://keepachangelog.com — международная практика ведения журнала изменений (адаптируйте под формат курса)

Резюме: Перепланирование проекта — стратегическая пауза между фичами в SDD, превращающая хаотичные наблюдения в системные правила. Его цель не ускорить разработку, а предотвратить повторение ошибок через кодификацию: правила в QWEN.md, технические решения в tech-stack.md, шаблоны в validation.md, навыки в .qwen/skills/. Ключевые практики: отдельная ветка Git с запретом на новые фичи, обновление старых спецификаций без изменения реализации, ведение CHANGELOG.md как коммуникации для людей и контекста для агента, правильный размер фаз дорожной карты (проверяем за вечер), маховик обратной связи с предопределёнными реакциями на сигналы. Пропуск перепланирования создаёт иллюзию скорости и удваивает технический долг. Регулярная кодификация 2-3 самых частых наблюдений за итерацию формируёт самоусиливающуюся систему качества.