Основы ревью плана: визуальная проверка AI-планов

Чему вы научитесь

✅ Использовать визуальный интерфейс Plannotator для проверки AI-планов
✅ Выделять текст плана и добавлять различные типы аннотаций (удаление, замена, комментарий)
✅ Одобрять план, чтобы AI продолжил реализацию
✅ Отклонять план, отправляя аннотации как обратную связь для AI
✅ Понимать сценарии использования и различия типов аннотаций

Ваша текущая проблема

Проблема 1: AI-планы реализации приходится читать в терминале — много текста, структура неясна, проверка утомляет.

Проблема 2: Чтобы дать AI обратную связь, приходится описывать словами «удали третий абзац», «измени эту функцию» — высокие затраты на коммуникацию, AI может неправильно понять.

Проблема 3: Некоторые части плана не требуют изменений, некоторые нужно заменить, некоторые — прокомментировать, но нет инструмента для структурирования этой обратной связи.

Проблема 4: Непонятно, как сообщить AI, что план одобрен или требует доработки.

Plannotator поможет вам:

Визуальный UI вместо чтения в терминале — чёткая структура
Выделите текст и добавьте аннотацию (удаление, замена, комментарий) — точная обратная связь
Аннотации автоматически преобразуются в структурированные данные — AI точно понимает ваши намерения
Одобрение или отклонение одним кликом — AI реагирует мгновенно

Когда использовать этот подход

Сценарии использования:

AI Agent завершил план и вызвал ExitPlanMode (Claude Code)
AI Agent вызвал инструмент submit_plan (OpenCode)
Необходимо проверить AI-план реализации
Необходимо точно передать замечания по плану

Неподходящие сценарии:

Прямая реализация кода AI (без ревью плана)
План уже одобрен, нужно проверить фактические изменения кода (используйте функцию code review)

🎒 Подготовка

Предварительные требования:

✅ Установлен Plannotator CLI (см. Быстрый старт)
✅ Настроен плагин Claude Code или OpenCode (см. соответствующее руководство по установке)
✅ AI Agent поддерживает ревью плана (Claude Code 2.1.7+ или OpenCode)

Способы запуска:

Claude Code: После завершения плана AI автоматически вызывает ExitPlanMode, Plannotator запускается автоматически
OpenCode: AI вызывает инструмент submit_plan, Plannotator запускается автоматически

Основная концепция

Что такое ревью плана

Ревью плана — это основная функция Plannotator для визуальной проверки AI-планов реализации.

Зачем нужно ревью плана?

После генерации плана AI обычно спрашивает «Этот план подходит?» или «Начать реализацию?». Без визуального инструмента приходится читать текстовый план в терминале и отвечать размытыми фразами вроде «ок», «нет, измени XX». Plannotator позволяет просматривать план в визуальном интерфейсе, точно выделять части, требующие изменений, добавлять структурированные аннотации — AI легче понимает ваши намерения.

Рабочий процесс

┌─────────────────┐
│  AI Agent      │
│  (генерация    │
│   плана)       │
└────────┬────────┘
         │
         │ ExitPlanMode / submit_plan
         ▼
┌─────────────────┐
│ Plannotator UI  │  ← браузер открывается автоматически
│                 │
│ ┌───────────┐  │
│ │ Содержимое │  │
│ │ плана      │  │
│ │ (Markdown) │  │
│ └───────────┘  │
│       │         │
│       │ выделение текста
│       ▼         │
│ ┌───────────┐  │
│ │ Добавление │  │
│ │ аннотации  │  │
│ │ Delete/    │  │
│ │ Replace/   │  │
│ │ Comment    │  │
│ └───────────┘  │
│       │         │
│       ▼         │
│ ┌───────────┐  │
│ │ Решение   │  │
│ │ Approve/  │  │
│ │ Request   │  │
│ │ Changes   │  │
│ └───────────┘  │
└────────┬────────┘
         │
         │ {"behavior": "allow"} или
         │ {"behavior": "deny", "message": "..."}
         ▼
┌─────────────────┐
│  AI Agent      │
│  (продолжение  │
│   реализации)  │
└─────────────────┘

