Основы ревью кода: просмотр Git Diff с помощью /plannotator-review
Чему вы научитесь
- ✅ Использовать команду
/plannotator-reviewдля ревью Git Diff - ✅ Переключаться между режимами side-by-side и unified
- ✅ Выбирать диапазон кода кликом по номеру строки и добавлять построчные комментарии
- ✅ Добавлять комментарии разных типов (comment/suggestion/concern)
- ✅ Переключаться между типами diff (uncommitted/staged/last commit/branch)
- ✅ Отправлять обратную связь AI Agent
Ваши текущие проблемы
Проблема 1: При просмотре изменений кода через git diff вывод прокручивается в терминале, и сложно полностью понять суть изменений.
Проблема 2: Когда вы хотите дать Agent обратную связь о проблемах в коде, приходится описывать текстом «проблема в строке 10», «измените эту функцию» — это легко приводит к недопониманию.
Проблема 3: Непонятно, какие именно файлы изменил Agent, и в большом объёме изменений сложно сфокусироваться на ключевых частях.
Проблема 4: После ревью кода хочется отправить структурированную обратную связь Agent, чтобы он внёс исправления согласно рекомендациям.
Plannotator поможет вам:
- Визуализировать Git Diff с поддержкой режимов side-by-side и unified
- Выбирать диапазон кода кликом по номеру строки для точной маркировки проблемных мест
- Добавлять построчные комментарии (comment/suggestion/concern) с предлагаемым кодом
- Переключаться между типами diff одним кликом (uncommitted, staged, last commit, branch)
- Автоматически преобразовывать комментарии в Markdown для точного понимания Agent
Когда использовать этот подход
Сценарии использования:
- После того как Agent завершил изменения кода, вам нужно проверить изменения
- Перед коммитом хотите полностью проверить свои изменения
- При командной работе нужна структурированная обратная связь о проблемах в коде
- Хотите переключаться между типами diff (незакоммиченные vs staged vs последний коммит)
Неподходящие сценарии:
- Ревью плана реализации, сгенерированного AI (используйте функцию ревью плана)
- Использование
git diffнапрямую в терминале (визуальный интерфейс не нужен)
🎒 Подготовка перед началом
Предварительные требования:
- ✅ Установлен Plannotator CLI (см. Быстрый старт)
- ✅ Настроен плагин Claude Code или OpenCode (см. соответствующее руководство по установке)
- ✅ Текущая директория находится в Git-репозитории
Способ запуска:
- Выполните команду
/plannotator-reviewв Claude Code или OpenCode
Основная концепция
Что такое ревью кода
Ревью кода — это инструмент визуального просмотра Git Diff, предоставляемый Plannotator, который позволяет просматривать изменения кода в браузере и добавлять построчные комментарии.
Зачем нужно ревью кода?
После того как AI Agent завершает изменения кода, обычно он выводит содержимое git diff в терминал. Такой текстовый формат затрудняет полное понимание изменений и не позволяет точно указать проблемные места. Plannotator предоставляет визуальный интерфейс (side-by-side или unified), поддерживает добавление комментариев кликом по номеру строки и отправку структурированной обратной связи Agent, чтобы он мог внести исправления согласно рекомендациям.
Рабочий процесс
┌─────────────────┐
│ Пользователь │
│ (выполняет │
│ команду) │
└────────┬────────┘
│
│ /plannotator-review
▼
┌─────────────────┐
│ CLI │
│ (запускает git)│
│ git diff HEAD │
└────────┬────────┘
│
│ rawPatch + gitRef
▼
┌─────────────────┐
│ Review Server │ ← Запуск локального сервера
│ /api/diff │
└────────┬────────┘
│
│ Браузер открывает UI
▼
┌─────────────────┐
│ Review UI │
│ │
│ ┌───────────┐ │
│ │ File Tree │ │
│ │ (список │ │
│ │ файлов) │ │
│ └───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ DiffViewer│ │
│ │ (сравнение│ │
│ │ кода) │ │
│ │ split/ │ │
│ │ unified │ │
│ └───────────┘ │
│ │ │
│ │ Клик по номеру строки
│ ▼ │
│ ┌───────────┐ │
│ │ Добавить │ │
│ │ комментарий│ │
│ │ comment/ │ │
│ │ suggestion/│ │
│ │ concern │ │
│ └───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ Отправить │ │
│ │ обратную │ │
│ │ связь │ │
│ │ Send │ │
│ │ Feedback │ │
│ │ или LGTM │ │
│ └───────────┘ │
└────────┬────────┘
│
│ Обратная связь в формате Markdown
▼
┌─────────────────┐
│ AI Agent │
│ (вносит │
│ исправления) │
└─────────────────┘Режимы просмотра
| Режим просмотра | Описание | Сценарий использования |
|---|---|---|
| Split (Side-by-side) | Разделение экрана: старый код слева, новый справа | Сравнение больших изменений, чёткое отображение до и после |
| Unified | Объединённый вид: удаления и добавления в одном столбце | Просмотр небольших изменений, экономия вертикального пространства |
Типы комментариев
Plannotator поддерживает три типа комментариев к коду:
| Тип комментария | Назначение | Отображение в UI |
|---|---|---|
| Comment | Комментарий к строке кода, вопрос или пояснение | Фиолетовая/синяя рамка |
| Suggestion | Конкретное предложение по изменению кода | Зелёная рамка с блоком предлагаемого кода |
| Concern | Маркировка потенциальной проблемы, требующей внимания | Жёлтая/оранжевая рамка |
Различия между типами комментариев
- Comment: для вопросов, пояснений, общей обратной связи
- Suggestion: для конкретных предложений по изменению кода (с предлагаемым кодом)
- Concern: для маркировки проблем, требующих исправления, или потенциальных рисков
Типы Diff
| Тип Diff | Git-команда | Описание |
|---|---|---|
| Uncommitted | git diff HEAD | Незакоммиченные изменения (по умолчанию) |
| Staged | git diff --staged | Изменения в staging area |
| Unstaged | git diff | Изменения вне staging area |
| Last commit | git diff HEAD~1..HEAD | Содержимое последнего коммита |
| Branch | git diff main..HEAD | Сравнение текущей ветки с основной |
Пошаговое руководство
Шаг 1: Запуск ревью кода
Выполните команду /plannotator-review в Claude Code или OpenCode:
Пользователь: /plannotator-review
CLI: Выполняется git diff...
Браузер открытВы должны увидеть:
- Браузер автоматически открывает интерфейс ревью кода Plannotator
- Слева отображается список файлов (File Tree)
- Справа отображается Diff Viewer (по умолчанию режим split)
- Вверху кнопки переключения режимов (Split/Unified)
- Внизу кнопки "Send Feedback" и "LGTM"
Шаг 2: Просмотр списка файлов
В File Tree слева просмотрите изменённые файлы:
- Файлы сгруппированы по путям
- Для каждого файла показана статистика изменений (additions/deletions)
- Клик по файлу переключает на соответствующий diff
Вы должны увидеть:
src/
auth/
login.ts (+12, -5) ← Кликните для просмотра diff этого файла
user.ts (+8, -2)
api/
routes.ts (+25, -10)Шаг 3: Переключение режимов просмотра
Нажмите кнопку "Split" или "Unified" вверху страницы для переключения режима:
Режим Split (Side-by-side):
- Старый код слева (серый фон, красное зачёркивание)
- Новый код справа (белый фон, зелёное выделение)
- Подходит для сравнения больших изменений
Режим Unified (объединённый):
- Старый и новый код в одном столбце
- Удалённые строки с красным фоном, добавленные — с зелёным
- Подходит для просмотра небольших изменений
Вы должны увидеть:
- Режим Split: разделение экрана, чёткое сравнение до и после
- Режим Unified: объединённый вид, экономия вертикального пространства
Шаг 4: Выбор строк кода и добавление комментариев
Добавление комментария Comment:
- Наведите курсор на строку кода — рядом с номером строки появится кнопка
+ - Нажмите кнопку
+или кликните по номеру строки для выбора - Выбор нескольких строк: кликните по начальному номеру, затем с зажатым Shift кликните по конечному
- Введите текст комментария во всплывающей панели
- Нажмите кнопку "Add Comment"
Добавление комментария Suggestion (с предлагаемым кодом):
- Выполните шаги выше для добавления комментария
- Нажмите кнопку "Add suggested code" в панели
- Введите предлагаемый код в появившемся поле
- Нажмите кнопку "Add Comment"
Вы должны увидеть:
- Комментарий отображается под строкой кода
- Комментарий Comment: фиолетовая/синяя рамка с текстом комментария
- Комментарий Suggestion: зелёная рамка с текстом комментария и блоком предлагаемого кода
- В боковой панели справа отображается список всех комментариев
Шаг 5: Переключение типа Diff
Выберите другой тип diff вверху страницы:
- Uncommitted changes (по умолчанию): незакоммиченные изменения
- Staged changes: изменения в staging area
- Last commit: содержимое последнего коммита
- vs main (если не на основной ветке): сравнение с основной веткой
Вы должны увидеть:
- Diff Viewer обновляется с новым содержимым diff
- Список файлов обновляется с новой статистикой изменений
Шаг 6: Отправка обратной связи Agent
Send Feedback (отправить обратную связь):
- Добавьте необходимые комментарии (Comment/Suggestion/Concern)
- Нажмите кнопку "Send Feedback" внизу страницы
- Если комментариев нет, появится диалог подтверждения
LGTM (Looks Good To Me):
Если с кодом всё в порядке, нажмите кнопку "LGTM".
Вы должны увидеть:
- Браузер автоматически закрывается (с задержкой 1.5 секунды)
- В терминале отображается содержимое обратной связи или "LGTM - no changes requested."
- Agent получает обратную связь и начинает вносить изменения в код
Шаг 7: Просмотр содержимого обратной связи (опционально)
Если вы хотите увидеть обратную связь, которую Plannotator отправил Agent, посмотрите в терминале:
# Code Review Feedback
## src/auth/login.ts
### Line 15 (new)
Здесь нужно добавить обработку ошибок.
### Line 20-25 (old)
**Suggested code:**
```typescript
try {
await authenticate(req);
} catch (error) {
return res.status(401).json({ error: 'Authentication failed' });
}src/api/routes.ts
Line 10 (new)
В этой функции отсутствует валидация входных данных.
**Вы должны увидеть**:
- Обратная связь сгруппирована по файлам
- Каждый комментарий показывает путь к файлу, номер строки, тип
- Комментарии Suggestion содержат блок предлагаемого кода
## Контрольная точка ✅
После выполнения всех шагов вы должны уметь:
- [ ] Выполнить команду `/plannotator-review`, браузер автоматически открывает интерфейс ревью кода
- [ ] Просматривать список изменённых файлов в File Tree
- [ ] Переключаться между режимами Split и Unified
- [ ] Выбирать строки кода кликом по номеру строки или кнопке `+`
- [ ] Добавлять комментарии Comment, Suggestion, Concern
- [ ] Добавлять предлагаемый код в комментарии
- [ ] Переключаться между типами diff (uncommitted/staged/last commit/branch)
- [ ] Нажать Send Feedback, браузер закрывается, в терминале отображается обратная связь
- [ ] Нажать LGTM, браузер закрывается, в терминале отображается "LGTM - no changes requested."
**Если какой-то шаг не работает**, см.:
- [Частые проблемы](../../faq/common-problems/)
- [Руководство по установке Claude Code](../../start/installation-claude-code/)
- [Руководство по установке OpenCode](../../start/installation-opencode/)
## Типичные ошибки
**Ошибка 1**: После выполнения `/plannotator-review` браузер не открывается
**Причина**: Возможно, порт занят или сервер не запустился.
**Решение**:
- Проверьте сообщения об ошибках в терминале
- Попробуйте вручную открыть отображаемый URL в браузере
- Если проблема сохраняется, см. [Устранение неполадок](../../faq/troubleshooting/)
**Ошибка 2**: После клика по номеру строки панель не появляется
**Причина**: Возможно, выбрана пустая строка или окно браузера слишком маленькое.
**Решение**:
- Попробуйте выбрать строку с кодом
- Увеличьте окно браузера
- Убедитесь, что JavaScript не отключён
**Ошибка 3**: После добавления комментария он не отображается под строкой кода
**Причина**: Возможно, выбрана пустая строка или окно браузера слишком маленькое.
**Решение**:
- Попробуйте выбрать строку с кодом
- Увеличьте окно браузера
- Убедитесь, что JavaScript не отключён
- Проверьте, отображается ли комментарий в списке в боковой панели справа
**Ошибка 4**: После нажатия Send Feedback в терминале не отображается обратная связь
**Причина**: Возможно, проблема с сетью или ошибка сервера.
**Решение**:
- Проверьте сообщения об ошибках в терминале
- Попробуйте отправить обратную связь повторно
- Если проблема сохраняется, см. [Устранение неполадок](../../faq/troubleshooting/)
**Ошибка 5**: Agent получил обратную связь, но не внёс изменения согласно рекомендациям
**Причина**: Agent мог неправильно понять намерение комментария.
**Решение**:
- Попробуйте использовать более конкретные комментарии (Suggestion точнее, чем Comment)
- Используйте Comment для добавления подробных пояснений
- В Suggestion предоставьте полный предлагаемый код
- Если проблема сохраняется, запустите `/plannotator-review` снова для ревью новых изменений
**Ошибка 6**: После переключения типа diff список файлов пуст
**Причина**: Возможно, выбранный тип diff не содержит изменений.
**Решение**:
- Попробуйте переключиться обратно на "Uncommitted changes"
- Проверьте статус git, убедитесь, что есть изменения
- Используйте `git status` для просмотра текущего состояния
## Итоги урока
Ревью кода — это инструмент визуального просмотра Git Diff, предоставляемый Plannotator:
**Основные операции**:
1. **Запуск**: выполните `/plannotator-review`, браузер автоматически открывает UI
2. **Просмотр**: просмотрите список изменённых файлов в File Tree
3. **Режим**: переключайтесь между режимами Split (side-by-side) и Unified
4. **Комментарии**: выбирайте строки кода кликом по номеру, добавляйте комментарии Comment/Suggestion/Concern
5. **Переключение**: выбирайте разные типы diff (uncommitted/staged/last commit/branch)
6. **Обратная связь**: нажмите Send Feedback или LGTM, обратная связь отправляется Agent
**Режимы просмотра**:
- **Split (Side-by-side)**: разделение экрана, старый код слева, новый справа
- **Unified**: объединённый вид, удаления и добавления в одном столбце
**Типы комментариев**:
- **Comment**: комментарий к строке кода, вопрос или пояснение
- **Suggestion**: конкретное предложение по изменению кода (с предлагаемым кодом)
- **Concern**: маркировка потенциальной проблемы, требующей внимания
**Типы Diff**:
- **Uncommitted**: незакоммиченные изменения (по умолчанию)
- **Staged**: изменения в staging area
- **Unstaged**: изменения вне staging area
- **Last commit**: содержимое последнего коммита
- **Branch**: сравнение текущей ветки с основной
## Анонс следующего урока
> В следующем уроке мы изучим **[Добавление комментариев к коду](../code-review-annotations/)**.
>
> Вы узнаете:
> - Как точно использовать комментарии Comment, Suggestion, Concern
> - Как добавлять предлагаемый код с форматированием
> - Как редактировать и удалять комментарии
> - Лучшие практики и типичные сценарии использования комментариев
> - Как выбирать сторону old/new в режиме side-by-side
---
## Приложение: справочник по исходному коду
<details>
<summary><strong>Нажмите, чтобы развернуть расположение исходного кода</strong></summary>
> Дата обновления: 2026-01-24
| Функция | Путь к файлу | Строки |
| --- | --- | --- |
| Сервер ревью кода | [`packages/server/review.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts#L1-L302) | 1-302 |
| UI ревью кода | [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx#L1-L150) | 1-150 |
| Компонент DiffViewer | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L1-L349) | 1-349 |
| Git-утилиты | [`packages/server/git.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/git.ts#L1-L148) | 1-148 |
| Точка входа Hook (review) | [`apps/hook/server/index.ts`](https://github.com/backnotprop/plannotator/blob/main/apps/hook/server/index.ts#L46-L84) | 46-84 |
| Определение типов комментариев | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L53-L83) | 53-83 |
**Ключевые типы**:
- `CodeAnnotationType`: перечисление типов комментариев к коду (comment, suggestion, concern) (`packages/ui/types.ts:53`)
- `CodeAnnotation`: интерфейс комментария к коду (`packages/ui/types.ts:55-66`)
- `DiffType`: перечисление типов Diff (uncommitted, staged, unstaged, last-commit, branch) (`packages/server/git.ts:10-15`)
- `GitContext`: интерфейс Git-контекста (`packages/server/git.ts:22-26`)
**Ключевые функции**:
- `startReviewServer()`: запуск сервера ревью кода (`packages/server/review.ts:79`)
- `runGitDiff()`: выполнение команды git diff (`packages/server/git.ts:101`)
- `getGitContext()`: получение Git-контекста (информация о ветке и опции diff) (`packages/server/git.ts:79`)
- `parseDiffToFiles()`: парсинг diff в список файлов (`packages/review-editor/App.tsx:48`)
- `exportReviewFeedback()`: экспорт комментариев в Markdown-обратную связь (`packages/review-editor/App.tsx:86`)
**API-маршруты**:
- `GET /api/diff`: получение содержимого diff (`packages/server/review.ts:118`)
- `POST /api/diff/switch`: переключение типа diff (`packages/server/review.ts:130`)
- `POST /api/feedback`: отправка обратной связи по ревью (`packages/server/review.ts:222`)
- `GET /api/image`: получение изображения (`packages/server/review.ts:164`)
- `POST /api/upload`: загрузка изображения (`packages/server/review.ts:181`)
- `GET /api/agents`: получение доступных agents (OpenCode) (`packages/server/review.ts:204`)
**Бизнес-правила**:
- По умолчанию просмотр незакоммиченного diff (`apps/hook/server/index.ts:55`)
- Поддержка переключения на diff vs main (`packages/server/git.ts:131`)
- Форматирование обратной связи в Markdown (`packages/review-editor/App.tsx:86`)
- При одобрении отправляется текст "LGTM" (`packages/review-editor/App.tsx:430`)
</details>