Повседневные сценарии¶

Пошаговые процедуры для оператора: поставить задачу, отдать её агенту, проследить прогон, принять ревью, взять задачу самому, передать работу другому харнессу и восстановиться после потери владения. Каждый сценарий показан в консоли и через MCP-плагин Claude Code; вызовы cp_* — это то, что агент делает по вашей команде после вашего явного решения.

Общая картина¶

flowchart LR
    A["Создать задачу<br/>(тип, Workspace, исполнитель)"] --> B{"Кому?"}
    B -- "агенту" --> C["Runner берёт задачу<br/>claim → run → ветка"]
    B -- "себе" --> D["Claim → run<br/>работа в репозитории"]
    C --> E["Прогон в консоли:<br/>ход, действия, артефакты"]
    E --> F["Приёмка задачи:<br/>gate-approval ревью"]
    F -- "approve" --> G["Вливание ветки,<br/>задача done"]
    F -- "reject" --> H["Задача возвращается<br/>тому же агенту"] --> C
    D --> I["Артефакты, завершение"]
    D -- "смена харнесса" --> J["Handoff"] --> D

Создать задачу¶

КонсольClaude Code

«Задачи» → Создать задачу (или кнопка в шапке модуля).
Заполните название и описание: контекст, критерии готовности, ссылки.
Выберите тип (например coding-task для работы с кодом), Workspace, приоритет, срок.
Исполнитель — человек или агент (см. следующий сценарий), либо «не назначать».
Создать — откроется карточка задачи.

Попросите ассистента завести задачу. Он покажет черновик и вызовет инструмент только после вашего «да»:

cp_list_task_types()                       # какой тип выбрать
cp_create_task(
  title="Добавить фильтр по сроку в список задач",
  description="Контекст… Критерии готовности: …",
  type_key="coding-task",
  priority="high",
  assignee_id="<cp-principal-id>",
  due_date="2026-10-01"
)

workspace_id и проект подставляются из привязки репозитория; guard плагина не даст завести задачу в чужом проекте.

Хорошее описание для агента

Агент читает описание буквально. Укажите, что сделать и как проверить результат (какие тесты, какое поведение). Как устроен репозиторий — не повторяйте в каждой задаче, это дело файла соглашений runner'а (Адаптеры). Задачу, которую нельзя проверить, агент закроет «как понял».

Назначить задачу агенту¶

Runner в режиме CONTROL_PLANE_AGENT_ONLY_ASSIGNED=1 берёт только задачи, назначенные его principal'у. Поэтому «поставить задачу агенту» = назначить исполнителем CP principal агента.

Узнайте CP principal id исполнителя — экран «Участники и ключи» (kind агент) или у администратора.
Проверьте, что задача в том Workspace (проекте), который обслуживает этот runner (CONTROL_PLANE_AGENT_WORKSPACE), и что её тип — тот, который он берёт.
Назначьте:
КонсольClaude Code
Карточка задачи → «Мета» → Редактировать → «Исполнитель» → агент → Сохранить.
cp_get_task("<publicId>") # узнать version cp_update_task(task="<publicId>", expected_version=4, assignee_id="<cp-principal-id агента>")
В течение интервала опроса runner'а (по умолчанию 5 с) задача перейдёт в статус захвата типа (например in_progress), в карточке появится захват агента и прогон.

Задача не берётся

Проверьте по порядку: назначена ли она именно этому principal'у; тот ли Workspace; свободна ли (нет чужого захвата, не блокирует ли её неразрешённый gate-approval или зависимость — панель claimability в карточке); жив ли runner (экран «Агенты и сессии»). Если тип задачи исполняется скиллом, а principal runner'а не имеет task_types.read, демон такую задачу пропускает.

Проследить прогон агента¶

Карточка задачи → блок прогонов → ссылка на прогон, или «Агенты и сессии» → текущая работа агента.
На экране прогона:
- Действия обновляются вживую: каждый вызов инструмента агента (tool.Bash, tool.Read, tool.Edit…) со сводкой входа и статусом;
- Контрольные точки: execution.workspace (ветка, базовый коммит, ревизии соседей), claude-code.session (id сессии, фаза);
- по завершении хода — Ход прогона (транскрипт) и Итоговый ответ.
После успеха у задачи появляются артефакты:
- report — summary агента: что сделано, какие тесты прогнаны, что осталось;
- transcript — ограниченный транскрипт;
- commit — ветка task/<publicId> и коммит; published: true значит, что ветка есть в forge.

