主题: Приложение C. Чек-листы и шаблоны
难度等级: 中等
预计学习时间: 4-6 часов (теория 2 часа, практика 2-4 часа)
前置要求: Базовое понимание методологии SDD (Specification-Driven Development)
Опыт работы с системами контроля версий (Git)
Знакомство с форматом Markdown
Понимание структуры проектной документации (requirements.md, plan.md, validation.md)
Опыт взаимодействия с AI-агентами в разработке
学习目标: Самостоятельно применять все чек-листы приложения C на каждом этапе жизненного цикла фичи: от спецификации до запроса на слияние
Создавать полноценные запросы на слияние и ретроспективы по предоставленным шаблонам без пропуска обязательных секций
Формулировать минимальные запросы для ревью реализации и перепланирования, обеспечивающие эффективную работу AI-агента
Организовывать рабочую сессию с AI-агентом после команды /clear, следуя чек-листу новой сессии
Выявлять и предотвращать типичные ошибки: утечку секретов, несвязанные рефакторинги, изменения вне границ фичи
概述: Приложение C представляет собой операционный справочник для практического применения методологии SDD (Specification-Driven Development). В отличие от теоретических глав, этот материал создан для немедленного использования «в поле» — во время активной работы над проектом. Содержит шесть чек-листов, охватывающих полный цикл разработки фичи: от подготовки спецификации через реализацию до слияния и ретроспективы, а также четыре готовых шаблона для типовых операций с AI-агентом. Ключевая ценность — предотвращение типичных ошибок, которые дорого обходятся при работе с AI-агентами: потеря контекста, утечка секретов, размывание границ фичи, невалидные результаты. Материал рассчитан на промежуточный уровень: предполагается, что читатель уже знаком с базовой структурой SDD-документации и готов интегрировать чек-листы в ежедневную практику.
关键概念: Чек-лист перед созданием спецификации: Восемь обязательных условий, которые должны быть выполнены до начала написания спецификации. Проверяет ясность цели, аудиторию, границы работы, ограничения стека, проверяемые результаты, фазу дорожной карты и доступность необходимых ресурсов. Критически важен: попытка создать спецификацию без выполнения этих условий приводит к неполным или неконсистентным требованиям, которые AI-агент интерпретирует непредсказуемо.
Чек-лист перед реализацией: Семь пунктов контроля готовности к передаче задачи AI-агенту. Проверяет наличие и коммит трёх обязательных файлов (requirements.md, plan.md, validation.md), корректность передачи контекста (ссылки на файлы вместо длинной истории чата), чистоту ветки, соответствие границ фичи tech-stack.md и отсутствие «троянских» рефакторингов. Нарушение этого чек-листа — основная причина сбоев в работе агента.
Чек-лист перед запросом на слияние: Семь критериев качества для финальной проверки ветки. Включает верификацию обязательных фактов из validation.md, явное перечисление проваленных и отложенных фактов с обоснованием, ревью новых хуков и MCP-серверов, проверку на утечку секретов, обновление CHANGELOG.md и дорожной карты. Этот чек-лист — последний рубеж защиты от попадания некачественного кода в основную ветку.
Шаблон запроса на слияние: Стандартизированная структура MR/PR в формате Markdown. Содержит пять обязательных секций: спецификация (с папкой и фазой), перечень изменений, факты проверки с чекбоксами, непроверенные/отложенные факты, изменения вне границ фичи, и особые указания для ревьюера. Стандартизация обеспечивает предсказуемость ревью и снижает когнитивную нагрузку.
Шаблон ретроспективы sdd: Пять секций для систематического анализа завершённой фичи: что спецификация описала правильно, что агент вывел сам, что поймала проверка, какие факты были слабыми, что перенести в QWEN.md или specs/, что убрать из процесса. Ретроспектива замыкает цикл обучения и накапливает организационные знания.
Чек-лист для новой сессии после /clear: Шесть шагов восстановления контекста AI-агента после очистки истории чата. Проверяет прочтение базовых файлов (QWEN.md/AGENTS.md, mission.md, tech-stack.md), нужной папки фичи, знание запретных файлов, ожидаемых команд проверки и условий остановки для исследовательских задач. Без этого чек-листа агент работает «вслепую».
Минимальный запрос для ревью реализации: Стандартизированный промпт для верификации кода агентом. Структура: очистка, чтение контекста, сравнение с тремя эталонными документами, выдача четырёх категорий результатов (совпадения, расхождения, непроверенные факты, изменения вне границ), запрет на изменение файлов. Минимализм формулировки предотвращает «творческую» интерпретацию агентом.
Минимальный запрос для перепланирования: Стандартизированный промпт для подготовки следующей фазы дорожной карты. Структура: очистка, чтение mission.md, tech-stack.md, roadmap.md, недавних спецификаций и CHANGELOG.md, выдача списка необходимых обновлений, запрет на изменение файлов до одобрения. Обеспечивает консистентность эволюции проекта.
练习题: 名称: Аудит спецификации по чек-листу
问题: Вам передана незавершённая спецификация фичи «Экспорт отчётов в PDF». Проверьте её по чек-листу перед созданием спецификации. В материалах: описана цель («пользователи хотят сохранять отчёты»), указана аудитория («все пользователи»), границы работы не определены, ограничения стека не указаны, проверяемый результат один («файл скачивается»), фаза дорожной карты не указана, требуется интеграция с внешним API ключом которого нет в локальной среде. Составьте список блокирующих и неблокирующих проблем.
解决方案: 1. Блокирующие проблемы: отсутствие границ работы (непонятно, что входит в фичу, а что нет); отсутствие ограничений стека (агент может выбрать несовместимую технологию); фаза дорожной карты не указана (нарушает планирование); требуется внешний API с секретом, недоступным локально (блокирует разработку и тестирование). 2. Неблокирующие, но требующие улучшения: аудитория «все пользователи» слишком размыта — уточнить роли; проверяемый результат один — добавить проверки содержимого, формата, обработки ошибок. 3. Действия: либо получить доступ к API и инструкции по его использованию, либо исключить интеграцию из фичи, либо создать mock для локальной разработки.
难度: intermediate
名称: Формирование запроса на слияние по шаблону
问题: Завершена работа над фичей «Автодополнение адресов». Известно: папка спецификации specs/2024-03-15-address-autocomplete/, фаза дорожной карты «Улучшение UX форм», изменены файлы src/components/AddressInput.tsx, src/hooks/useAddressAPI.ts, tests/AddressInput.test.tsx. Проверены факты: npm run typecheck — пройден, npm test — 2 теста из 5 упали (известная проблема с rate limiting внешнего API). Новый MCP-сервер добавлен для геокодинга. CHANGELOG.md обновлён. Дорожная карта не обновлена, так как изменения минимальны. Составьте полный MR по шаблону.
解决方案: ## Спецификация - Папка: specs/2024-03-15-address-autocomplete/ - Фаза дорожной карты: Улучшение UX форм ## Что изменено - Реализован компонент AddressInput с автодополнением - Добавлен хук useAddressAPI для интеграции с геокодинг-сервисом - Написаны unit-тесты для компонента ## Факты проверки - [x] npm run typecheck - [ ] npm test (3/5 пройдено, 2 упали из-за rate limiting внешнего API) ## Непроверенные или отложенные факты - Интеграционные тесты с реальным API: отложены, требуется тестовый аккаунт без rate limiting - Нагрузочное тестирование: отложено до получения production-ключей ## Изменения вне границ фичи - Нет ## Что ревьюеру проверить особенно внимательно - Новый MCP-сервер геокодинга: проверить обработку ошибок и timeout - Корректность работы хука при быстром вводе (debounce)
难度: intermediate
名称: Диагностика сбоя после /clear
问题: Разработчик сообщает: после команды /clear AI-агент начал вносить изменения в файл .env, хотя этот файл явно запрещён к модификации. Агент также проигнорировал существующую архитектуру проекта и предложил альтернативный стек технологий. Проанализируйте ситуацию по чек-листу новой сессии и составьте корректную последовательность действий для восстановления работоспособности.
解决方案: 1. Диагностика: агент не прочитал QWEN.md/AGENTS.md (отсутствует знание запретных файлов); агент не прочитал tech-stack.md (не знает текущего стека); вероятно, агент не прочитал и папку фичи (работает без контекста). 2. Корректная последовательность: выполнить /clear; дать команду прочитать @QWEN.md; дать команду прочитать @mission.md; дать команду прочитать @tech-stack.md; дать команду прочитать нужную папку фичи; явно указать: файл .env нельзя изменять; явно указать: стек технологий фиксирован в tech-stack.md; указать ожидаемые команды проверки; для исследовательской задачи — указать условие остановки. 3. Профилактика: добавить в QWEN.md явное правило «НЕ изменять .env и файлы с секретами» с примером.
难度: intermediate
名称: Выявление скрытого рефакторинга
问题: В плане реализации фичи «Уведомления по email» агент включил пункт «Рефакторинг модуля аутентификации для использования нового хранилища сессий». В tech-stack.md указано текущее хранилище сессий, и оно не конфликтует с фичей уведомлений. Проанализируйте ситуацию по чек-листу перед реализацией и определите корректное действие.
解决方案: 1. Анализ по чек-листу: пункт «в плане нет несвязанных рефакторингов» — НЕ выполнен. 2. Обоснование: рефакторинг модуля аутентификации не имеет причинной связи с отправкой уведомлений по email; изменение хранилища сессий — это отдельная фича с собственными рисками и требованиями к валидации; смешивание в одной ветке нарушает принцип атомарности изменений. 3. Корректное действие: удалить рефакторинг из plan.md данной фичи; если рефакторинг действительно нужен — создать отдельную спецификацию с собственными requirements.md, plan.md, validation.md; если рефакторинг блокирует фичу — явно документировать эту зависимость и получить одобрение на расширение границ. 4. Риски игнорирования: увеличение объёма ревью, влияние на несвязанные функции, затруднение отката при проблемах.
难度: intermediate
案例研究: 名称: Утечка API-ключа в спецификацию: инцидент в команде финтех-стартапа
场景: Команда из 4 разработчиков использует SDD для разработки микросервиса платёжной обработки. Старший разработчик создаёт спецификацию интеграции с процессингом, включая примеры запросов с реальным тестовым API-ключом для наглядности. Спецификация коммитится в репозиторий specs/. AI-агент при реализации использует этот ключ в коде и логах. Код проходит ревью и попадает в staging.
挑战: Тестовый ключ оказался в трёх местах: specs/ (спецификация), src/config/payment.ts (код), logs/debug-2024-01-15.log (логи). Ключ имел доступ к тестовому окружению процессинга с реальными (хотя и тестовыми) картами. Утечка обнаружена только при аудите безопасности через 3 недели. Потенциальный ущерб: компрометация тестовых данных клиентов, блокировка аккаунта в процессинге, репутационные риски.
解决方案: Применён чек-лист перед запросом на слияние, который ранее игнорировался из-за спешки. Внедрены: автоматическая проверка секретов через git-secrets в pre-commit hook; обязательный пункт чек-листа «секреты не попали в спецификации, логи и память» с ручной верификацией; шаблон спецификации с плейсхолдерами вместо реальных ключей (API_KEY_PLACEHOLDER); отдельный файл secrets.template.md в .gitignore для локальных настроек; ретроспектива с обновлением QWEN.md правилом «НИКОГДА не включать реальные секреты в примеры».
结果: Нулевой инцидент за 8 месяцев после внедрения. Время на проверку MR увеличилось на 2 минуты, но сократилось время ревью на 15% за счёт стандартизации. Команда обнаружила ещё 2 исторические утечки при ретроспективном аудите. Процессинг выделил отдельный sandbox без реальных данных.
经验教训: Чек-лист без принудительного механизма выполнения бесполезен — нужны автоматические проверки или блокирующий code review
Примеры в спецификациях должны использовать явные плейсхолдеры, даже если это снижает «наглядность»
Ретроспектива должна фиксировать не только успехи, но и «слабые факты» — они указывают на системные пробелы
Правила из инцидентов должны мигрировать в QWEN.md немедленно, а не «когда-нибудь»
相关概念: Чек-лист перед запросом на слияние
Шаблон ретроспективы SDD
Чек-лист для новой сессии после /clear
名称: Восстановление контекста после сбоя: миграция легаси-системы
场景: Консалтинговая компания мигрирует монолит на микросервисы с помощью AI-агента. Проект длится 6 месяцев, 47 спецификаций. В критический момент разработчика заменяет новый сотрудник, который не знает истории проекта. При первой сессии с агентом после /clear тот предлагает использовать ORM, отличный от зафиксированного в tech-stack.md, и начинает переписывать существующие миграции.
挑战: Новый разработчик передал агенту «краткое описание» проекта вместо ссылок на файлы. Агент не прочитал tech-stack.md, не узнал о запрете на изменение существующих миграций, не понял архитектурных решений предыдущих фаз. Результат: 3 часа работы агента пошли в мусор, существующие тесты сломались, база данных в локальной среде оказалась в неконсистентном состоянии.
解决方案: Строгое следование чек-листу новой сессии после /clear: последовательное чтение QWEN.md (с обновлёнными правилами проекта), mission.md, tech-stack.md, актуальной папки фичи. Явное указание запретных файлов: «migrations/2024-* нельзя изменять — они применены в production». Использование минимального запроса для перепланирования для понимания текущего состояния дорожной карты. Внедрение practice: каждый новый участник проходит «пробную сессию» с наблюдением ментора.
结果: Время входа нового разработчика в проект сократилось с 5 дней до 1.5 дней. Создан onboarding-шаблон в QWEN.md с перечнем «вещей, которые каждый новый участник должен знать». Потерянная работа агента стала учебным кейсом для команды. Установлено правило: первый запрос любой новой сессии — всегда чтение базовых файлов, никаких исключений.
经验教训: «Краткое описание» не заменяет структурированные файлы — агент теряет детали и галлюцинирует
Чек-лист новой сессии — это не формальность, а критически важный механизм восстановления контекста
Запретные файлы должны быть перечислены явно и конкретно, а не в общих формулировках
Onboarding новых участников должен включать практику работы с AI-агентом под наблюдением
相关概念: Чек-лист для новой сессии после /clear
Минимальный запрос для перепланирования
Минимальный запрос для ревью реализации
学习建议: Создайте физическую или цифровую «карту памяти»: распечатайте все чек-листы на одном листе A4 и держите перед глазами во время работы — тактильное присутствие снижает вероятность пропуска пунктов
Практикуйте «обратный чек-лист»: берите завершённые MR из своей практики и проверяйте, что они соответствуют шаблону — это выявляет привычные пропуски
Записывайте типичные ошибки в личный «дополнительный QWEN.md» — со временем у вас накопится список специфичных для вашего проекта дополнений к стандартным чек-листам
Используйте технику «первый запрос — всегда шаблон»: даже если кажется, что ситуация уникальна, начинайте с минимального запроса и модифицируйте его — это предотвращает «творческое» поведение агента
Проводите микроретроспективы: 5 минут после каждой фичи, не дожидаясь формальной ретроспективы — фиксируйте одну вещь, которую агент вывел сам, и одну, которую спецификация описала неточно
Парное обучение: найдите коллегу и поочерёдно выполняйте роли «разработчика» и «ревьюера чек-листов» — внешний взгляд ловит пропуски, которые вы сами не замечаете
Адаптируйте шаблоны под свой проект: скопируйте шаблон MR в свой репозиторий как .github/pull_request_template.md или аналог — автоматическое появление шаблона устраняет лень заполнять
附加资源: Оригинальное приложение c курса sdd: Исходный материал, на основе которого построен данный гайд — используйте как быстрый справочник в полевых условиях
Шаблоны для копирования: Создайте в своём проекте файлы: TEMPLATES/merge-request.md, TEMPLATES/retrospective.md, TEMPLATES/minimal-prompts.md с содержимым из приложения C
Инструменты проверки секретов: git-secrets (AWS Labs), truffleHog, GitGuardian — для автоматизации пункта «секреты не попали в спецификации»
Расширения для работы с чек-листами: Markdown Checkbox в VS Code, GitHub Task Lists, Obsidian Tasks — для отслеживания выполнения пунктов
Примеры qwen.md от сообщества: Поиск по репозиториям с тегом qwen-md или sdd-methodology для вдохновения по структуре контекстных файлов
Документация по mcp-серверам: Ресурсы по Model Context Protocol для понимания пункта «новые MCP-серверы ревьюились» в чек-листе перед MR
摘要: Приложение C — это операционный мозг методологии SDD, превращающий теоретические принципы в конкретные действия. Шесть чек-листов покрывают полный жизненный цикл фичи и защищают от типичных ошибок: неполной спецификации, потери контекста агентом, утечки секретов, размывания границ, неконсистентного кода. Четыре шаблона стандартизируют коммуникацию и снижают когнитивную нагрузку. Ключевой принцип: чек-лист выполняется полностью или не выполняется вообще — частичное применение хуже отсутствия, так как создаёт ложное чувство безопасности. Успешное освоение материала измеряется не знанием пунктов, а автоматичностью их применения: чек-листы должны стать мышечной памятью, а шаблоны — умолчательным способом работы. Регулярные ретроспективы замыкают цикл обучения, превращая индивидуальный опыт в организационные знания.