| 1 | # Playbook: капитан и параллельные субагенты (v1) |
| 2 | |
| 3 | Стабильный id для ссылок и роутера: **`captain-parallel-v1`**. |
| 4 | |
| 5 | ## 1. Зачем это |
| 6 | |
| 7 | Некоторые задачи выигрывают от **одновременного** исследования разных частей репозитория, доков или команд — при условии, что **капитан** (ведущий агент в чате) потом **сводит результаты** и принимает решения о конфликтах и патчах. |
| 8 | |
| 9 | Это **не замена** обычному одному агенту: оверхед по контексту и координации имеет смысл при **средней и крупной** неопределённости (много файлов, несколько подсистем, нужно «разведать параллельно»). |
| 10 | |
| 11 | ## 2. Инструмент в Cursor |
| 12 | |
| 13 | - В среде доступен **Task** (субагенты): типы вроде `explore` (обход репо), `generalPurpose`, `shell`, при необходимости **несколько Task в одном ответе** — параллельный запуск. |
| 14 | - У субагента **нет полного чата**: в промпт нужно **вложить** всё существенное (цель, пути, ограничения, формат ответа). |
| 15 | |
| 16 | ## 3. Роли |
| 17 | |
| 18 | | Роль | Кто | Обязанность | |
| 19 | |------|-----|-------------| |
| 20 | | **Капитан** | Агент в основном чате | Декомпозиция, запуск воркеров, слияние, правки, финальная верификация | |
| 21 | | **Воркер** | Субагент (Task) | Узкая подзадача: поиск, чтение, один сценарий shell, черновик вывода | |
| 22 | |
| 23 | Капитан **не** обязан называться «капитаном» в UI — это **операционная модель**, не персонаж. |
| 24 | |
| 25 | ## 4. Протокол (пошагово) |
| 26 | |
| 27 | 1. **Зафиксировать цель** и критерий «готово» (тесты зелёные, поведение X, док обновлён). |
| 28 | 2. **Разрезать** работу на подзадачи с **явными границами** (каталог, слой, список файлов). Предпочитать границы по **разным файлам/проектам**. |
| 29 | 3. **Параллель** — только если подзадачи **не пишут в одни и те же файлы** и не требуют строгого порядка (иначе последовательно). |
| 30 | 4. **Бриф воркеру** (шаблон): |
| 31 | - корень workspace / репозитория (абсолютный путь, если известен); |
| 32 | - одна чёткая задача (вопрос или «найди X и верни список путей»); |
| 33 | - запреты (не трогать `git push`, не коммитить без явного запроса и т.д., по политике пользователя); |
| 34 | - **формат ответа**: маркированный список, таблица, «кратко + риски». |
| 35 | 5. **Слияние**: капитан проверяет противоречия, устраняет дубликаты, **не слепо** копирует вывод воркеров. |
| 36 | 6. **Верификация**: `dotnet build` / `dotnet test`, линтер, ручная проверка — что уместно по задаче. |
| 37 | |
| 38 | ## 5. Антипаттерны |
| 39 | |
| 40 | - Два воркера на **правку одного файла** в параллели → конфликты патчей. |
| 41 | - Субагент без **пути к репо** и без контекста задачи → бесполезный или галлюцинаторный ответ. |
| 42 | - Дробление на **слишком мелкие** подзадачи при малом объёме работы → лишняя задержка и токены. |
| 43 | - Параллель **shell** с **долгими** или **конфликтующими** командами в одном каталоге без очереди. |
| 44 | |
| 45 | ## 6. Когда не распараллеливать |
| 46 | |
| 47 | - Одна точка изменения, один файл. |
| 48 | - Нужна **тесная** последовательность (сначала миграция схемы, потом код). |
| 49 | - Задача «выполни и закоммить» в одном потоке быстрее, чем координация. |
| 50 | |
| 51 | ## 7. Где это уместно (любой проект, не только один репо) |
| 52 | |
| 53 | Паттерн **капитан + параллельные воркеры** не привязан к конкретному продукту. Имеет смысл, когда нужно **параллельно** разведать или проверить **разные части** одного workspace, а потом свести результат в основном чате. |
| 54 | |
| 55 | Типично: |
| 56 | |
| 57 | - **Несколько слоёв или пакетов** в одном репозитории (например API, домен, инфраструктура, UI) — воркеры по разным деревьям каталогов. |
| 58 | - **Несколько артефактов**: код + тесты + CI + документация; или основной репо + соседний модуль в монорепо. |
| 59 | - **Разные виды поиска**: карта символов по одному пути, список вызовов по другому, сверка с `README`/ADR третьим воркером. |
| 60 | - **Несколько инструментов** (MCP, CLI), когда обзор «кто что умеет» или проверка сценариев логично разнести по воркерам с общим брифом от капитана. |
| 61 | |
| 62 | **Корень команд и путей:** тот workspace, который открыт у пользователя в Cursor (не подменять путями из worktree без проверки). Запреты и политика коммитов/push — как в §4. |
| 63 | |
| 64 | ## 8. Пример: Cascade IDE (репо `Financial/software/open/cascade-ide`) |
| 65 | |
| 66 | Иллюстрация на одном из репо в домашнем workspace — **не** единственный случай использования этого playbook. |
| 67 | |
| 68 | Когда задача касается именно этого проекта: |
| 69 | |
| 70 | - **Разведать** сразу несколько зон: `Services/`, `ViewModels/MainWindowViewModel*.cs`, `Features/*`, MCP, тесты; |
| 71 | - после разведки капитан делает **сфокусированные** правки по плану B (логика в `Services/`, VM оркестратор), см. `docs/architecture-migration.md`. |
| 72 | |
| 73 | **Практика для воркеров (в рамках этого репо):** |
| 74 | |
| 75 | - `explore`: «найди все вхождения X», «карта partial MainWindowViewModel». |
| 76 | - `shell` (осторожно): только read-only или явно согласованные команды; сборка через очередь MCP, если у пользователя настроено. |
| 77 | |
| 78 | ## 9. Связь с другими playbook |
| 79 | |
| 80 | - Мультипроектный контекст и роутинг KB: [`../../workspace-context/playbook-multi-project-context-v1.md`](../../workspace-context/playbook-multi-project-context-v1.md), [`../../index-knowledge-router-v1.md`](../../index-knowledge-router-v1.md) (канон agent-notes). |
| 81 | - Целостность под давлением: [`../../domains/agent-operations/playbook-integrity-under-pressure-v1.md`](../../domains/agent-operations/playbook-integrity-under-pressure-v1.md). |
| 82 | |
| 83 | ## 10. Версионирование |
| 84 | |
| 85 | При существенном изменении процесса — добавить **`playbook-captain-parallel-agents-v2.md`** и оставить v1 для истории или пометить v1 устаревшим в шапке. |
| 86 | |