Через MCP то же самое:

cp_get_task("<publicId>")
cp_list_artifacts(task_id="<task-id>")
cp_get_run_context(run_id="<run-id>")

Что видите	Что это значит
прогон `failed`, причина `restart_recovery`	runner перезапускался посреди работы; задача вернулась в очередь, следующая попытка продолжит ту же ветку и сессию
`failed: lease_lost` / `ownership_lost`	аренда потеряна во время работы; результат не записан
`failed: workspace_busy`	рабочую копию держит другой процесс runner'а
`failed: ClaudeCodeError: claude did not finish within …`	ход упёрся в таймаут; разбейте задачу или попросите поднять таймаут
успех, но нет артефакта `commit`	агент ничего не изменил
`commit` с `published: false`	ветка не опубликована — критерии ревью и вливания пропущены, сообщите инженеру runner'а
`failed: executor_blocked`, задача в `blocked`	агент сообщил, что не может сделать работу; причина — в комментарии задачи

Отменить идущий прогон — кнопка Запросить отмену в шапке карточки задачи.

Принять или отклонить ревью¶

Задача на код (coding-task) после сдачи ждёт приёмки: её тип объявляет критерии «ревью человеком», затем «вливание ветки». Если вы — ревьюер установки, после каждой сданной задачи с опубликованной веткой ядро запрашивает у вас блокирующий approval на самой задаче — отдельной задачи ревью нет.

Найдите approval: экран Согласования (фильтр «ожидают»), Фокус, карточка задачи; уведомление в Telegram с кнопками; в Claude Code — cp_list_approvals(); в Human Harness — секция Decide.
Прочитайте задачу и отчёт агента (артефакт report). Ветка, коммит и целевая ветка — в артефакте commit задачи.

Посмотрите изменения от merge-base с целевой веткой:

git fetch origin
git diff $(git merge-base origin/<targetBranch> origin/task/<publicId>) origin/task/<publicId>

Решите:

КонсольClaude Code

Карточка approval → комментарий → Согласовать или Отклонить.

cp_approve(approval_id="<approval-id>", comment="Принято")
cp_reject(approval_id="<approval-id>",
          comment="Нет теста на пустой фильтр; миграция не обратима")

Что происходит дальше:
- approve — ядро вливает одобренный коммит в целевую ветку скиллом git.merge@1 вашими полномочиями; задача становится выполненной, её зависимые — доступными. Если вливание не удалось (конфликт, ветка сдвинулась), задача возвращается агенту с причиной;
- reject — задача возвращается в todo тому же агенту на ту же ветку; ваш комментарий придёт ему в блоке «Замечания последней проверки». После повторной сдачи вы получите новый запрос решения.

Комментарий при отклонении — это задание агенту

Пишите его как постановку: что именно не так и как проверить исправление.

Подробно — Ревью и вливание кода.

Взять задачу самому в Claude Code¶

Откройте сессию Claude Code в привязанном репозитории. Ассистент сам вызовет cp_whoami, cp_context и при необходимости cp_focus_project.

Попросите показать работу:

cp_list_tasks(system_status_category="active", assignee_id="<мой cp-principal-id>")
cp_list_work(assigned_to_me=true)

Выберите задачу и скажите явно: «берём ». Ассистент:

cp_get_task("<publicId>")          # claimability, переходы
cp_list_comments("<publicId>")     # решения и блокеры обычно в треде
cp_claim_task("<publicId>", intent="реализация фильтра")
cp_start_run()
cp_get_run_context()                # checkpoints прошлых попыток, артефакты, approvals

Работа в репозитории. По ходу:
- cp_checkpoint(kind="progress", data={"branch": "...", "next": "..."}) после значимых шагов и перед рискованными действиями;
- cp_comment(...) — решение, вопрос, блокер (после вашего согласия с текстом).

Результат:

