Тема: Приложение A. Мосты к первому тому
Уровень сложности: Средний
Расчётное время изучения: 4-6 часов активного изучения + 2-3 часа практических упражнений
Предварительные требования: Прохождение основных частей первого тома (части 6, 7, 9, 10, 12, 13, 15, 16, 17, 20, 22)
Понимание структуры артефактов SDD: mission.md, tech-stack.md, roadmap.md, requirements.md, plan.md, validation.md
Базовое знакомство с проектом AgentClinic из первого тома
Понимание форматов EARS и Given/When/Then для спецификации требований
Знакомство с хуками Qwen Code (PreToolUse, PostToolUse)
Понимание концепции заменяемости агента и ссылок на ACP/AGENTS.md
Цели обучения: Успешно сопоставить все 12 production-сценариев второго тома с соответствующими учебными компонентами AgentClinic из первого тома
Провести миграцию артефактов между тремя диалектами SDD (авторский, Spec Kit, Kiro) без потери семантики
Сформировать минимальный маршрут прохождения второго тома, отличая обязательные артефакты от полного трека внедрения
Идентифицировать и объяснить, какие 8 тем первого тома являются критическими предпосылками для чтения второго тома
Применить доменную карту AgentClinic для интерпретации production-симптомов (node_not_ready, appointment_latency, high_memory_usage и др.) в контексте конкретных глав
Обзор: Приложение А служит архитектурным мостом между учебным первым томом и прикладным вторым томом курса по SDD (Specification-Driven Development). Оно систематизирует три критические связи: предпосылки из первого тома (без которых второй том нечитаем), соответствие диалектов SDD (авторский, GitHub Spec Kit, AWS Kiro), и доменную карту трансформации учебного проекта AgentClinic в production-сценарии. Приложение не содержит новой методологии — его цель — предотвратить когнитивную перегрузку читателя, явно показав, как каждый «production-термин» второго тома вырастает из уже знакомого учебного кода. Второй том строит 14 новых слоёв поверх базы первого тома: от спек-археологии и ярусных бюджетов до антипаттернов production SDD и итогового production-зачёта.
Ключевые концепции: Мост (bridge): Явная связь между артефактом/концепцией первого тома и её production-интерпретацией во втором томе. Мосты собраны в табличном виде для быстрого перекрёстного поиска при чтении любой главы второго тома.
Минимальный маршрут: Урезанный трек прохождения второго тома, где часть артефактов заполняется вручную, часть примеров запускается локально, а часть блоков относится только к полному треку внедрения. Описан в части 0 (part-00-production-lab.md).
Диалект sdd: Конкретная реализация методологии Specification-Driven Development с фиксированным набором артефактов и правил их именования. Авторский диалект учебника использует .md файлы; Spec Kit использует команды /speckit.*; Kiro использует собственную структуру артефактов.
Доменная карта agentclinic: Таблица соответствия между учебными сущностями первого тома (маршруты Hono, SQLite-миграции, формы обратной связи) и production-симптомами второго тома (node_not_ready, appointment_latency_spike, rate_limit_breach и др.).
Production-симптом: Наблюдаемый в production признак аномалии (например, high_memory_usage), который во втором томе анализируется через призму SDD-цикла: спецификация → план → валидация → эскалация/ремедиация.
Зачётный маршрут: Обязательный минимум для получения зачёта по прикладному тому. Для доменной карты AgentClinic зачётный кейс — high_memory_usage (пик чтений SQLite после деплоя); остальные симптомы используются для понимания локальных примеров.
Spec-археология: Процесс восстановления спецификации из следов унаследованной системы без исходной документации. Второй том развивает эту тему из части 13 первого тома.
Теневые спецификации: Неформальные эвристики и неявные требования, которые не зафиксированы в явных артефактах, но влияют на принятие решений. Второй том формализует их через процедуру отбора.
Ярусные бюджеты: Система распределения стоимости вызовов LLM-моделей по уровням (ярусам) сложности задач, предотвращающая бюджетный drain на простых операциях.
Anti-goodhart метрики: Парные сторожевые метрики, сконструированные так, чтобы оптимизация по одной метрике не приводила к деградации по другой (защита от эффекта Гудхарта).
Практические упражнения: Название: Упражнение 1: Диагностика пробелов в предпосылках
Проблема: Перед вами список из 8 тем первого тома. Для каждой темы определите: (а) какой артефакт SDD она порождает, (б) в какой главе второго тома этот артефакт используется, (в) что произойдёт при чтении главы без знания предпосылки. Темы: Структура mission.md/tech-stack.md/roadmap.md; Формат requirements.md/plan.md/validation.md; Факты допуска к слиянию и EARS; Перепланирование и обновление дорожной карты; Поддержка унаследованной кодовой базы; Заменяемость агента; Командное ревью и пакет доказательств; Хуки Qwen Code.
Решение: Шаг 1: Составьте таблицу 3×8. Шаг 2: Для 'Структура mission.md' — артефакты: конституция проекта; глава второго тома: часть 3 (Production-конституция); последствие пропуска: непонимание разделения неизменяемого и изменяемого слоёв. Шаг 3: Для 'Формат requirements.md/plan.md/validation.md' — артефакты: спецификация фичи; глава: часть 7 (Specification CI); последствие: невозможность настроить шлюз спецификации как обязательный gate. Шаг 4: Для 'Факты допуска и EARS' — артефакты: факты валидации; глава: часть 4 (LLM-дуэль); последствие: невозможность организовать состязательную валидацию между ролями. Шаг 5: Для 'Перепланирование' — артефакты: обновлённая roadmap; глава: часть 9 (Ярусные бюджеты); последствие: непонимание, как бюджетные ограничения влияют на перепланирование. Шаг 6: Для 'Spec-археология' — артефакты: восстановленная спецификация; глава: часть 1; последствие: невозможность применить техники восстановления из legacy. Шаг 7: Для 'Заменяемость агента' — артефакты: ACP/AGENTS.md; глава: часть 8 (Файловый арбитраж); последствие: непонимание, как мультиагентный трибунал сохраняет независимость ролей. Шаг 8: Для 'Командное ревью' — артефакты: пакет доказательств; глава: часть 13 (Практический зачёт); последствие: невозможность сформировать итоговый production-зачёт. Шаг 9: Для 'Хуки Qwen Code' — артефакты: PreToolUse/PostToolUse; глава: часть 11 (Production API); последствие: невозможность реализовать авто-ремедиацию через хуки.
Сложность: intermediate
Название: Упражнение 2: Трансляция между диалектами SDD
Проблема: Команда работает в GitHub Spec Kit. Переведите следующие артефакты авторского диалекта учебника в команды Spec Kit: requirements.md для фичи 'запись на приём', plan.md для итерации спринта, validation.md для проверки фичи. Затем выполните обратную трансляцию: /speckit.analyze → авторский диалект.
Решение: Шаг 1: requirements.md → /speckit.specify (создание спецификации требований). Шаг 2: plan.md → /speckit.plan + /speckit.tasks (план разбивается на структуру плана и конкретные задачи). Шаг 3: validation.md → /speckit.analyze + проверочные списки (валидация включает анализ и чек-листы приёмки). Шаг 4: Обратная трансляция: /speckit.analyze → validation.md (файл валидации, содержащий факты допуска, EARS-спецификации, Given/When/Then сценарии). Шаг 5: Проверьте сохранение семантики: в Spec Kit команды исполняются в чат-интерфейсе, в авторском диалекте — файлы версионируются в Git; оба подхода должны порождать идентичный набор проверяемых фактов.
Сложность: intermediate
Название: Упражнение 3: Интерпретация production-симптома через доменную карту
Проблема: В production-системе на основе AgentClinic зафиксирован симптом autoscale_200pct (резкий рост нагрузки на 200%). Используя доменную карту, определите: (а) какой учебный компонент первого тома лежит в основе этого симптома, (б) в какой фазе проекта (MVP) он возник, (в) какие главы второго тома применимы для анализа, (г) какие метрики и бюджеты задействованы.
Решение: Шаг 1: По таблице доменной карты autoscale_200pct соответствует 'MVP-фаза (часть 12)' первого тома. Шаг 2: MVP-фаза характеризовалась ручным деплоем и отсутствием автоматического масштабирования — резкий рост нагрузки был неожиданным. Шаг 3: Применимые главы второго тома: часть 9 (Ярусные бюджеты — распределение моделей по сложности задач при росте нагрузки), часть 10 (Anti-Goodhart метрики — предотвращение оптимизации autoscale в ущерб latency), часть 11 (Production API — интеграция с системами авто-масштабирования). Шаг 4: Метрики: appointment_latency (задержка ответа), high_memory_usage (потребление ресурсов при масштабировании). Шаг 5: Бюджеты: ярусный бюджет моделей (не исчерпать дорогие вызовы на рутинные проверки), cdn_error_budget_burn (не исчерпать бюджет ошибок CDN при резком росте трафика).
Сложность: intermediate
Название: Упражнение 4: Формирование минимального маршрута для конкретной главы
Проблема: Вы готовитесь к изучению части 5 второго тома (Мутационное тестирование спецификаций). На основе структуры минимального маршрута из части 0, определите: какие артефакты заполняются руками, какие примеры запускаются локально, какие блоки относятся только к полному треку внедрения.
Решение: Шаг 1: Определите предпосылки из Приложения А: часть 9 первого тома (факты допуска, EARS, Given/When/Then) — критически необходима, иначе мутации спецификаций нечем проверять. Шаг 2: Артефакты, заполняемые руками: requirements.md для фичи с EARS-форматом, набор мутантов (намеренно искажённых версий спецификации), оракул-список ожидаемых провалов. Шаг 3: Локально запускаемые примеры: скрипт мутации (внесение контролируемых дефектов в спецификацию), прогон валидатора против мутантов, анализ покрытия мутаций. Шаг 4: Блоки полного трека: интеграция с CI/CD для автоматического мутационного тестирования каждого PR, метрики mutation score в дашборде, связь с ярусными бюджетами (часть 9). Шаг 5: Проверка: если вы не проходили часть 9 первого тома — вернитесь к ней, иначе мутационное тестирование станет 'нагромождением терминов'.
Сложность: intermediate
Кейсы: Название: Кейс: Миграция команды из Spec Kit в авторский диалект при подготовке к production-зачёту
Сценарий: Команда из 4 разработчиков 18 месяцев работала с GitHub Spec Kit в чат-интерфейсе для спецификации внутренней системы записи к врачу. При переходе на курс SDD для подготовки к production-зачёту обнаружилось, что история спецификаций не версионируется, команды /speckit.* не порождают проверяемые артефакты для аудита, и невозможно сформировать пакет доказательств для командного ревью.
Задача: (1) Потеря семантики при трансляции: /speckit.plan содержит неявные допущения, которые в файловом plan.md должны быть явными. (2) Отсутствие фактов допуска к слиянию — в Spec Kit проверки выполнялись вручную без формализации EARS. (3) Команда не понимала, как заменяемость агента связана с ACP/AGENTS.md, поскольку в Spec Kit роль агента фиксировалась в контексте чата. (4) Необходимо было пройти зачётный маршрут с high_memory_usage как основным кейсом.
Решение: Шаг 1: Обратное проектирование (reverse engineering) всех /speckit.* команд в файловую структуру .md с сохранением временных меток. Шаг 2: Формализация неявных допущений через теневые спецификации (часть 6 второго тома) с последующим отбором в явные requirements.md. Шаг 3: Внедрение EARS и Given/When/Then для всех критических путей, прохождение части 9 первого тома в режиме ускоренного повторения. Шаг 4: Создание ACP/AGENTS.md с явным разделением ролей, настройка хуков Qwen Code для автоматической фиксации контекста. Шаг 5: Применение доменной карты: high_memory_usage интерпретирован как пик чтений SQLite после деплоя (часть 12 первого тома), что позволило сформулировать метрики и бюджеты для зачёта.
Результат: Через 3 недели команда сформировала полный пакет доказательств для части 13 (production-зачёт). Mutation score для спецификаций вырос с 0% до 73%. Ярусный бюджет позволил сократить расходы на LLM-вызовы на 34% при сохранении latency. Критический вывод: мосты между томами оказались не формальностью, а инструментом предотвращения когнитивного коллапса при переходе от чат-ориентированной спецификации к production-ready SDD.
Извлечённые уроки: Трансляция между диалектами SDD требует явной проверки семантической эквивалентности, а не только синтаксического соответствия имен файлов и команд
Теневые спецификации, накопленные в чат-формате, становятся критическим риском при масштабировании — их формализация должна предшествовать, а не следовать за production-внедрением
Зачётный маршрут (high_memory_usage) работает как якорь для всей команды: он конкретизирует абстрактные концепции второго тома через уже пройденный учебный код
Пропуск предпосылок (в данном случае — части 15 и 16 первого тома) увеличивает время миграции в 2-3 раза из-за необходимости возврата
Связанные концепции: Диалект SDD
Теневые спецификации
Доменная карта AgentClinic
Заменяемость агента
Зачётный маршрут
Пакет доказательств
Название: Кейс: Развёртывание Specification CI в унаследованном проекте AgentClinic без исходной спецификации
Сценарий: Учебный проект AgentClinic, развёрнутый студентом после прохождения первого тома, был доработан в течение 6 месяцев без ведения SDD-артефактов. При попытке применить часть 7 второго тома (Specification CI) как обязательный gate обнаружилось, что текущее состояние системы не покрыто спецификациями, и шлюз блокирует любое изменение.
Задача: (1) Spec-археология: необходимо было восстановить спецификацию из существующего кода и базы данных. (2) Контролируемые дефекты: часть 2 второго тома требует умение диагностировать 'отравленные' спецификации — но при отсутствии оригинала нечего диагностировать. (3) Production-конституция (часть 3): неизменяемые слои были нарушены ad-hoc изменениями. (4) Необходимо было определить, какие части первого тома критичны для восстановления, а какие можно опустить при ограниченном времени.
Решение: Шаг 1: Применение части 13 первого тома (Поддержка существующего проекта) для структурированного сбора следов системы: логи, миграции базы данных, коммит-история, API-эндпоинты. Шаг 2: Формирование временной 'теневой конституции' с явным разделением того, что уже неизменяемо (схема БД с данными), и что подлежит рефакторингу (бизнес-логика в хендлерах). Шаг 3: Использование EARS и Given/When/Then из части 9 для формализации наблюдаемого поведения системы как временной спецификации. Шаг 4: Постепенное внедрение Specification CI: сначала для новых фич, затем — ретроспективное покрытие критических путей. Шаг 5: Применение доменной карты: симптом node_not_ready использован как тестовый случай для проверки работоспособности восстановленной спецификации.
Результат: Через 4 недели Specification CI заработал для 60% критических путей. Оставшиеся 40% были явно помечены как 'legacy без спецификации' с планом постепенного покрытия. Восстановленная спецификация позволила обнаружить 3 скрытых бага, которые не проявлялись в тестовом окружении, но были критичны в production (связано с rate_limit_breach).
Извлечённые уроки: Spec-археология без знания части 13 первого тома превращается в хаотичный реверс-инжиниринг; структурированный подход экономит 40-50% времени
Временная 'теневая конституция' — допустимый артефакт на промежуточном этапе; главное — явное разделение неизменяемого и изменяемого
Доменная карта работает в обе стороны: не только 'учебный код → production-симптом', но и 'production-симптом → тестовый случай для валидации восстановленной спецификации'
Попытка внедрить Specification CI без прохождения частей 6-7 первого тома приводит к формализации неправильной структуры артефактов
Связанные концепции: Spec-археология
Production-конституция
Контролируемые дефекты
Specification CI
Доменная карта AgentClinic
Минимальный маршрут
Советы по изучению: Используйте таблицу 'Минимум, без которого второй том не читается' как чек-лист перед каждой главой: если предпосылка незнакома — немедленно вернитесь к соответствующей части первого тома, иначе последующее чтение станет пассивным просмотром 'нагромождения терминов'
Печатайте или держите в отдельном окне таблицу доменной карты AgentClinic при чтении любой главы второго тома — это снижает когнитивную нагрузку на 30-40% по сравнению с попыткой удержать все соответствия в памяти
Для аудиального восприятия: прочитайте вслух мостовые формулировки вида 'Маршрут GET / (Hello Hono) → node_not_ready: реплики не отвечают на health-check' — ритмическая структура 'учебное → production' помогает запоминанию
Для кинестетического восприятия: физически проставьте галочки в таблице предпосылок, вручную перепишите 3-4 ключевых моста в собственной формулировке, создайте физическую 'карту мостов' на листе A3
Для визуального восприятия: раскрасьте таблицу доменной карты цветами — зелёным зачётный маршрут (high_memory_usage), жёлтым локальные runnable-примеры, красным полный трек внедрения
Проводите 'трансляционные сессии': возьмите одну главу второго тома и явно проставьте, какие предпосылки из первого тома используются в каждом абзаце — это превращает пассивное чтение в активное конструирование связей
Если ваша команда работает в Spec Kit или Kiro — создайте собственную таблицу соответствия с авторским диалектом и повесьте её рядом с рабочим местом; переименование артефактов должно стать автоматическим навыком
Используйте хронологический подход: пройдите части первого тома в порядке их упоминания в Приложении А (6 → 7 → 9 → 10 → 12 → 13 → 15 → 16 → 17 → 20 → 22), а не в порядке номеров — это соответствует логике нарастания сложности во втором томе
Для глав 9-11 второго тома (бюджеты, метрики, Production API) обязательно вернитесь к частям 17 и 20 первого тома — хуки Qwen Code и антипаттерны SDD являются прямыми предпосылками для понимания ярусных бюджетов и авто-ремедиации
Формируйте 'личный словарь мостов': при обнаружении нового соответствия между томами фиксируйте его в едином документе — через 2-3 главы вы создадите индивидуальную версию Приложения А, адаптированную под ваш стиль мышления
Дополнительные ресурсы: Часть 0. лаборатория agentclinic-production (part-00-production-lab.md): Базовая рамка для перевода AgentClinic в учебную production-модель; содержит определение минимального маршрута
Приложение a первого тома (appendix-a-sdd-dialects.md): Детальное сравнение трёх диалектов SDD: таблица соответствия артефактов, рекомендации по переносу, ограничения каждого формата
Приложение b первого тома (appendix-b-agentclinic-domain.md): Полное описание сущностей домена AgentClinic: агенты-пациенты, недуги, терапии, записи на приём, отзывы, обратная связь
Readme прикладного тома (readme.md): Короткая карта чтения второго тома и ссылка на Приложение А
Часть 6 первого тома (part-06-constitution.md): Создание конституции: mission.md, tech-stack.md, roadmap.md
Часть 7 первого тома (part-07-feature-specification.md): Спецификация фичи: requirements.md, plan.md, validation.md
Часть 9 первого тома (part-09-feature-validation.md): Проверка фичи: факты допуска к слиянию, EARS, Given/When/Then
Часть 13 первого тома (part-13-legacy-support.md): Поддержка существующего проекта: spec-археология
Часть 15 первого тома (part-15-agent-replaceability.md): Заменяемость агента, ссылки на ACP/AGENTS.md
Часть 17 первого тома (part-17-qwen-code-hooks.md): Хуки Qwen Code: PreToolUse и PostToolUse
Резюме: Приложение А — это не вспомогательный материал, а критическая инфраструктурная компонента курса, обеспечивающая преемственность между учебным и прикладным томами. Три его функции: (1) диагностика готовности читателя через чек-лист из 8 обязательных предпосылок, (2) обеспечение мультидиалектности SDD через явные правила трансляции между авторским форматом, Spec Kit и Kiro, (3) конкретизация абстрактных production-сценариев через доменную карту AgentClinic. Ключевой принцип: каждый production-симптом второго тома (node_not_ready, appointment_latency, high_memory_usage, rate_limit_breach, autoscale_200pct, cdn_error_budget_burn) — это переименованный и усложнённый учебный компонент первого тома. Зачётный маршрут фиксирует high_memory_usage как якорной кейс; остальные симптомы служат для понимания локальных примеров. Без активного использования мостов второй том деградирует в пассивное накопление терминов; с мостами он становится осмысленным продолжением уже выстроенных компетенций.