Типы аннотаций

Plannotator поддерживает четыре типа аннотаций, каждый с разным назначением:

Тип аннотации	Назначение	Обратная связь для AI
Delete	Удаление ненужного контента	"Удалить: [выделенный текст]"
Replace	Замена на лучший контент	"Заменить: [выделенный текст] на [ваш текст]"
Comment	Комментарий к фрагменту без требования изменений	"Комментарий: [выделенный текст]. Пояснение: [ваш комментарий]"
Global Comment	Глобальный комментарий, не привязанный к конкретному тексту	"Глобальный комментарий: [ваш комментарий]"

Approve vs Request Changes

Тип решения	Действие	Обратная связь для AI	Сценарий использования
Approve	Нажать кнопку Approve	`{"behavior": "allow"}`	План в порядке, одобрить сразу
Request Changes	Нажать кнопку Request Changes	`{"behavior": "deny", "message": "..."}`	Есть замечания для исправления

Различия между Claude Code и OpenCode

Claude Code: При Approve аннотации не отправляются (игнорируются)
OpenCode: При Approve аннотации можно отправить как примечание (опционально)

При отклонении плана: На обеих платформах аннотации отправляются AI

Пошаговое руководство

Шаг 1: Запуск ревью плана

Пример для Claude Code:

В Claude Code начните диалог с AI, попросив сгенерировать план реализации:

Пользователь: Помоги мне составить план реализации модуля аутентификации

Claude: Хорошо, вот план реализации:
1. Создать модель пользователя
2. Реализовать API регистрации
3. Реализовать API входа
...
(AI вызывает ExitPlanMode)

Пример для OpenCode:

В OpenCode AI автоматически вызывает инструмент submit_plan.

Что вы должны увидеть:

Браузер автоматически открывает Plannotator UI
Отображается содержимое AI-плана (в формате Markdown)
Внизу страницы кнопки «Approve» и «Request Changes»

Шаг 2: Просмотр содержимого плана

Просмотрите план в браузере:

План отрендерен в формате Markdown: заголовки, абзацы, списки, блоки кода
Можно прокручивать для просмотра всего плана
Поддержка переключения светлой/тёмной темы (кнопка в правом верхнем углу)

Шаг 3: Выделение текста и добавление аннотаций

Добавление аннотации Delete:

Выделите мышью текст, который нужно удалить
Нажмите кнопку Delete во всплывающей панели инструментов
Текст будет отмечен стилем удаления (красное зачёркивание)

Добавление аннотации Replace:

Выделите мышью текст, который нужно заменить
Нажмите кнопку Replace во всплывающей панели инструментов
Введите новый текст в появившемся поле ввода
Нажмите Enter или кнопку подтверждения
Исходный текст будет отмечен стилем замены (жёлтый фон), ниже отобразится текст замены

Добавление аннотации Comment:

Выделите мышью текст, который хотите прокомментировать
Нажмите кнопку Comment во всплывающей панели инструментов
Введите комментарий в появившемся поле ввода
Нажмите Enter или кнопку подтверждения
Текст будет отмечен стилем комментария (синяя подсветка), комментарий отобразится в боковой панели

Добавление Global Comment:

Нажмите кнопку Add Global Comment в правом верхнем углу страницы
Введите глобальный комментарий в появившемся поле ввода
Нажмите Enter или кнопку подтверждения
Комментарий отобразится в разделе «Global Comments» боковой панели

Что вы должны увидеть:

После выделения текста сразу появляется панель инструментов (Delete, Replace, Comment)
После добавления аннотации текст отображается с соответствующим стилем (зачёркивание, фон, подсветка)
В боковой панели отображается список всех аннотаций, клик переходит к соответствующему месту
Можно нажать кнопку удаления рядом с аннотацией, чтобы её убрать

Шаг 4: Одобрение плана

Если план в порядке:

Нажмите кнопку Approve внизу страницы.

Что вы должны увидеть:

Браузер автоматически закрывается (с задержкой 1,5 секунды)
В терминале Claude Code/OpenCode отображается, что план одобрен
AI продолжает реализацию плана

