Тема: Приложение B. Доменная карта AgentClinic
Уровень сложности: Средний
Расчётное время изучения: 6-8 часов (теория + практика)
Предварительные требования: Базовое понимание веб-разработки (HTTP, маршруты, запросы)
Знакомство с реляционными базами данных (SQL, таблицы, связи)
Понимание концепции MVP (Minimum Viable Product)
Базовые знания TypeScript/JavaScript
Понимание принципов тестирования (факты проверки, assertions)
Цели обучения: Самостоятельно спроектировать доменную модель учебного проекта, определяя сущности, их атрибуты и связи, аналогичные AgentClinic
Разбить полный функционал проекта на фазы SDD-цикла, объяснив порядок добавления маршрутов и обосновав приоритетность каждой фазы
Сформулировать минимальные проверяемые факты для каждой фазы, создав чек-лист валидации, который можно автоматизировать
Применять доменный словарь последовательно во всех спецификациях, выявляя и исправляя несоответствия терминологии
Отличать элементы, входящие в учебный домен, от тех, что требуют отдельной спецификации, и обосновывать это решение
Обзор: AgentClinic — это учебный проект-сатира, демонстрирующий SDD-цикл (Specification-Driven Development) на примере «клиники для программных агентов». Доменная карта описывает структуру этого проекта: какие сущности существуют (агенты, недуги, терапии, записи на приём, отзывы), как они связаны между собой, какие маршруты обслуживают пользовательские сценарии, и как вся функциональность раскладывается по фазам разработки. Ключевая идея — домен специально остаётся простым, но достаточно насыщенным, чтобы продемонстрировать все аспекты SDD: от первого «Hello Hono» до панели администратора с проверкой счётчиков. При этом проект намеренно исключает сложные реальные сценарии (платежи, авторизация, внешние интеграции), чтобы фокус оставался на самом процессе разработки через спецификации.
Ключевые концепции: Доменная карта: Визуальное и текстовое описание предметной области проекта, включающее сущности, их атрибуты, связи и границы. В AgentClinic доменная карта служит общим языком между разработчиками, тестировщиками и спецификациями. Она не диктует конкретную реализацию, но задаёт рамки, в которых движется проект.
Сущность: Ключевой объект предметной области с чёткой семантикой. В AgentClinic пять основных сущностей: Агент (программный помощник), Недуг (повторяющаяся проблема агента), Терапия (способ помощи агенту), Запись на приём (заявка пользователя), Отзыв (обратная связь). Каждая сущность имеет набор атрибутов и правила использования в спецификациях.
Sdd-цикл (specification-driven development): Процесс разработки, в котором спецификации (requirements.md, plan.md, validation.md) ведут реализацию. Вместо того чтобы строить всё сразу, проект развивается фазами, каждая из которых начинается с чётких проверяемых фактов и заканчивается их подтверждением.
Проверяемые факты: Конкретные, объективно измеримые утверждения о поведении системы, которые можно автоматизировать. Например: «GET / возвращает 200» или «невалидная форма отклоняется». Факты заменяют расплывчатые требования вроде «приложение должно работать быстро».
Фаза разработки: Ограниченный по времени и объёму этап, дающий конкретный поставляемый результат. В AgentClinic шесть фаз: Hello Hono → Агенты и недуги → Терапии → Запись на приём → Обратная связь → Панель администратора. Каждая фаза добавляет новые маршруты и факты проверки, но не ломает предыдущие.
Минимальные маршруты: Набор URL-путей, достаточный для демонстрации домена. Не все маршруты нужны в первой фазе — это принцип итеративности SDD. Маршруты используют технические английские имена (/agents, /ailments), в то время как пользовательские сценарии описываются на русском с применением доменного словаря.
Доменный словарь: Соглашение о единой терминологии во всех спецификациях. Запрещает синонимы вроде «бот/ассистент/модель» для сущности «агент». Технические имена (маршруты, таблицы, файлы) остаются на английском, пользовательские сценарии — на русском с единообразными терминами.
Границы учебного домена: Явное перечисление того, что НЕ входит в проект без отдельной спецификации: настоящая медицинская терминология, реальные персональные данные, платёжные сценарии, авторизация с ролями, внешняя отправка писем, сложные графики, интеграции с реальными сервисами. Это ограничение сохраняет фокус на процессе SDD.
Практические упражнения: Название: Проектирование доменной модели для нового проекта
Проблема: Представьте, что вам нужно создать учебный проект «AgentLibrary» — библиотеку для программных агентов. Определите минимум 4 сущности, их атрибуты и примеры, аналогично таблице сущностей AgentClinic. Затем опишите, какие маршруты понадобятся и как они раскладываются по фазам SDD.
Решение: Шаг 1: Определите сущности. Например: Книга (название, автор, описание), Агент-читатель (имя, предпочтительные жанры), Отзыв (рейтинг, текст, дата), Полка (название, публичная/приватная). Шаг 2: Задайте атрибуты в формате таблицы с примерами. Шаг 3: Спроектируйте маршруты: /, /books, /books/:id, /agents, /reviews, /shelves. Шаг 4: Разбейте на фазы: (1) Hello Hono — GET / возвращает 200; (2) Книги — список и карточка; (3) Агенты и отзывы — связанные отзывы на книгу; (4) Полки — создание и управление коллекциями. Шаг 5: Для каждой фазы сформулируйте 2-3 проверяемых факта.
Сложность: intermediate
Название: Аудит терминологии в спецификациях
Проблема: Вам даны три фрагмента из разных файлов проекта AgentClinic: (1) requirements.md: «Бот должен отображать список своих проблем»; (2) plan.md: «Создать таблицу symptoms для хранения повторяющихся неполадок ассистента»; (3) validation.md: «GET /agents/:id возвращает связанный список ailments». Найдите все нарушения доменного словаря, объясните, почему они проблематичны, и перепишите фрагменты корректно.
Решение: Нарушения: «бот» вместо «агент», «проблемы» вместо «недуги», «symptoms» вместо «ailments», «ассистент» вместо «агент». Проблема: разные термины для одной сущности создают путаницу в команде, усложняют поиск по документам, приводят к несоответствию между кодом (таблица ailments) и спецификациями (symptoms). Корректный вариант: (1) «Агент должен отображать список своих недугов»; (2) «Создать таблицу ailments для хранения повторяющихся недугов агента»; (3) без изменений — уже корректно.
Сложность: intermediate
Название: Расширение домена: анализ границ
Проблема: Команда предлагает добавить в AgentClinic систему рейтинга клиник (аналог Google Reviews) с платной подпиской для приоритетной записи. Используя критерии из раздела «Что не входит в учебный домен», проанализируйте это предложение. Опишите, какие компоненты нарушают границы, и предложите альтернативу, сохраняющую образовательную ценность.
Решение: Нарушения границ: платная подписка — платёжные сценарии (явно запрещены); система рейтинга с агрегацией по регионам — сложные графики и потенциально реальные персональные данные; приоритетная запись — неявная авторизация с ролями (обычный vs премиум пользователь). Альтернатива: простая шкала удовлетворённости (1-5 звёзд) в существующей сущности «отзыв» без привязки к пользователю, без агрегации и без платежей. Добавить как отдельную фазу: «Расширенные отзывы» с фактами «отзыв содержит оценку 1-5», «средняя оценка видна на странице /feedback».
Сложность: advanced
Название: Проектирование схемы базы данных
Проблема: На основе описанных сущностей AgentClinic и минимальных маршрутов спроектируйте полную SQL-схему с учётом всех связей. Объясните, почему agent_ailments — связующая таблица, а не поле в agents. Опишите, как изменится схема, если добавить требование: «одна терапия лечит конкретный недуг конкретного агента».
Решение: Базовая схема: agents(id, name, description); ailments(id, title, description); therapies(id, title, description); agent_ailments(agent_id, ailment_id) — связь многие-ко-многим: один агент может иметь несколько недугов, один недуг может быть у нескольких агентов. Связующая таблица нужна, потому что массив в поле agents нарушает первую нормальную форму и усложняет запросы. appointments(id, name, message, ailment_id, created_at); feedback(id, name, message, created_at). При новом требовании добавляется agent_ailment_therapies(agent_ailment_id, therapy_id, effectiveness_rating), где agent_ailment_id — составной ключ или отдельный id таблицы agent_ailments. Это превращает связь в тройную: агент-недуг-терапия.
Сложность: intermediate
Название: Формулировка проверяемых фактов для фазы «Запись на приём»
Проблема: Для фазы «Запись на приём» в AgentClinic сформулируйте минимум 5 проверяемых фактов, которые покрывают: успешное создание, валидацию обязательных полей, обработку несуществующего недуга, отображение сохранённых записей, временную метку. Укажите, какие факты можно проверить unit-тестами, а какие требуют интеграционного тестирования.
Решение: Факты: (1) POST /appointments с валидными данными возвращает 201 и redirect — интеграционный; (2) POST /appointments без поля name возвращает 400 с сообщением об ошибке — unit (валидация формы) + интеграционный; (3) POST /appointments с ailment_id=999 возвращает 400 или 404 — интеграционный (требует базы); (4) GET /appointments после успешного POST содержит созданную запись — интеграционный; (5) created_at записи находится в пределах последней минуты от времени теста — интеграционный. Unit-тесты возможны для (2) на уровне валидации входных данных без базы. Остальные требуют полного стека.
Сложность: intermediate
Кейсы: Название: Миграция монолитного прототипа на SDD-фазы в стартапе EdTech
Сценарий: Стартап разработал прототип образовательной платформы за 3 месяца «на коленке»: курсы, уроки, домашние задания, чаты, платежи, аналитика — всё в одном репозитории без тестов. При найме новых разработчиков выяснилось, что никто не понимает, какая функциональность работает, а какая — «заглушка для демо». Инвесторы требовали доказательств работоспособности.
Задача: Команда из 8 человек не могла параллельно работать из-за постоянных конфликтов в коде. Невозможно было показать инвесторам конкретный прогресс: «всё почти готово» звучало уже полгода. Платёжная система ломала чаты, а аналитика показывала случайные числа. Необходимо было перейти к прозрачной, проверяемой разработке без переписывания всего с нуля.
Решение: Техлид адаптировал подход AgentClinic: выделил доменные сущности (Курс, Урок, Ученик, Задание, Попытка, Отзыв) и зафиксировал доменный словарь. Разбил монолит на фазы, аналогичные SDD-циклу: (1) «Hello Framework» — базовый отклик; (2) «Курсы и уроки» — просмотр контента; (3) «Задания» — создание и проверка; (4) «Попытки» — сохранение ответов ученика; (5) «Отзывы» — обратная связь. Платежи и аналитику вынесли в отдельные спецификации со статусом «вне учебного домена MVP». Для каждой фазы написали requirements.md, plan.md, validation.md с проверяемыми фактами.
Результат: За 6 недель команда стабилизировала ядро платформы (фазы 1-4). Инвесторам предъявили конкретный чек-лист: 47 проверяемых фактов, из которых 43 проходили автоматически. Новые разработчики входили в проект за 2 дня вместо 2 недель благодаря доменному словарю. Платёжная система была добавлена позже как отдельная фаза с собственной спецификацией, не ломая существующий функционал. Команда сократила количество критических багов с 15 в неделю до 2.
Извлечённые уроки: Доменная карта и единый словарь устраняют «фольклорные знания» — информацию, которая существует только в головах отдельных разработчиков
Проверяемые факты превращают разговоры с инвесторами из «всё почти готово» в конкретные метрики готовности
Явное определение границ домена защищает команду от преждевременной сложности и позволяет фокусироваться на ценности
Связанные концепции: Доменная карта
SDD-цикл
Проверяемые факты
Границы учебного домена
Доменный словарь
Название: Провал интеграции из-за нарушения доменного словаря в корпоративном проекте
Сценарий: Крупный банк разрабатывал внутреннюю систему для управления кредитными заявками. Проект разделили между тремя командами: фронтенд (мобильное приложение), бэкенд (API), аналитика (отчёты). Каждая команда работала в своей документации без единого доменного словаря.
Задача: В мобильном приложении «клиент» означал физическое лицо, подавшее заявку. В API «клиент» был внутренним идентификатором юридического лица-партнёра. В аналитике «клиент» обозначал любой объект в CRM. При интеграции данные смешивались: заявки физических лиц приписывались юридическим лицам, отчёты показывали невозможные цифры. Исправление потребовало 3 недели аудита 200+ эндпоинтов и 15 конфигурационных файлов.
Решение: После инцидента внедрили подход, аналогичный доменному словарю AgentClinic: фиксированные термины с определениями в общем репозитории. «Заявитель» — физическое лицо, подавшее кредитную заявку. «Партнёр» — юридическое лицо, с которым у банка договор. «Заявка» — единый документ в системе. Технические имена полей в API оставили на английском (applicant, partner, application), пользовательские сценарии перевели на русский с единой терминологией. Ввели автоматический линтер документации, проверяющий соответствие словарю.
Результат: Время onboarding новых аналитиков сократилось с 3 недель до 4 дней. Количество интеграционных ошибок, связанных с семантикой, упало на 80%. При расширении системы на ипотечные заявки добавили термин «Объект недвижимости» без конфликтов с существующими сущностями. Проект стал примером для других департаментов банка.
Извлечённые уроки: Нарушение доменного словаря — не «стилистическая проблема», а источник дорогостоящих интеграционных багов
Разделение технических имён (английские, для кода) и пользовательских терминов (русские, для спецификаций) решает проблему многоязычных команд
Автоматизация проверки словаря (линтеры, CI-пайплайны) важнее ручных инструкций
Связанные концепции: Доменный словарь
Сущность
Границы учебного домена
Советы по изучению: Создайте физическую или цифровую «карту стены»: распечатайте сущности AgentClinic на карточках и соедините линиями связи. Визуальное пространственное расположение помогает запомнить структуру лучше, чем табличное чтение
Практикуйте «обратный перевод»: берите технические термины из кода (таблица agent_ailments, маршрут /appointments) и формулируйте их пользовательскую семантику на русском с использованием доменного словаря. Это тренирует переключение между техническим и пользовательским контекстом
Для каждой фазы SDD самостоятельно придумайте «факт, который легко забыть». Например, для фазы «Запись на приём» — проверка XSS в поле message. Сравните с предложенными в материале — это развивает критическое мышление о полноте спецификаций
Используйте метод «преподавания»: объясните доменную карту AgentClinic коллеге или даже воображаемому слушателю. Попытка простым языком объяснить, почему agent_ailments — связующая таблица, а не поле, быстро выявляет пробелы в понимании
Проводите «аудит границ» для своих текущих проектов: какие функции «не входят в домен» без отдельной спецификации? Это упражнение переносит концепции AgentClinic на реальную практику
Создайте шаблон документа validation.md для одной из фаз, используя формат Given-When-Then или просто список фактов. Попробуйте написать тест, реализующий один из фактов — даже мысленно это укрепляет связь между спецификацией и кодом
Дополнительные ресурсы: Оригинальный документ «приложение b. доменная карта agentclinic»: Исходный материал курса, на основе которого построен данный гайд
Книга «domain-driven design» эрика эванса: Фундаментальная работа о предметно-ориентированном проектировании — доменные карты, ограниченные контексты, единый язык
Книга «implementing domain-driven design» вона вернона: Практическое руководство по внедрению DDD с примерами кода и паттернов
Статья «specification by example» гойко аджича: Методология формулирования требований через проверяемые примеры, родственная SDD-циклу
Инструмент «event storming»: Техник группового моделирования домена через события — полезна для расширения доменных карт в команде
Sqlite documentation (sqlite.org/lang.html): Официальная документация по SQL для самостоятельного проектирования схем, аналогичных предложенной в AgentClinic
Фреймворк hono (hono.dev): Документация лёгкого веб-фреймворка, используемого в фазе «Hello Hono» — для практической реализации маршрутов
Статья «the c4 model for software architecture» саймона брауна: Метод визуализации архитектуры программного обеспечения, включающий контекстные и контейнерные диаграммы — полезен для расширения доменных карт
Резюме: Доменная карта AgentClinic — это не просто шуточная метафора, а тщательно спроектированный учебный инструмент для освоения SDD-цикла. Её ключевые принципы: сатирический, но семантически точный домен; пять чётко определённых сущностей с атрибутами и примерами; итеративное наращивание функциональности через шесть фаз с проверяемыми фактами; единый доменный словарь, разделяющий технические английские имена и пользовательские русские термины; явные границы, защищающие от преждевременной сложности. Освоив эту карту, разработчик учится проектировать предметные области, которые достаточно насыщенны для демонстрации реальных паттернов, но достаточно просты для контролируемого обучения. Главный навык — переводить расплывчатые пожелания («сделайте клинику для агентов») в конкретные сущности, маршруты, таблицы и факты, которые можно проверить автоматически.