Быстрый старт: Освоение Plannotator за 5 минут

Что вы сможете делать после изучения

✅ Понимать основные функции и сценарии использования Plannotator
✅ Установить Plannotator за 5 минут
✅ Настроить интеграцию с Claude Code или OpenCode
✅ Выполнить первое рецензирование плана и кода

Ваша текущая ситуация

Plannotator — это интерактивный инструмент рецензирования для Claude Code и OpenCode, который поможет решить следующие проблемы:

Проблема 1: Планы реализации, сгенерированные ИИ, читаются в терминале — много текста, нечёткая структура, рецензирование утомительно.

Проблема 2: При необходимости дать ИИ обратную связь приходится описывать текстом "удалить 3-й абзац", "изменить эту функцию" — высокие затраты на коммуникацию.

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

Проблема 4: Члены команды хотят участвовать в рецензировании, но не знают, как делиться содержимым планов.

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

Визуальный UI вместо чтения в терминале — чёткая структура
Выделите текст, чтобы добавить комментарий (удаление, замена, комментарий) — точная обратная связь
Визуальное рецензирование Git diff с поддержкой комментариев на уровне строк
Функция обмена URL — командная работа без бэкенда

Когда использовать этот инструмент

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

Использование Claude Code или OpenCode для разработки с помощью ИИ
Необходимость рецензирования планов реализации, сгенерированных ИИ
Необходимость проверки изменений кода
Необходимость делиться планами или результатами рецензирования кода с командой

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

Полностью ручное написание кода (без планов, сгенерированных ИИ)
Уже есть полноценный процесс рецензирования кода (например, GitHub PR)
Нет необходимости в инструменте визуального рецензирования

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

Что такое Plannotator

Plannotator — это интерактивный инструмент рецензирования, разработанный для AI Coding Agent (Claude Code, OpenCode), предоставляющий две основные функции:

Рецензирование планов: Визуальное рецензирование планов реализации, сгенерированных ИИ, с поддержкой добавления комментариев, одобрения или отклонения
Рецензирование кода: Визуальное рецензирование Git diff с поддержкой комментариев на уровне строк и нескольких режимов просмотра

Принцип работы

┌─────────────────┐
│   AI Agent      │
│ (генерация плана)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Plannotator   │ ← Локальный HTTP-сервер
│  (визуальный UI)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Браузер      │
│ (рецензирование)│
└─────────────────┘

Основной процесс:

AI Agent завершает план или изменения кода
Plannotator запускает локальный HTTP-сервер и открывает браузер
Пользователь просматривает план/код в браузере, добавляет комментарии
Пользователь одобряет или отклоняет, Plannotator возвращает решение AI Agent
AI Agent продолжает реализацию или вносит изменения на основе обратной связи

Безопасность

Все данные обрабатываются локально, не загружаются в облако:

Содержимое планов, diff кода, комментарии хранятся на вашем локальном компьютере
Локальный HTTP-сервер использует случайный порт (или фиксированный порт)
Функция обмена URL реализована путём сжатия данных в хэш URL, без необходимости бэкенда

🎒 Подготовка к началу

Системные требования:

Операционная система: macOS / Linux / Windows / WSL
Среда выполнения: Bun (скрипт установки обработает автоматически)
Среда ИИ: Claude Code 2.1.7+ или OpenCode

Выбор способа установки:

При использовании Claude Code: необходимо установить CLI + плагин
При использовании OpenCode: необходимо настроить плагин
Если нужно только рецензирование кода: достаточно установить CLI

Следуйте инструкциям

Шаг 1: Установка Plannotator CLI

macOS / Linux / WSL:

bash

curl -fsSL https://plannotator.ai/install.sh | bash

Windows PowerShell:

powershell

irm https://plannotator.ai/install.ps1 | iex

Windows CMD:

cmd

curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Вы должны увидеть: Скрипт установки автоматически загрузит Plannotator CLI, добавит его в системный PATH и отобразит номер версии (например, "plannotator v0.6.7 installed to ...").

Что делает скрипт установки?

Скрипт установки выполняет:

Загрузку последней версии Plannotator CLI
Добавление в системный PATH
Очистку возможных старых версий
Автоматическую установку команды /plannotator-review (для рецензирования кода)

Шаг 2: Настройка Claude Code (опционально)

Если вы используете Claude Code, необходимо установить плагин.