Поведение Approve

Claude Code: Отправляется только {"behavior": "allow"}, аннотации игнорируются
OpenCode: Отправляется {"behavior": "allow"}, аннотации можно отправить как примечание (опционально)

Шаг 5: Отклонение плана (Request Changes)

Если план требует доработки:

Добавьте необходимые аннотации (Delete, Replace, Comment)
Нажмите кнопку Request Changes внизу страницы
Браузер покажет диалог подтверждения

Что вы должны увидеть:

Диалог подтверждения «Send X annotations to AI?»
После подтверждения браузер автоматически закрывается
В терминале Claude Code/OpenCode отображается содержимое обратной связи
AI доработает план на основе обратной связи

Поведение Request Changes

Claude Code и OpenCode: Оба отправляют {"behavior": "deny", "message": "..."}
Аннотации преобразуются в структурированный Markdown-текст
AI доработает план и снова вызовет ExitPlanMode/submit_plan

Шаг 6: Просмотр содержимого обратной связи (опционально)

Если хотите увидеть, что Plannotator отправил AI, посмотрите в терминале:

Claude Code:

Plan rejected by user
Please modify the plan based on the following feedback:

[структурированное содержимое аннотаций]

OpenCode:

<feedback>
[структурированное содержимое аннотаций]
</feedback>

Контрольный список ✅

После выполнения всех шагов вы должны уметь:

[ ] После запуска ревью плана AI браузер автоматически открывает Plannotator UI
[ ] Выделять текст плана и добавлять аннотации Delete, Replace, Comment
[ ] Добавлять Global Comment
[ ] Просматривать все аннотации в боковой панели и переходить к соответствующим местам
[ ] Нажать Approve — браузер закрывается, AI продолжает реализацию
[ ] Нажать Request Changes — браузер закрывается, AI дорабатывает план

Если какой-то шаг не работает, см.:

Типичные ошибки

Ошибка 1: После выделения текста панель инструментов не появляется

Причина: Возможно, выделен текст внутри блока кода или выделение охватывает несколько элементов.

Решение:

Старайтесь выделять текст в пределах одного абзаца или элемента списка
Для блоков кода используйте аннотацию Comment, не выделяйте несколько строк

Ошибка 2: После добавления аннотации Replace текст замены не отображается

Причина: Поле ввода текста замены могло быть отправлено некорректно.

Решение:

После ввода текста замены нажмите Enter или кнопку подтверждения
Проверьте, отображается ли текст замены в боковой панели

Ошибка 3: После нажатия Approve или Request Changes браузер не закрывается

Причина: Возможна ошибка сервера или проблемы с сетью.

Решение:

Проверьте сообщения об ошибках в терминале
Закройте браузер вручную
Если проблема сохраняется, см. Устранение неполадок

Ошибка 4: AI получил обратную связь, но не внёс изменения согласно аннотациям

Причина: AI мог неправильно понять намерение аннотации.

Решение:

Попробуйте использовать более явные аннотации (Replace яснее, чем Comment)
Используйте Comment для добавления подробных пояснений
Если проблема сохраняется, отклоните план повторно и скорректируйте аннотации

Ошибка 5: После добавления нескольких аннотаций Delete AI удалил только часть контента

Причина: Несколько аннотаций Delete могут пересекаться или конфликтовать.

Решение:

Убедитесь, что диапазоны текста аннотаций Delete не пересекаются
Если нужно удалить большой фрагмент, выделите весь абзац за один раз

Итоги урока

Ревью плана — это основная функция Plannotator для визуальной проверки AI-планов:

Основные операции:

Запуск: AI вызывает ExitPlanMode или submit_plan, браузер автоматически открывает UI
Просмотр: Просмотр содержимого плана в визуальном интерфейсе (формат Markdown)
Аннотации: Выделение текста, добавление Delete, Replace, Comment или Global Comment
Решение: Нажатие Approve (одобрить) или Request Changes (отклонить)
Обратная связь: Аннотации преобразуются в структурированные данные, AI продолжает или дорабатывает план

Типы аннотаций:

