| 1 | # Playbook: OOA&D — операционный проход для агента v1 |
| 2 | |
| 3 | **Назначение:** пошаговый **фундаментальный проход** перед реализацией или крупным рефакторингом. Не заменяет чтение Larman, но заставляет **не пропускать анализ**. |
| 4 | |
| 5 | **Фундамент:** `kb-ooad-fundamentals-v1.md` |
| 6 | **Быстрый контракт в коде:** `playbook-domain-nouns-verbs-decomposition-v1.md` |
| 7 | |
| 8 | **Версия:** v1.0 · 2026-05-17 |
| 9 | |
| 10 | --- |
| 11 | |
| 12 | ## Когда обязателен проход |
| 13 | |
| 14 | - Новая **подсистема** или экран (чат, граф, wizard, MCP-панель). |
| 15 | - Рост **`switch` / `enum Kind` / общего record** в renderer, ViewModel, handler. |
| 16 | - Задача «сделать визуал», но в домене уже есть **именованные понятия** (Message, Thread, Order, …). |
| 17 | - Пользователь явно просит **OOA&D**, **декомпозицию**, **сущности**. |
| 18 | |
| 19 | **Можно сократить** (только nouns-verbs чеклист): мелкий баг в одном типе, однострочный фикс, конфиг. |
| 20 | |
| 21 | --- |
| 22 | |
| 23 | ## Проход (7 шагов) |
| 24 | |
| 25 | ### Шаг 0 — Зафиксировать границу задачи |
| 26 | |
| 27 | - Что **в scope** (один модуль, один слой, одна фича)? |
| 28 | - Какой **артефакт** на выходе (типы, ADR, рефакторинг файла X)? |
| 29 | |
| 30 | ### Шаг 1 — Словарь предметной области (OOA) |
| 31 | |
| 32 | Выписать в ответ пользователю или в черновик ADR (таблица): |
| 33 | |
| 34 | | Существительные (кандидаты в типы) | Глаголы (кандидаты в операции) | |
| 35 | |-----------------------------------|-------------------------------| |
| 36 | | … | … | |
| 37 | |
| 38 | - Источники: запрос, ADR, `*Snapshot`, compositor, UI-строки. |
| 39 | - Пометить **синонимы** и **шум** (не домен). |
| 40 | |
| 41 | ### Шаг 2 — Уточнить атрибут vs тип |
| 42 | |
| 43 | Для каждого существительного: |
| 44 | |
| 45 | - Есть **собственное поведение** или жизненный цикл? → **отдельный тип**. |
| 46 | - Только свойство другого понятия? → **поле** (`IsPending` у `Confirmation`). |
| 47 | - Стабильный набор вариантов без разного поведения? → **enum** (редко — единственный дискриминатор на много видов UI). |
| 48 | |
| 49 | ### Шаг 3 — CRC (мини) |
| 50 | |
| 51 | Для 3–10 главных кандидатов — таблица: |
| 52 | |
| 53 | | Class | Responsibilities (1–3) | Collaborators | |
| 54 | |-------|------------------------|---------------| |
| 55 | | Message | хранить текст; отображать в ленте | Thread | |
| 56 | | TopicCard | показать summary; hit open thread | Thread, Overview | |
| 57 | |
| 58 | ### Шаг 4 — Назначение операций (GRASP) |
| 59 | |
| 60 | - Каждый глагол привязан к **Information Expert** или **Controller**. |
| 61 | - Варианты поведения → **Polymorphism** (`ISkiaChatEntity`), не `switch`. |
| 62 | - Создание объектов сцены → **Creator** (`SceneBuilder`). |
| 63 | |
| 64 | ### Шаг 5 — Слои |
| 65 | |
| 66 | Явно разделить: |
| 67 | |
| 68 | 1. Domain / snapshot |
| 69 | 2. Application (ViewModel, команды) |
| 70 | 3. Presentation (Skia, XAML) |
| 71 | 4. Infrastructure |
| 72 | |
| 73 | Зависимости — **к domain**, не «всё в Control». |
| 74 | |
| 75 | ### Шаг 6 — Реализация |
| 76 | |
| 77 | - Сначала **скелет типов** и интерфейсов (`Measure`/`Draw`/`CreateHit` для UI). |
| 78 | - Потом наполнение, стили, цвета. |
| 79 | - Control — **оркестратор** (цикл, scroll, theme). |
| 80 | |
| 81 | ### Шаг 7 — Проверка (чеклист) |
| 82 | |
| 83 | - [ ] Нет второго `case` по **доменному виду** в одном renderer. |
| 84 | - [ ] Имена типов = **существительные** домена (или явные fabrication: `SceneBuilder`). |
| 85 | - [ ] Глаголы — **методы**, не комментарии «// draw topic» внутри 200 строк. |
| 86 | - [ ] Сборка/тесты; для C# — `roslyn_get_diagnostics` по затронутым файлам. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Связка с рефакторингом legacy |
| 91 | |
| 92 | Если код уже есть с `ItemKind`: |
| 93 | |
| 94 | 1. Словарь из **текущих** `case` и полей record → это и есть пропущенные существительные. |
| 95 | 2. Extract Class / Replace Conditional with Polymorphism (Fowler). |
| 96 | 3. Сверить с доменным snapshot — имена должны **совпадать по смыслу**. |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## Анти-паттерн агента |
| 101 | |
| 102 | > «Сейчас быстро поправлю визуал в `DrawOperation`, структуру потом.» |
| 103 | |
| 104 | **Стоп:** шаги 1–4 занимают мало токенов, экономят переписывание. Сначала типы, потом пиксели. |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | ## Связанные документы |
| 109 | |
| 110 | - `kb-ooad-fundamentals-v1.md` — теория, GRASP, источники |
| 111 | - `playbook-domain-nouns-verbs-decomposition-v1.md` |
| 112 | - `worlds/software-engineering-evidence/map-engineering-reading-v1.md` — Track C |
| 113 | |