cp_create_artifact(type="commit", name="feature/due-filter@3f1c2a9",
                   uri="git:3f1c2a9…", metadata={"branch": "feature/due-filter"})

Завершение — только по вашей отдельной команде: cp_complete_run() (по умолчанию завершает и задачу; статус завершения берётся из типа задачи). Если работа не удалась — cp_fail_run(reason="…"), claim остаётся за вами.

Смена статуса без завершения (например blocked) — через cp_update_task и только по переходу с route: update из cp_get_task.

Передать работу другому харнессу (handoff)¶

Handoff нужен, когда работу по задаче продолжит другой харнесс: вы переходите из Claude Code в Codex, на другую машину или передаёте задачу коллеге.

Убедитесь, что всё значимое записано: артефакты (коммиты, PR, документы), checkpoints.
Попросите ассистента подготовить handoff. Он покажет summary, следующие шаги и ссылки на evidence — без транскрипта, рассуждений, секретов и локальных путей.
После вашего подтверждения:
```
cp_prepare_handoff(
  summary="Фильтр по сроку реализован в API, не сделан UI",
  next_steps=["Добавить фильтр в таблицу задач", "Прогнать e2e"],
  evidence_refs=["git:3f1c2a9…"]
)
```
Атомарно: checkpoint вида handoff, run → suspended, claim освобождён. 4. Закройте первую сессию. 5. Во втором харнессе: cp_whoami, cp_context, найти задачу, по вашему решению — новый cp_claim_task, новый cp_start_run, затем cp_get_run_context: он вернёт handoff- checkpoint и артефакты предыдущего run.

Второй харнесс не продолжает старый run и не читает чужой транскрипт: он восстанавливается только из авторитетного состояния Control Plane.

Ожидание решения (gate) внутри своей работы¶

Если посреди работы нужно чьё-то решение (например согласование схемы):

cp_checkpoint(kind="before-approval", data={"next": "применить миграцию после согласования"})
cp_request_approval(gate=true, required_role_id="<role-id>",
                    comment="Согласовать изменение схемы: …")
cp_suspend_run(reason="waiting_approval", waiting_for_approval_id="<approval-id>")
# run архивируется, claim освобождается

После решения продолжение — всегда новый claim и новый run, читающий checkpoints.

Потеря владения (`stale_claim`)¶

Инструмент вернул stale_claim, task_already_claimed или run_not_active: ваша аренда истекла или задачу перехватили.

Прекратите любые записи по задаче — не повторяйте checkpoint, артефакт или завершение.
cp_context — посмотрите, чей сейчас claim и какой run активен.
Решите вместе с владельцем задачи: дождаться, перехватить истёкший захват (в консоли — перехватить в панели «Захват»), или передать работу через комментарий.

Консольный аналог — панель «Захват» карточки: состояние «аренда истекла: задачу можно перехватить» и кнопка перехватить.

Разобрать упавший прогон агента¶

Экран прогона → причина провала в шапке, последние действия и checkpoints.
Если это обрыв (restart_recovery, lease_lost) — ничего делать не нужно: задача вернулась в очередь, следующая попытка продолжит ту же рабочую копию и сессию агента.
Если агент упёрся в задачу (таймаут, красные тесты, непонятные требования) — уточните описание или разбейте задачу, оставьте комментарий и при необходимости переназначьте.
Если причина в окружении runner'а (нет доступа к forge, нет прав) — сообщите инженеру runner'а; см. Диагностика: исполнение и runner.

Шпаргалка¶

Хочу	Консоль	Claude Code
Увидеть, что ждёт меня	Фокус	`cp_context`, `cp_list_approvals`
Создать задачу	«Создать задачу»	`cp_create_task`
Отдать агенту	Мета → Исполнитель	`cp_update_task(assignee_id=…)`
Посмотреть прогон	карточка → прогон	`cp_get_run_context`
Решить approval	Согласования	`cp_approve` / `cp_reject`
Взять задачу	«Захватить»	`cp_claim_task` → `cp_start_run`
Записать результат	«Прикрепить файл»	`cp_create_artifact`
Прокомментировать	тред в карточке	`cp_comment`
Передать харнессу	—	`cp_prepare_handoff`
Завершить	«Завершить задачу»	`cp_complete_run`