Delete: Удаление ненужного контента
Replace: Замена на лучший контент
Comment: Комментарий к фрагменту без требования изменений
Global Comment: Глобальный комментарий, не привязанный к конкретному тексту

Типы решений:

Approve: План в порядке, одобрить сразу (Claude Code игнорирует аннотации)
Request Changes: Есть замечания, аннотации отправляются AI

Анонс следующего урока

В следующем уроке мы изучим Добавление аннотаций к плану.
Вы узнаете:
Как точно использовать аннотации Delete, Replace, Comment
Как добавлять аннотации к изображениям
Как редактировать и удалять аннотации
Лучшие практики и типичные сценарии использования аннотаций

Приложение: справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Дата обновления: 2026-01-24

Функция	Путь к файлу	Строки
UI ревью плана	`packages/editor/App.tsx`	1-200
Определение типов аннотаций	`packages/ui/types.ts`	1-70
Сервер ревью плана	`packages/server/index.ts`	91-310
API: получение содержимого плана	`packages/server/index.ts`	132-134
API: одобрение плана	`packages/server/index.ts`	201-277
API: отклонение плана	`packages/server/index.ts`	280-309
Компонент Viewer	`packages/ui/components/Viewer.tsx`	1-100
Компонент AnnotationPanel	`packages/ui/components/AnnotationPanel.tsx`	1-50

Ключевые типы:

AnnotationType: перечисление типов аннотаций (DELETION, INSERTION, REPLACEMENT, COMMENT, GLOBAL_COMMENT) (packages/ui/types.ts:1-7)
Annotation: интерфейс аннотации (packages/ui/types.ts:11-33)
Block: интерфейс блока плана (packages/ui/types.ts:35-44)

Ключевые функции:

startPlannotatorServer(): запуск сервера ревью плана (packages/server/index.ts:91)
parseMarkdownToBlocks(): парсинг Markdown в блоки (packages/ui/utils/parser.ts)

API-маршруты:

GET /api/plan: получение содержимого плана (packages/server/index.ts:132)
POST /api/approve: одобрение плана (packages/server/index.ts:201)
POST /api/deny: отклонение плана (packages/server/index.ts:280)

Бизнес-правила:

Claude Code при одобрении не отправляет аннотации (apps/hook/server/index.ts:132)
OpenCode при одобрении может отправить аннотации как примечание (apps/opencode-plugin/index.ts:270)
При отклонении плана аннотации всегда отправляются (apps/hook/server/index.ts:154)

Основы ревью плана: визуальная проверка AI-планов ​

Чему вы научитесь ​

Ваша текущая проблема ​

Когда использовать этот подход ​

🎒 Подготовка ​

Основная концепция ​

Что такое ревью плана ​

Рабочий процесс ​

Типы аннотаций ​

Approve vs Request Changes ​

Пошаговое руководство ​

Шаг 1: Запуск ревью плана ​

Шаг 2: Просмотр содержимого плана ​

Шаг 3: Выделение текста и добавление аннотаций ​

Шаг 4: Одобрение плана ​

Шаг 5: Отклонение плана (Request Changes) ​

Шаг 6: Просмотр содержимого обратной связи (опционально) ​

Контрольный список ✅ ​

Типичные ошибки ​

Итоги урока ​

Анонс следующего урока ​

Приложение: справочник по исходному коду ​

Основы ревью плана: визуальная проверка AI-планов

Чему вы научитесь

Ваша текущая проблема

Когда использовать этот подход

🎒 Подготовка

Основная концепция

Что такое ревью плана

Рабочий процесс

Типы аннотаций

Approve vs Request Changes

Пошаговое руководство

Шаг 1: Запуск ревью плана

Шаг 2: Просмотр содержимого плана

Шаг 3: Выделение текста и добавление аннотаций

Шаг 4: Одобрение плана

Шаг 5: Отклонение плана (Request Changes)

Шаг 6: Просмотр содержимого обратной связи (опционально)

Контрольный список ✅

Типичные ошибки

Итоги урока

Анонс следующего урока

Приложение: справочник по исходному коду