Выполните в Claude Code:

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

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

Вы должны увидеть: После успешной установки плагина в списке плагинов Claude Code появится plannotator.

Ручная настройка (опционально)

Если вы не хотите использовать систему плагинов, можно настроить hook вручную. Подробности см. в разделе Установка плагина Claude Code.

Шаг 3: Настройка OpenCode (опционально)

Если вы используете OpenCode, необходимо отредактировать файл opencode.json.

Отредактируйте opencode.json:

json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

Перезапустите OpenCode.

Вы должны увидеть: После перезапуска OpenCode автоматически загрузит плагин, инструмент submit_plan станет доступен.

Шаг 4: Первое рецензирование плана (пример с Claude Code)

Условие запуска: Попросите Claude Code сгенерировать план реализации и вызвать ExitPlanMode.

Пример диалога:

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

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

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

Браузер автоматически откроет Plannotator UI
Отобразится содержимое плана, сгенерированного ИИ
Можно выделить текст плана, добавить комментарий (удаление, замена, комментарий)
Внизу кнопки "Approve" и "Request Changes"

Действия:

Просмотрите план в браузере
Если план в порядке, нажмите Approve → ИИ продолжит реализацию
Если нужны изменения, выделите текст для изменения, нажмите Delete, Replace или Comment → нажмите Request Changes

Вы должны увидеть: После нажатия браузер автоматически закроется, Claude Code получит ваше решение и продолжит выполнение.

Шаг 5: Первое рецензирование кода

Выполните в директории проекта:

bash

/plannotator-review

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

Браузер откроет страницу рецензирования кода
Отобразится Git diff (по умолчанию незафиксированные изменения)
Слева дерево файлов, справа diff viewer
Нажмите на номер строки, чтобы выделить диапазон кода и добавить комментарий

Действия:

Просмотрите изменения кода в diff viewer
Нажмите на номер строки, чтобы выбрать код для рецензирования
Добавьте комментарий в правой панели (comment/suggestion/concern)
Нажмите Send Feedback, чтобы отправить агенту, или LGTM для одобрения

Вы должны увидеть: После нажатия Send Feedback браузер закроется, в терминале выведется отформатированное содержимое обратной связи, агент автоматически обработает его.

Контрольная точка ✅

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

[ ] Скрипт установки отображает "plannotator vX.X.X installed to ..."
[ ] В Claude Code запускается рецензирование плана, браузер автоматически открывает UI
[ ] В UI можно выделить текст плана, добавить комментарий
[ ] Нажатие Approve или Request Changes закрывает браузер
[ ] Выполнение /plannotator-review открывает интерфейс рецензирования кода
[ ] В рецензировании кода можно добавить комментарий на уровне строки, нажать Send Feedback

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

Предупреждения о подводных камнях

Ошибка 1: После установки запуск plannotator выдаёт "command not found"

Причина: Переменная окружения PATH не обновлена или требуется перезапуск терминала.

Решение:

macOS/Linux: выполните source ~/.zshrc или source ~/.bashrc, или перезапустите терминал
Windows: перезапустите PowerShell или CMD

Ошибка 2: После установки плагина в Claude Code рецензирование плана не запускается

Причина: Claude Code не перезапущен, hook не активирован.

Решение: Полностью выйдите из Claude Code (не просто закройте окно), затем откройте заново.

Ошибка 3: Браузер не открывается автоматически

Причина: Возможно, удалённый режим (например, devcontainer, SSH) или порт занят.

Решение:

Проверьте, установлена ли переменная окружения PLANNOTATOR_REMOTE=1
Посмотрите URL, выведенный в терминале, откройте вручную в браузере
Подробности см. в разделе Режим удалённого доступа/Devcontainer

Ошибка 4: В рецензировании кода отображается "No changes"

Причина: В данный момент нет незафиксированных изменений git.

Решение:

Сначала выполните git status, чтобы подтвердить наличие изменений
Или выполните git add, чтобы добавить некоторые файлы в индекс
Или переключитесь на другой тип diff (например, last commit)

Резюме урока

Plannotator — это локальный инструмент рецензирования, который повышает эффективность рецензирования планов и кода через визуальный UI:

Основные функции:

