Thema: Часть 13. Поддержка существующего проекта
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 6-8 часов (теория + практика)
Voraussetzungen: Базовое понимание SDD (Spec-Driven Development)
Опыт работы с Git и системами контроля версий
Знакомство с TypeScript/JavaScript и веб-фреймворками
Понимание структуры проектов (package.json, маршруты, тесты)
Опыт работы с AI-ассистентами (Qwen Code или аналоги)
Lernziele: Восстанавливать конституцию проекта (mission.md, tech-stack.md, roadmap.md) из существующего кода и документации без переписывания приложения
Различать факты, предположения и неизвестные зоны при анализе унаследованного кода и формулировать уточняющие вопросы для команды
Преобразовывать неструктурированные TODO и задачи трекера в фазированную дорожную карту с чёткими приоритетами
Применять обычный цикл SDD для реализации новых фич в существующем проекте, сохраняя существующие соглашения кода
Идентифицировать и минимизировать риски SDD в существующем проекте: устаревший README, случайный код как правило, тесты, закрепляющие ошибки
Übersicht: Эта часть курса посвящена применению подхода Spec-Driven Development (SDD) не к новому, а к уже существующему проекту. Ключевая идея: SDD полезен не только для зелёного поля. В существующем проекте спецификации можно восстановить из кода, README, TODO, трекера задач, журнала изменений, тестов и архитектурных документов. Это не «переписать старый код» — это добавить слой намерения, которого раньше не хватало. Вы научитесь проводить археологию кода: извлекать факты, отделять их от предположений, формировать конституцию проекта через интервью с AI-ассистентом, а затем продолжать обычный цикл SDD. Особое внимание уделяется рискам: устаревшей документации, случайному коду, принятому за архитектурное правило, и соблазну «подчистить» проект в ветке фичи без явного разрешения.
Schlüsselkonzepte: Восстановление конституции: Процесс создания specs/mission.md, specs/tech-stack.md и specs/roadmap.md на основе анализа существующего проекта без его переписывания. Конституция добавляет слой намерения, которого раньше не хватало, и служит фундаментом для дальнейшей работы по SDD.
Факты vs. предположения vs. неизвестное: Критически важное разделение при анализе существующего проекта. Факты — то, что можно доказать по коду (например, используется TypeScript). Предположения — интерпретации, требующие проверки (например, «это микросервисная архитектура»). Неизвестное — пробелы, которые нужно заполнить вопросами (например, цель развёртывания).
Процесс восстановления: Структурированный подход: существующий проект → восстановление (конституция) → продолжение обычного цикла SDD. Это обеспечивает непрерывность: проект не останавливается для «большого рефакторинга», а постепенно обрастает спецификациями.
Интервью с ai-ассистентом: Метод работы с Qwen Code, при котором ассистент задаёт уточняющие вопросы перед записью файлов. Три группы вопросов: пробелы в миссии, предположения в технологическом стеке, приоритеты дорожной карты. Это защищает от выдуманной архитектуры.
Дорожная карта из todo: Преобразование неструктурированного списка задач в фазированный план с чёткими границами. Каждая фаза содержит конкретные, проверяемые шаги. Позволяет избежать «бесконечного TODO» и даёт точки принятия решений.
Существующие соглашения кода: Найденные паттерны в структуре проекта (где лежат маршруты, компоненты, тесты, миграции). Ключевое правило: не добавлять новую архитектуру при подключении SDD к существующему проекту, сохранять поведение существующих маршрутов.
Риски sdd в существующем проекте: Специфические опасности: случайный старый код принимается за архитектурное правило; README устарел; TODO не отражает текущий приоритет; тесты закрепляют ошибки; соблазн «очистить» проект в ветке фичи. Противоядие — явное разделение «наблюдаемого», «решённого» и «неизвестного».
Спецификация фичи для существующего проекта: После восстановления конституции применяется обычный цикл SDD: найти следующую незавершённую фазу в roadmap.md, создать спецификацию фичи, использовать существующие соглашения, спросить о границах перед записью файлов.
Übungsaufgaben: Name: Упражнение 1: Археология кода — сбор фактов
Problem: Вам дан существующий проект AgentClinic MVP без папки specs/. Используя предоставленный запрос для Qwen Code, проведите анализ проекта. Проект содержит: README.md с общим описанием клиники, TODO.md с 8 пунктами, package.json с зависимостями, папки src/routes, src/components, src/db/migrations, tests/. Ваша задача — составить список только из фактов, отделив их от предположений. Затем сформулируйте 3 вопроса в каждой из трёх групп (миссия, технологический стек, дорожная карта).
Lösung: Шаг 1: Запустите анализ с запросом «Изучи проект и составь список только из фактов...». Шаг 2: Проверьте полученный список на наличие предположений (например, если агент написал «используется микросервисная архитектура» — это предположение, факт: «единая точка входа в src/index.ts»). Шаг 3: Сгруппируйте факты: среда выполнения (Node.js 18 из package.json), фреймворк (Hono из dependencies), скрипты (dev, build, test из package.json), хранение (better-sqlite3 в dependencies, папка migrations), маршруты (файлы в src/routes), тесты (Vitest из devDependencies). Шаг 4: Сформулируйте вопросы группы 1 (миссия): «Какова целевая аудитория — частные пациенты или корпоративные клиенты?», «Есть ли планы на мобильное приложение?», «Какая юрисдикция регулирует обработку медицинских данных?». Группа 2 (технологический стек): «Где развёртывается приложение — VPS, облако, on-premise?», «Есть ли CI/CD пайплайн?», «Какой линтер и форматтер используются — ESLint, Prettier, Biome?». Группа 3 (дорожная карта): «Какой пункт TODO блокирует другие задачи?», «Есть ли дедлайны от регулятора?», «Какие пункты уже начаты в коде, но не отмечены в TODO?». Шаг 5: Сравните свои вопросы с ответами ментора или коллеги, уточните конституцию.
Komplexität: beginner
Name: Упражнение 2: Восстановление tech-stack.md
Problem: На основе фактов, собранных в упражнении 1, создайте файл specs/tech-stack.md для существующего проекта. Проект использует: TypeScript, Hono с JSX-рендерингом на сервере, better-sqlite3 для SQLite, Vitest для тестов. Структура: src/routes, src/components, src/db/migrations, tests/. Неизвестно: цель развёртывания, конфигурация CI, политика линтинга. Также в коде обнаружен нестандартный паттерн: некоторые маршруты используют прямой SQL, другие — абстракцию из src/db/queries.ts.
Komplexität: intermediate
Name: Упражнение 3: Преобразование TODO в фазированную дорожную карту
Problem: Дан TODO.md проекта: «Добавить форму обратной связи», «Добавить страницу о компании», «Добавить отзывы клиентов», «Добавить карту на страницу о компании», «Добавить онлайн-запись», «Интеграция с телеграм-ботом для напоминаний». Приоритеты бизнеса: форма обратной связи нужна для лицензии (юридическое требование), онлайн-запись — главная цель MVP, телеграм-бот — nice-to-have. Страница о компании и отзывы — маркетинг. Преобразуйте в дорожную карту с фазами, учитывая зависимости и приоритеты.
Lösung: Шаг 1: Проанализируйте зависимости между задачами. Карта зависит от страницы о компании. Отзывы можно добавить на страницу о компании или отдельно. Онлайн-запись не зависит от других задач, но критична для бизнеса. Шаг 2: Расставьте приоритеты с учётом бизнес-целей: Фаза 0 (юридический минимум): форма обратной связи. Фаза 1 (основная ценность): онлайн-запись. Фаза 2 (маркетинговая основа): страница о компании. Фаза 3 (расширение страницы): карта на странице о компании. Фаза 4 (социальное доказательство): отзывы клиентов. Фаза 5 (удобство): телеграм-бот для напоминаний. Шаг 3: Детализируйте каждую фазу проверяемыми шагами. Пример для Фазы 1: «Добавить таблицу appointments со статусами», «Добавить маршрут /booking с выбором специалиста», «Добавить валидацию пересечения слотов», «Добавить тесты на граничные случаи (переход через полночь, часовые пояса)». Шаг 4: Добавьте критерии перехода между фазами: форма обратной связи принята юристом, онлайн-запись протестирована 5 реальными пользователями. Шаг 5: Зафиксируйте в roadmap.md с отметками о приоритетах и блокировках.
Komplexität: intermediate
Name: Упражнение 4: Реализация фичи с соблюдением существующих соглашений
Problem: Реализуйте «Фазу 1: форма обратной связи» из roadmap.md. Существующие соглашения проекта: маршруты в src/routes с именованием [feature].ts, компоненты форм в src/components/forms, валидация через Zod (уже используется в одном маршруте), тесты интеграционные в tests/routes. В коде обнаружен конфликт: один разработчик использовал прямой SQL в маршрутах, другой — абстракцию queries.ts. Спецификация фичи не требует решения этого конфликта. Как вы поступите?
Lösung: Шаг 1: Создайте спецификацию фичи с явным указанием: «Использовать существующие соглашения; не решать архитектурный конфликт SQL vs. queries.ts в рамках этой фичи». Шаг 2: Выберите подход, консистентный с большинством существующего кода. Если 70% маршрутов используют queries.ts — используйте его; если большинство прямой SQL — используйте прямой SQL с комментарием «следовать паттерну существующих маршрутов». Шаг 3: Создайте specs/features/feedback-form.md с границами: входные данные (имя, email, телефон, сообщение, согласие на обработку), валидация (Zod-схема), маршрут POST /api/feedback, страница /feedback, тесты (успешная отправка, валидация ошибок, XSS-защита). Шаг 4: Перед записью файлов задайте уточняющие вопросы: «Куда отправляются уведомления — email администратора, Telegram, CRM?», «Нужна ли капча?», «Сохранять ли неуспешные попытки для анализа спама?». Шаг 5: Реализуйте фичу, сохранив поведение существующих маршрутов. Шаг 6: Зафиксируйте технический долг: «Архитектурный конфликт SQL vs. queries.ts требует отдельной спецификации рефакторинга».
Komplexität: advanced
Name: Упражнение 5: Защита от риска «тесты закрепляют ошибки»
Problem: При анализе проекта обнаружено: тест tests/routes/appointment.test.ts проходит, но проверяет неверное поведение — при пересечении слотов создаётся две записи вместо ошибки. Это известный баг #47 в трекере, отложенный на 3 месяца. Тест был написан до обнаружения бага и фиксирует текущее (ошибочное) поведение. Вы готовите спецификацию фичи «онлайн-запись», которая затрагивает эту область. Как поступить?
Lösung: Шаг 1: Зафиксируйте факт в tech-stack.md в разделе «Рискованные зоны»: «tests/routes/appointment.test.ts: тест №3 проверяет создание пересекающихся слотов, что является багом #47. Тест проходит, фиксируя ошибочное поведение». Шаг 2: В спецификации фичи «онлайн-запись» явно укажите границу: «Если спецификация не требует иного, сохранить поведение существующих маршрутов. Баг #47 вне scope этой фичи». Шаг 3: Если спецификация требует корректного поведения (что логично для онлайн-записи), создайте отдельную спецификацию рефакторинга: «Исправление бага #47: пересечение слотов должно возвращать 409 Conflict». Шаг 4: В спецификации рефакторинга укажите: обновить тест №3 на проверку ошибки, добавить тест на граничный случай (слот заканчивается ровно когда начинается другой — не считается пересечением). Шаг 5: Получите явное разрешение на рефакторинг ответственного лица, поскольку это меняет существующее поведение. Шаг 6: Никогда не «подчищайте» баг «по пути» в ветке фичи — это нарушает принцип атомарности изменений и усложняет code review.
Komplexität: advanced
Fallstudien: Name: Кейс: Внедрение SDD в унаследованный проект медицинской клиники
Szenario: Компания «Здоровье+» разрабатывает веб-приложение для частной клиники с 2022 года. Проект написан на TypeScript + Hono, использует SQLite, развёрнут на VPS. За 2 года сменилось 4 разработчика, каждый оставил свой почерк: разные стили кода, противоречивые подходы к SQL, устаревший README (ещё от первого разработчика, упоминает Express вместо Hono). TODO.md содержит 23 пункта, часть выполнена, часть устарела, часть дублируется в трекере задач. Новый технический директор хочет внедрить SDD без остановки разработки. Команда из 2 разработчиков боится «большого рефакторинга».
Aufgabe: Главные проблемы: (1) README устарел на 18 месяцев и вводит в заблуждение — новые разработчики теряют время; (2) архитектурные решения не документированы, каждый разработчик интерпретировал структуру по-своему; (3) TODO.md и трекер задач не синхронизированы, приоритеты неясны; (4) тесты покрывают 40% кода, при этом 3 теста фиксируют известные баги (разработчики «не успели» их исправить); (5) соблазн «подчистить» код при добавлении новых фич — уже дважды приводил к регрессиям в продакшене.
Lösung: Технический директор применил подход из Части 13. Шаг 1: Использовал Qwen Code с запросом сбора фактов — получил объективную картину за 30 минут вместо недель «погружения». Шаг 2: Провёл интервью с ассистентом по трём группам вопросов, уточнив миссию (целевая аудитория сместилась с частных пациентов на корпоративных), технологический стек (обнаружил незадокументированный Redis для сессий), приоритеты (юридическое требование — форма обратной связи — оказалось забыт в трекере). Шаг 3: Создал конституцию с явным разделением: «Обнаружено», «Найденные соглашения», «Неизвестно», «Ограничения». В tech-stack.md зафиксировал архитектурный конфликт SQL vs. абстракция и пометил его как «не решать без спецификации рефакторинга». Шаг 4: Преобразовал TODO в фазированную дорожную карту: Фаза 0 (юридический минимум), Фаза 1 (онлайн-запись — главная ценность для корпоративных клиентов), Фаза 2-4 (маркетинг, интеграции). Шаг 5: Реализовал Фазу 0 через спецификацию фичи, явно сохранив существующие соглашения. Шаг 6: Для багов, фиксируемых тестами, создал отдельные спецификации рефакторинга с явным приоритетом и согласованием.
Ergebnis: Через 2 недели проект получил работающую конституцию. Новый разработчик, пришедший на 3-ю неделю, разобрался в проекте за 2 дня вместо 2 недель. Форма обратной связи была реализована за 3 дня без регрессий. Архитектурный конфликт SQL был запланирован на квартал 2 с отдельной спецификацией и бюджетом. Технический директор отметил: «Мы наконец видим, что происходит, вместо того чтобы бояться кода».
Gewonnene Erkenntnisse: Устаревший README хуже отсутствующего — он активно вредит новым разработчикам. Восстановление конституции должно начинаться с проверки актуальности существующих документов.
Интервью с AI-ассистентом по трём группам вопросов выявляет пробелы, которые человек, погружённый в проект, перестаёт замечать. Внешний «наивный» взгляд критически важен.
Явное разделение фактов, предположений и неизвестного защищает от «выдуманной архитектуры» — главного риска при работе с унаследованным кодом.
Соблазн «подчистить по пути» никогда не оправдывается. Отдельные спецификации рефакторинга с явным приоритетом и бюджетом — единственный устойчивый путь.
Тесты, фиксирующие баги, должны быть явно помечены в конституции как «рискованные зоны» — иначе они будут воспроизводить ошибки бесконечно.
Verwandte Konzepte: Восстановление конституции
Факты vs. предположения vs. неизвестное
Интервью с AI-ассистентом
Дорожная карта из TODO
Риски SDD в существующем проекте
Спецификация фичи для существующего проекта
Name: Кейс: Неудачная попытка «быстрого SDD» и возврат к процессу
Szenario: Стартап «FastMed» решил ускорить внедрение SDD в существующий проект, пропустив фазу восстановления конституции. Техлид поручил разработчику «просто начать писать спецификации фич» для нового функционала — интеграции с лабораторией. Разработчик изучил код за полдня и написал specs/features/lab-integration.md.
Aufgabe: Разработчик не провёл интервью по трём группам вопросов, не отделил факты от предположений. В спецификации он предположил, что проект использует REST API для всех интеграций (на самом деле, существующая интеграция с аптекой использовала SOAP из-за требований партнёра). Он также не заметил, что в src/db/ существует две системы миграций: knex-миграции (устаревшие) и ручные SQL-файлы (текущие). В спецификации предложил использовать Prisma — новый ORM, которого не было в проекте. При реализации возникли конфликты: SOAP-требование лаборатории было упущено, миграция на Prisma сломала существующую схему, тесты начали падать из-за изменения поведения старых маршрутов аптеки.
Lösung: После 2 недель «пожара» команда вернулась к процессу из Части 13. Остановила разработку новых фич на 3 дня (не на рефакторинг, а на восстановление конституции). Использовала Qwen Code для сбора фактов — обнаружила SOAP-интеграцию, двойную систему миграций, незадокументированный крон для синхронизации остатков. Провела интервью, уточнив приоритеты: лаборатория требовала SOAP, отказ невозможен. Создала tech-stack.md с явным ограничением: «Не добавлять новые ORM или фреймворки». Преобразовала интеграцию с лабораторией в Фазу 2 дорожной карты, после унификации подхода к интеграциям (Фаза 1).
Ergebnis: Проект потерял 2 недели на исправление, но сэкономил месяцы будущих проблем. Унификация подхода к интеграциям (SOAP-обёртка для всех медицинских партнёров) стала архитектурным решением, задокументированным в конституции. Техлид внедрил правило: «Никаких спецификаций фич без актуальной конституции».
Gewonnene Erkenntnisse: Пропуск фазы восстановления конституции кажется экономией времени, но всегда приводит к дорогостоящим ошибкам. «Быстрый SDD» — это не SDD.
Предположения о «современных» технологиях (REST, Prisma) опасны в существующих проектах, где исторические решения обусловлены внешними требованиями (SOAP по требованию партнёра).
Двойные системы миграций, незадокументированные кроны и другие «технические тайны» всплывают только при систематическом сборе фактов, а не при поверхностном изучении кода.
Ограничение «не добавлять новый фреймворк» в tech-stack.md защищает от технологического разбухания и сохраняет когнитивную нагрузку команды.
Иногда нужно смириться с 3-дневной паузой для восстановления конституции — это инвестиция, а не потеря.
Verwandte Konzepte: Восстановление конституции
Факты vs. предположения vs. неизвестное
Особые риски SDD в существующем проекте
Существующие соглашения кода
Процесс восстановления
Lerntipps: Практикуйтесь на реальном проекте: возьмите свой старый pet-project или рабочий проект, удалите/переименуйте specs/, и пройдите полный цикл восстановления. Теория без практики на реальном коде не закрепляется.
Ведите «дневник археолога» во время сбора фактов: записывайте, что вы думали до анализа и что обнаружили. Это развивает метакогнитивный навык распознавания собственных предположений.
Используйте технику «преподавания»: объясните восстановленную конституцию коллеге или запишите видео. Если вам непонятно, почему в tech-stack.md раздел «Неизвестно» важен — вы ещё не освоили материал.
Для визуальных учеников: создайте схему процесса «Существующий проект → Восстановление → Продолжение» и повесьте её рядом с рабочим местом. Отмечайте, на каком этапе вы сейчас находитесь.
Для аудиальных учеников: диктуйте запросы для Qwen Code вслух перед отправкой. Это помогает выявить нечёткость формулировок и лишние предположения.
Для кинестетиков: физически выделите три зоны в конституции разными цветами (зелёный — факты, жёлтый — предположения, красный — неизвестное). Цветовое кодирование ускоряет распознавание паттернов.
Тренируйтесь формулировать «плохие» вопросы и превращать их в «хорошие». Плохой: «Почему здесь так плохо написано?» Хороший: «Какое намерение стояло за этим решением, и сохраняется ли оно?»
Создайте чек-лист для проверки готовности конституции перед первой спецификацией фичи: README проверен на актуальность, тесты проверены на «фиксацию багов», архитектурные конфликты явно помечены как «не решать в фиче».
Используйте технику «красная команда»: попросите коллегу найти предположения в вашей конституции, выдавая их за факты. Это имитирует опасность «выдуманной архитектуры».
Делайте регулярные «аудиты конституции»: раз в квартал перезапускайте сбор фактов и сравнивайте с текущей конституцией. Проекты живут, конституция должна жить тоже.
Zusätzliche Ressourcen: Исходный документ курса (часть 13): Основной материал, на котором построен гайд. Перечитывайте после каждого практического упражнения — понимание углубится.
Книга «working effectively with legacy code» майкла физерса: Классика по работе с унаследованным кодом. Дополняет SDD техническими приёмами безопасного изменения кода (seams, characterization tests).
Статья «archaeology of code: reading the layers» марина захаровой: Методология чтения кода как археологических слоёв — полезна для развития навыка отделения фактов от предположений.
Документация qwen code по контекстным запросам: Официальные примеры работы с @-ссылками на файлы и дерево кода. Критично для точного сбора фактов.
Шаблоны конституции проекта (mission.md, tech-stack.md, roadmap.md): Создайте собственные шаблоны на основе примеров из курса. Стандартизация ускоряет восстановление на новых проектах.
Интерактивный симулятор: agentclinic mvp без specs/: Учебный сценарий из курса. Практикуйтесь в безопасной среде перед применением на рабочем проекте.
Чек-лист «риски sdd в существующем проекте»: Самостоятельно созданный документ на основе раздела «Особые риски». Используйте перед каждой спецификацией фичи.
Zusammenfassung: Поддержка существующего проекта через SDD — это археология кода, а не его переписывание. Ключевые принципы: отделять факты от предположений и неизвестного; восстанавливать конституцию через структурированное интервью с AI-ассистентом; преобразовывать хаотичные TODO в фазированную дорожную карту; применять обычный цикл SDD для новых фич с уважением к существующим соглашениям; явно маркировать и откладывать архитектурные конфликты вместо «подчистки по пути». Главные риски — устаревшая документация, случайный код как правило, тесты, фиксирующие баги, и соблазн рефакторинга без спецификации. Противоядие — дисциплина разделения «наблюдаемого», «решённого» и «неизвестного» в каждом документе конституции. Освоив эту часть, вы сможете применять SDD к любому проекту, независимо от его возраста и состояния документации, превращая хаос в управляемую эволюцию.