主题: Часть 16. Командная работа и ревью кода
难度等级: 中等
预计学习时间: 4-6 часов (теория: 2 часа, практика: 2-4 часа)
前置要求: Части 1-15 курса SDD (понимание спецификации: requirements.md, plan.md, validation.md)
Базовые знания Git и работы с ветками
Опыт работы с pull request в GitHub/GitLab
Понимание роли Qwen Code как агента разработки
学习目标: Составлять и использовать четырёхслойное ревью (требования → план → факты → код) для проверки запросов на слияние в SDD-проекте
Применять шаблон запроса на слияние для демонстрации связи между спецификацией и изменениями кода
Определять, когда править спецификацию в ветке фичи, а когда требуется отдельная ветка перепланирования
Использовать Qwen Code как второго читателя при ревью, не допуская автоматической правки кода агентом
Выявлять изменения, которые нельзя отдавать агенту на автопилоте, и обеспечивать человеческий контроль над критическими решениями
概述: Эта часть курса переходит от индивидуальной разработки к командной работе в рамках Specification-Driven Development (SDD). Ключевой инсайт: в команде спецификация становится не просто подсказкой для агента, а договором между людьми. Если этот договор не ревьюить, агент может реализовать аккуратный код по слабому или неполному описанию — и это будет выглядеть как успех, пока не обнаружатся скрытые проблемы. Главное правило: в запросе на слияние ревьюят не только код, а связку «требования → план → факты проверки → изменения». Раздел охватывает полный поток работы от ветки фичи до слияния, роли автора и ревьюера, шаблоны PR, управление конфликтами в roadmap.md и границы автоматизации с Qwen Code.
关键概念: Главное правило командного sdd: В запросе на слияние ревьюят не только код. Ревьюят связку: требования → план → факты проверки → изменения. Это предотвращает ситуацию, когда аккуратный код реализует неверную спецификацию.
Поток работы (workflow): Ветка фичи → спецификация (requirements.md, plan.md, validation.md) → первое ревью границ и фактов → решение «можно реализовывать?» → реализация → проверка по validation.md → pull request → ревью кода и спецификации → слияние и перепланирование. Первое ревью в маленькой команде может быть устным, в большой — коротким комментарием в PR.
Четыре вопроса автора перед открытием pr: 1) Есть ли у фичи отдельная папка в specs/? 2) Не изменял ли агент файлы вне границ фичи? 3) Все обязательные факты из validation.md проверены? 4) Если факты изменились по ходу работы, видно ли, почему они изменились? Последний вопрос критичен: плохой признак — агент меняет validation.md после провала тестов, чтобы проверка стала проще; хороший — автор явно объясняет причину изменения фактов.
Четыре слоя ревьюера: Требования (понятны ли границы, для кого фича, что не входит), План (соответствуют ли группы задач требованиям, нет ли скрытого рефакторинга), Факты (проверяют ли реальное поведение, а не намерение; есть ли машинно проверяемые факты), Код (соответствует ли реализация плану и фактам, нет ли изменений «заодно»). Если ревьюер смотрит только код, SDD деградирует до обычного ревью с лишними Markdown-файлами.
Шаблон запроса на слияние: Минимальный шаблон вынесен в appendix-c-checklists.md и копируется в .github/pull_request_template.md. Смысл — заставить автора показать связь спецификации и изменений: папка спецификации, пройденные факты, отложенные факты с причинами, файлы вне ожидаемой области, особо внимательные проверки для ревьюера. Для большинства фич достаточно 6–8 пунктов.
Правка спецификации в ветке фичи: Допустимо при уточнениях, связанных с текущей фичей и не меняющих стратегию проекта: уточнить HTTP-статус, добавить ручной факт проверки интерфейса, исправить название маршрута, отметить факт отложенным, добавить решение, принятое при реализации. Плохая правка: переписать границы фичи, чтобы совпали с уже случайно написанным кодом.
Ветка перепланирования: Нужна при изменениях, затрагивающих конституцию проекта: смена стека, порядка фаз, новая архитектурная граница, изменение MVP, правило для нескольких будущих фич, перепись QWEN.md или командного навыка. Разделяет реализацию фичи и изменение процесса/дорожной карты.
Конфликты в roadmap.md: Узкое место: два человека могут одновременно менять статусы разных фаз. Правило: в ветке фичи можно читать и ссылаться, менять статусы лучше перед слиянием или в короткой ветке перепланирования. В большой команде — правило владельца дорожной карты.
Qwen code в ревью: Полезен как второй читатель, не как замена ревьюеру. Хороший запрос: прочитать QWEN.md, спецификацию ветки, git diff; сравнить реализацию с тремя файлами спецификации; составить список расхождений; файлы не изменять. Плохой запрос: «проверь PR и исправь всё» — агент смешивает ревью, исправление и принятие решений, что опасно в командной работе.
Запреты для автопилота агента: Без человеческого решения нельзя отдавать: расширение границ фичи, смена стека, удаление фактов из validation.md, изменение политики безопасности, обновление roadmap.md нескольких фаз, слияние PR, правку истории Git, необратимые миграции/удаление данных. Агент может предложить, человек решает.
练习题: 名称: Упражнение 1: Аудит готовности к PR по четырём вопросам
问题: Вам дана ветка фичи «добавление фильтрации пациентов по диагнозу» в проекте AgentClinic. Автор открыл PR. При проверке вы обнаружили: папка specs/patient-filter/ существует; в git diff видны изменения в specs/patient-filter/requirements.md, specs/patient-filter/plan.md, specs/patient-filter/validation.md, src/services/patient_service.py, tests/test_patient_filter.py; но также изменён файл src/models/base_model.py (добавлено поле is_archived). В validation.md последний факт изменён с «Фильтр возвращает только активных пациентов» на «Фильтр возвращает пациентов, у которых is_archived = false», при этом в истории коммитов видно, что это изменение сделано после провала теста test_active_patients_only. Напишите, какие из четырёх вопросов автору не удалось ответить удовлетворительно, и сформулируйте комментарий ревьюера.
解决方案: Шаг 1: Проверяем вопрос 1 — папка specs/patient-filter/ есть, ответ «да». Шаг 2: Проверяем вопрос 2 — изменён src/models/base_model.py вне границ фичи, ответ «нет, изменял». Шаг 3: Проверяем вопрос 3 — невозможно проверить однозначно, но предположим факты проверены. Шаг 4: Проверяем вопрос 4 — факт изменён после провала теста, причина не объяснена явно, похоже на ослабление проверки. Комментарий ревьюера: «Вопрос 2: изменение base_model.py выходит за границы фичи. Требуется либо вынести в отдельную фичу, либо обосновать в PR, почему это необходимо для фильтрации. Вопрос 4: факт про активных пациентов изменён после провала теста без объяснения причины. Это похоже на адаптацию спецификации под код, а не на уточнение требования. Прошу восстановить исходный факт или явно объяснить бизнес-причину изменения и добавить новый факт, подтверждающий корректность нового поведения.»
难度: intermediate
名称: Упражнение 2: Разделение правок на ветку фичи и ветку перепланирования
问题: В проекте AgentClinic в ветке фичи «экспорт отчётов в PDF» разработчик хочет внести следующие изменения. Определите, какие можно делать в ветке фичи, а какие требуют отдельной ветки перепланирования: (А) добавить в validation.md ручной факт «PDF открывается в Acrobat Reader без ошибок валидации»; (Б) заменить библиотеку генерации PDF с WeasyPrint на Playwright + Chromium; (В) добавить в requirements.md уточнение, что экспорт поддерживает только латиницу и кириллицу; (Г) перенести генерацию отчётов из модуля services/ в новый модуль reporting/; (Д) обновить roadmap.md, отметив фазу «Отчёты» как завершённую и добавив фазу «Аналитика отчётов»; (Е) изменить QWEN.md, добавив правило «все новые модули создаются с префиксом agentclinic_».
解决方案: Шаг 1: Анализируем каждое изменение по критерию — затрагивает ли конституцию проекта или касается только текущей фичи. (А) Ручной факт в validation.md — уточнение текущей фичи, ветка фичи. (Б) Смена стека библиотек — меняет технологический выбор, влияет на другие фичи и будущее проекта, отдельная ветка перепланирования. (В) Уточнение поддерживаемых символов — граница текущей фичи, ветка фичи. (Г) Новая архитектурная граница модуль reporting/ — затрагивает структуру проекта и будущие фичи, отдельная ветка перепланирования. (Д) Обновление roadmap.md с новой фазой — меняет дорожную карту нескольких фаз, отдельная ветка перепланирования (или короткая ветка перепланирования). (Е) Изменение QWEN.md — меняет командный навык, отдельная ветка перепланирования. Итог: ветка фичи — А, В; отдельная ветка перепланирования — Б, Г, Д, Е.
难度: intermediate
名称: Упражнение 3: Составление шаблона PR для конкретной фичи
问题: Разработчик завершил фичу «уведомления врача при критическом изменении показателей пациента» в AgentClinic. Спецификация находится в specs/critical-alerts/. Из validation.md проверены 4 из 5 фактов: факт «Уведомление доставлено за < 30 секунд» отложён, так как требует нагрузочного тестирования, которое запланировано на следующую итерацию. В git diff изменены: specs/critical-alerts/validation.md (отметка об отложенном факте), src/services/alert_service.py, src/notifications/push_sender.py, tests/test_critical_alerts.py. Неожиданно: также изменён src/config/settings.py — добавлена переменная окружения ALERT_TIMEOUT_MS. Составьте описание PR по шаблону из приложения C, 6–8 пунктов.
解决方案: Шаг 1: Указываем папку спецификации. Шаг 2: Перечисляем проверенные факты. Шаг 3: Отмечаем отложенный факт с причиной. Шаг 4: Объясняем изменение вне ожидаемой области. Шаг 5: Указываем, что ревьюер должен проверить особенно внимательно. Шаг 6: Даём общую оценку готовности. Пример результата: 1. Спецификация: specs/critical-alerts/ (requirements.md, plan.md, validation.md). 2. Проверены факты: уведомление создаётся при критическом изменении; содержит ID пациента и показатель; направляется назначенному врачу; логируется в audit trail. 3. Отложен: факт «доставка < 30 сек» — требует нагрузочного тестирования, запланировано на спринт 14. 4. Изменение вне границ: src/config/settings.py — добавлена ALERT_TIMEOUT_MS для единого управления таймаутом уведомлений. Обоснование: избежать хардкода в alert_service.py. 5. Проверить внимательно: корректность связи alert_service.py и push_sender.py; не создаёт ли ALERT_TIMEOUT_MS конфликтов с другими таймаутами в settings.py. 6. Готовность: фича функциональна, отложенный факт не блокирует MVP.
难度: intermediate
名称: Упражнение 4: Формулировка запроса к Qwen Code для ревью
问题: Вы — ревьюер в SDD-проекте. Автор PR просит «пусть Qwen проверит и поправит код, а потом вы посмотрите». Объясните, почему это плохая практика, и составьте корректный запрос к Qwen Code, который вы как ревьюер дадите агенту для помощи в ревью, не допуская автоматической правки.
解决方案: Шаг 1: Объясняем проблему: запрос «проверь и поправь» смешивает три роли — ревью (выявление расхождений), исправление (изменение кода) и принятие решений (что править, а что нет). В командной работе это опасно: агент может принять решения, которые должен принимать человек (например, ослабить факт или расширить границы). Ревью должно сначала создать ясный список расхождений, а автор решает, что править. Шаг 2: Составляем корректный запрос. Результат: «/clear. Прочитай @QWEN.md, спецификацию ветки specs/critical-alerts/ (requirements.md, plan.md, validation.md) и git diff этой ветки относительно main. Сравни реализацию с каждым из трёх файлов спецификации. Составь список расхождений: где код не соответствует требованиям, где реализация отличается от плана, где факты validation.md не проверяются или проверяются некорректно. Файлы не изменяй. Результат оформи как нумерованный список с указанием файла и строки.»
难度: intermediate
案例研究: 名称: Кейс: Деградация SDD до «Markdown-ревью» в стартапе MedFlow
场景: MedFlow — стартап из 4 разработчиков, внедривший SDD после курса. Первые два месяца работали по правилу «ревьюим связку требования-план-факты-код». С ростом нагрузки старший разработчик предложил «ускориться»: ревьюер стал смотреть только git diff и validation.md, пропуская requirements.md и plan.md. Авторы PR начали минимизировать спецификацию, а Qwen Code использовали для автозаполнения шаблонов PR.
挑战: Через 6 недель команда обнаружила, что реализована фича «интеграция с лабораторией», которая на самом деле делает не то, что требовал бизнес: код аккуратно передаёт данные в API лаборатории, но в requirements.md границы были расплывчаты («интеграция» без уточнения направления). План предполагал двусторонний обмен, а реализация сделала только отправку заказов без получения результатов. validation.md проверял корректность HTTP-статусов, но не проверял наличие endpoint'а для callback'ов. Фича прошла ревью, так как код соответствовал слабой спецификации. Бизнес потерял 3 недели на переделку.
解决方案: Команда ввела жёсткое правило: PR без явной ссылки на requirements.md и plan.md автоматически возвращается. Ревьюер обязан задавать хотя бы один вопрос по каждому из четырёх слоёв. Qwen Code перевели в режим «только список расхождений» с запретом на автоправку. Владельцем roadmap.md назначили ротацию по неделям. Шаблон PR сократили до 6 обязательных пунктов, но сделали их строгими.
结果: Среднее время ревью выросло с 15 до 40 минут, но количество переделок снизилось на 70%. Следующая фича интеграции (с платёжным шлюзом) прошла с одной итерацией ревью вместо прежних четырёх. CTO отметил, что «замедление» на ревью окупилось ускорением на этапе приёмки бизнесом.
经验教训: Пропуск слоёв ревью (особенно requirements и plan) делает SDD формальностью и не защищает от реализации неверной спецификации
Автозаполнение шаблонов агентом уничтожает их смысл — шаблон должен заставлять автора думать, а не экономить время на копировании
Краткость шаблона важнее полноты: 6 строгих пунктов работают лучше 15 опциональных
相关概念: Главное правило командного SDD
Четыре слоя ревьюера
Шаблон запроса на слияние
Qwen Code в ревью
名称: Кейс: Конфликт в roadmap.md и введение владельца дорожной карты
场景: AgentClinic — проект из 8 разработчиков, работающих по SDD. Дорожная карта в roadmap.md содержала 5 фаз. Два разработчика, Алексей и Мария, параллельно работали над фазами 3 («Интеграция датчиков») и 4 («Аналитика показателей»). Оба изменили статус своих фаз в roadmap.md в своих ветках фич.
挑战: При слиянии первого PR статус фазы 3 изменился на «завершено», а фазы 4 — на «в разработке». При слиянии второго PR произошёл конфликт: Мария изменила статус фазы 4 на «в разработке» в своей ветке, но к тому моменту Алексей уже добавил фазу 5 «Предиктивная аналитика» в main. Git не смог автоматически слить изменения roadmap.md. Разрешение конфликта заняло 2 часа, при этом ошибочно был потерян статус фазы 2 («Регистрация пациентов»), который кто-то исправил ранее.
解决方案: Команда ввела правило: в ветке фичи можно читать roadmap.md и ссылаться на фазу, но менять статусы только в короткой ветке перепланирования или непосредственно перед слиянием с явным согласованием. Назначили владельца дорожной карты — роль ротируется еженедельно, ответственность: проверять, что статусы фаз соответствуют реальности, и быть единственным, кто коммитит изменения roadmap.md в main.
结果: Конфликты в roadmap.md исчезли. Время на планирование спринта сократилось с 4 часов до 45 минут. Владелец дорожной карты стал естественной точкой синхронизации между разработчиками, что неожиданно улучшило коммуникацию в команде.
经验教训: roadmap.md — узкое место в параллельной работе, требующее явного правила владения
Ротация роли владельца дорожной карты предотвращает bus factor и вовлекает всех в понимание стратегии
Отделение изменения статусов от веток фич уменьшает конфликты и делает историю понятной
相关概念: Конфликты в roadmap.md
Ветка перепланирования
Поток работы (workflow)
学习建议: Проходите материал параллельно с реальным или учебным проектом: попробуйте открыть любой завершённый PR как «ментальный ревью» по четырём слоям — это превращает абстрактные правила в навык
Печатайте или держите под рукой чек-лист четырёх вопросов автора и четырёх слоёв ревьюера — используйте их буквально для первых 5 PR, пока не станет автоматически
Практикуйтесь в формулировке «хороших» и «плохих» запросов к Qwen Code: напишите 3 хороших и 3 плохих, объясните разницу коллеге или в учебном чате — обучение через обучение других укрепляет понимание
Создайте учебный репозиторий с несколькими ветками фич и намеренно внесите в одну из них типичные ошибки (изменение вне границ, ослабление факта после провала теста, отсутствие папки specs) — попрактикуйтесь в выявлении их по чек-листу
Изучайте связанные части 17, 18, 20 не последовательно, а параллельно: автоматизация проверок (17), безопасность ревью (18) и антипаттерны (20) — это три грани одного процесса, и понимание их взаимосвязи глубже, чем изолированное изучение
Ведите «дневник ревьюера»: фиксируйте, какие вопросы вы задаёте на реальных PR, какие находят проблемы, какие оказываются ложными тревогами — через месяц у вас будет персонализированный чек-лист
Для визуального стиля обучения: нарисуйте на бумаге поток работы от ветки фичи до слияния, отметьте, где именно происходит каждая проверка и кто за неё отвечает
附加资源: Appendix-c-checklists.md: Оригинальный шаблон запроса на слияние из курса — основа для .github/pull_request_template.md
Часть 17. автоматизация проверок ревью: Какие хуки помогают сделать часть проверок ревью автоматическими — продолжение темы командной работы
Часть 18. безопасность при ревью: Что искать в diff: утечка секретов, новые MCP-серверы, изменения хуков — критично для реальных проектов
Часть 20. антипаттерны: Ситуации для немедленного отклонения PR: спецификация без фактов, факты ослабленные по ходу работы, реализация будущей фазы
Github docs: about pull request templates: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository — техническая инструкция по внедрению шаблона
«code review best practices» by palantir: https://blog.palantir.com/code-review-best-practices-19e02770015f — классическая статья, дополняющая SDD-специфичный подход общими принципами ревью
Книга «working effectively with legacy code» майкла физерса: Глава про «прищепки» (seams) и границы изменений — полезна для понимания, почему важно не выходить за границы фичи
摘要: Командная работа в SDD требует переосмысления роли спецификации: она становится договором между людьми, а не только подсказкой для агента. Главное правило — ревьюить связку «требования → план → факты → код», а не изолированно код. Успешное применение требует дисциплины автора (четыре вопроса перед PR), системности ревьюера (четыре слоя проверки), чёткости в границах изменений (ветка фичи vs ветка перепланирования), управления узкими местами (владелец roadmap.md) и осознанного использования автоматизации (Qwen Code как второй читатель, не замена ревьюеру). Шаблон PR — инструмент связи, а не бюрократия. Запреты для автопилота агента защищают критические решения от необдуманной автоматизации. Соблюдение этих принципов предотвращает деградацию SDD до формального ревью с лишними Markdown-файлами и обеспечивает предсказуемость командной разработки.