Рецензирование планов: Визуальное рецензирование планов, сгенерированных ИИ, с поддержкой точных комментариев
Рецензирование кода: Визуальное рецензирование Git diff с поддержкой комментариев на уровне строк
Обмен URL: Возможность делиться содержимым рецензирования без бэкенда
Интеграция с третьими сторонами: Автоматическое сохранение одобренных планов в Obsidian/Bear

Ключевые преимущества:

Локальное выполнение, безопасность данных
Визуальный UI, повышение эффективности
Точная обратная связь, снижение затрат на коммуникацию
Командная работа без системы учётных записей

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

В следующем уроке мы изучим Установку плагина Claude Code.
Вы узнаете:
Подробные шаги установки плагина Claude Code
Способ ручной настройки hook
Как проверить успешность установки
Решения распространённых проблем установки

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

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

Обновлено: 2026-01-24

Функция	Путь к файлу	Номера строк
Вход CLI (рецензирование планов)	`apps/hook/server/index.ts`	1-50
Вход CLI (рецензирование кода)	`apps/hook/server/index.ts`	46-84
Сервер рецензирования планов	`packages/server/index.ts`	1-200
Сервер рецензирования кода	`packages/server/review.ts`	1-150
Инструменты Git	`packages/server/git.ts`	1-100
UI рецензирования планов	`packages/editor/App.tsx`	1-200
UI рецензирования кода	`packages/review-editor/App.tsx`	1-200

Ключевые константы:

MAX_RETRIES = 5: Количество повторных попыток порта (packages/server/index.ts:80)
RETRY_DELAY_MS = 500: Задержка повторной попытки порта (packages/server/index.ts:80)

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

startPlannotatorServer(): Запуск сервера рецензирования планов (packages/server/index.ts)
startReviewServer(): Запуск сервера рецензирования кода (packages/server/review.ts)
runGitDiff(): Выполнение команды git diff (packages/server/git.ts)

Переменные окружения:

PLANNOTATOR_REMOTE: Флаг удалённого режима (apps/hook/server/index.ts:17)
PLANNOTATOR_PORT: Фиксированный порт (apps/hook/server/index.ts:18)
PLANNOTATOR_BROWSER: Пользовательский браузер (apps/hook/README.md:79)
PLANNOTATOR_SHARE: Переключатель обмена URL (apps/hook/server/index.ts:44)

Быстрый старт за 5 минут

Обзор планов и кода

Совместная работа + интеграция с заметками

Что делать при возникновении проблем

API и структуры данных

Что нового

Быстрый старт: Освоение Plannotator за 5 минут

Что вы сможете делать после изучения

Ваша текущая ситуация

Когда использовать этот инструмент

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

Что такое Plannotator

Принцип работы

Безопасность

🎒 Подготовка к началу

Следуйте инструкциям

Шаг 1: Установка Plannotator CLI

Шаг 2: Настройка Claude Code (опционально)

Шаг 3: Настройка OpenCode (опционально)

Шаг 4: Первое рецензирование плана (пример с Claude Code)

Шаг 5: Первое рецензирование кода

Контрольная точка ✅

Предупреждения о подводных камнях

Резюме урока

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

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

Быстрый старт: Освоение Plannotator за 5 минут ​

Что вы сможете делать после изучения ​

Ваша текущая ситуация ​

Когда использовать этот инструмент ​

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

Что такое Plannotator ​

Принцип работы ​

Безопасность ​

🎒 Подготовка к началу ​

Следуйте инструкциям ​

Шаг 1: Установка Plannotator CLI ​

Шаг 2: Настройка Claude Code (опционально) ​

Шаг 3: Настройка OpenCode (опционально) ​

Шаг 4: Первое рецензирование плана (пример с Claude Code) ​

Шаг 5: Первое рецензирование кода ​

Контрольная точка ✅ ​

Предупреждения о подводных камнях ​

Резюме урока ​

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

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

Быстрый старт: Освоение Plannotator за 5 минут

Что вы сможете делать после изучения

Ваша текущая ситуация

Когда использовать этот инструмент

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

Что такое Plannotator

Принцип работы

Безопасность

🎒 Подготовка к началу

Следуйте инструкциям

Шаг 1: Установка Plannotator CLI

Шаг 2: Настройка Claude Code (опционально)

Шаг 3: Настройка OpenCode (опционально)

Шаг 4: Первое рецензирование плана (пример с Claude Code)

Шаг 5: Первое рецензирование кода

Контрольная точка ✅

Предупреждения о подводных камнях

Резюме урока

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

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