Добавление аннотаций кода: комментарии, предложения и замечания

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

✅ Добавлять построчные аннотации в diff кода (comment/suggestion/concern)
✅ Предлагать изменения кода (suggestedCode)
✅ Отмечать участки кода, требующие внимания (concern)
✅ Просматривать и управлять всеми аннотациями (боковая панель)
✅ Понимать сценарии использования трёх типов аннотаций
✅ Экспортировать отзывы в формате Markdown

С какими проблемами вы сталкиваетесь

Проблема 1: При ревью изменений кода вы видите diff только в терминале, а потом пишете «в строке 3 ошибка», «предлагаю изменить на XXX» — указание позиции неточное.

Проблема 2: Некоторый код хочется просто прокомментировать (comment), для другого — предложить изменения (suggestion), а третий — серьёзная проблема, требующая внимания (concern), но нет инструмента для их разграничения.

Проблема 3: Хотите предложить изменения для функции, но не знаете, как передать фрагмент кода ИИ.

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

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

Кликните по номеру строки, чтобы выбрать диапазон кода с точностью до строки
Три типа аннотаций (comment/suggestion/concern) для разных сценариев
Можно прикрепить предлагаемый код — ИИ сразу видит решение
Боковая панель показывает все аннотации с переходом в один клик

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

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

После выполнения команды /plannotator-review для просмотра изменений кода
Когда нужно дать обратную связь по конкретным строкам кода
Когда хотите предложить ИИ изменения кода
Когда нужно отметить потенциальные проблемы или риски

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

Ревью плана реализации, сгенерированного ИИ (используйте функцию ревью плана)
Быстрый просмотр diff (используйте базовые функции код-ревью)

🎒 Подготовка

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

✅ Установлен Plannotator CLI (см. Быстрый старт)
✅ Изучены основы код-ревью (см. Основы код-ревью)
✅ Есть локальный Git-репозиторий с незакоммиченными изменениями

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

Выполните команду /plannotator-review в OpenCode или Claude Code

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

Что такое аннотации кода

Аннотации кода — это ключевая функция код-ревью в Plannotator для добавления построчной обратной связи в Git diff. Кликая по номерам строк для выбора диапазона кода, вы можете точно добавлять комментарии, предложения или замечания к конкретным строкам. Аннотации отображаются под diff, что позволяет ИИ точно понять ваши намерения.

Зачем нужны аннотации кода?

При код-ревью вам нужно давать обратную связь по конкретным строкам кода. Если просто описывать текстом «в строке 5 проблема», «предлагаю изменить на XXX», ИИ придётся самому искать код, что чревато ошибками. Plannotator позволяет кликнуть по номеру строки, выбрать диапазон кода и добавить аннотацию прямо в этом месте. Аннотация отображается под diff (в стиле GitHub), и ИИ точно видит, к какому участку кода относится ваше предложение.

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

┌─────────────────┐
│  /plannotator-   │  Команда запуска
│  review          │
└────────┬────────┘
         │
         │ Выполнение git diff
         ▼
┌─────────────────┐
│  Diff Viewer    │  ← Отображение diff кода
│  (split/unified) │
└────────┬────────┘
         │
         │ Клик по номеру строки / Hover +
         ▼
┌─────────────────┐
│  Выбор диапазона │
│  кода            │
│  (lineStart-     │
│   lineEnd)       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Добавление      │  ← Появляется панель
│  аннотации       │     инструментов
│  - Comment       │     Ввод комментария
│  - Suggestion    │     Опционально: код
│  - Concern       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Отображение     │  Под diff
│  аннотации       │  Список в боковой
│  (стиль GitHub)  │  панели
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Экспорт отзыва  │  Send Feedback
│  (Markdown)      │  ИИ получает
└─────────────────┘   структурированный отзыв

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

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

Тип аннотации	Назначение	Типичные сценарии	Предлагаемый код
Comment	Комментарий к участку кода, общая обратная связь	«Эту логику можно упростить», «Название переменной неясное»	Опционально
Suggestion	Конкретное предложение по изменению кода	«Предлагаю заменить цикл for на map», «Использовать await вместо Promise.then»	Рекомендуется
Concern	Отметка потенциальной проблемы или риска	«Этот SQL-запрос может иметь проблемы с производительностью», «Отсутствует обработка ошибок»	Опционально

Рекомендации по выбору типа аннотации

Comment: для «предложений без обязательности», например, стиль кода, направление оптимизации
Suggestion: для «настоятельных рекомендаций к изменению» с конкретным решением
Concern: для «проблем, требующих обязательного внимания», например, баги, риски производительности, уязвимости безопасности

Comment vs Suggestion vs Concern

Сценарий	Выбор типа	Пример текста
Код работает, но есть возможность оптимизации	Comment	«Это можно упростить с помощью async/await»
Код имеет явное улучшение	Suggestion	«Предлагаю использовать `Array.from()` вместо spread-оператора» (с кодом)
Обнаружен баг или серьёзная проблема	Concern	«Здесь отсутствует проверка на null, что может вызвать ошибку во время выполнения»

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

Шаг 1: Запуск код-ревью

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

bash

/plannotator-review

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

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

Шаг 2: Просмотр содержимого diff

Просмотрите изменения кода в браузере:

По умолчанию используется split-вид (сравнение слева-справа)
Можно переключиться на unified-вид (сравнение сверху-снизу)
Кликните по имени файла в дереве для переключения просматриваемого файла

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

Способ 1: Hover и клик по кнопке «+»

Наведите курсор на строку кода, к которой хотите добавить аннотацию
Справа появится кнопка + (только на строках diff)
Кликните по кнопке +
Появится панель инструментов аннотации

Способ 2: Прямой клик по номеру строки

Кликните по номеру строки (например, L10), чтобы выбрать одну строку
Кликните по другому номеру строки (например, L15), чтобы выбрать диапазон
После выбора диапазона панель инструментов появляется автоматически

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

Панель инструментов показывает выбранные строки (например, Line 10 или Lines 10-15)
Панель содержит поле ввода текста (Leave feedback...)
Опциональную кнопку «Add suggested code»

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

Сценарий: Дать рекомендацию по коду без обязательного требования изменений

Введите текст комментария в поле ввода панели инструментов
Опционально: кликните Add suggested code и введите предлагаемый код
Кликните кнопку Add Comment

Пример:

Текст комментария: Название параметров этой функции неясное, предлагаю переименовать в fetchUserData

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

Панель инструментов исчезает
Аннотация отображается под diff (синяя рамка)
В боковой панели появляется новая запись аннотации
Если предоставлен предлагаемый код, он отображается под аннотацией (в формате блока кода)

Шаг 5: Добавление аннотации Suggestion

Сценарий: Предоставить конкретное решение по изменению кода, которое ИИ должен применить

Введите описание предложения в поле ввода панели инструментов (опционально)
Кликните Add suggested code
В появившемся поле ввода кода введите предлагаемый код
Кликните кнопку Add Comment

Пример:

Описание предложения: Использовать async/await для упрощения цепочки Promise

Предлагаемый код:
async function fetchData() {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

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

Аннотация отображается под diff (синяя рамка)
Предлагаемый код отображается в формате блока кода с меткой «Suggested:»
В боковой панели показывается первая строка предлагаемого кода (с многоточием)

Шаг 6: Добавление аннотации Concern

Сценарий: Отметить потенциальную проблему или риск, обратить внимание ИИ

Примечание: В текущей версии UI Plannotator тип аннотации по умолчанию — Comment. Если нужно отметить Concern, можно явно указать это в тексте аннотации.

Введите описание замечания в поле ввода панели инструментов
Можно использовать метки Concern: или ⚠️ для явного указания, что это замечание
Кликните кнопку Add Comment

Пример:

Concern: Здесь отсутствует проверка на null, если user равен null, произойдёт ошибка во время выполнения

Предлагаю добавить:
if (!user) return null;

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

Аннотация отображается под diff
В боковой панели показывается содержимое аннотации

Шаг 7: Просмотр и управление аннотациями

Просмотр всех аннотаций в боковой панели:

Правая боковая панель показывает список всех аннотаций
Каждая аннотация отображает:
- Имя файла (последний компонент пути)
- Диапазон строк (например, L10 или L10-L15)
- Автор (при совместном ревью)
- Временная метка (например, 5m, 2h, 1d)
- Содержимое аннотации (максимум 2 строки)
- Превью предлагаемого кода (первая строка)

Клик по аннотации для перехода:

Кликните по аннотации в боковой панели
Diff viewer автоматически прокручивается к соответствующей позиции
Аннотация подсвечивается

Удаление аннотации:

Наведите курсор на аннотацию в боковой панели
Кликните кнопку × в правом верхнем углу
Аннотация удаляется, подсветка в diff исчезает

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

Боковая панель показывает количество аннотаций (например, Annotations: 3)
После клика по аннотации diff viewer плавно прокручивается к соответствующей строке
После удаления аннотации количество обновляется

Шаг 8: Экспорт отзыва

После завершения всех аннотаций кликните кнопку Send Feedback внизу страницы.

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

Браузер автоматически закрывается
В терминале отображается отзыв в формате Markdown
ИИ получает структурированный отзыв и может автоматически ответить

Формат экспортируемого Markdown:

markdown

# Code Review Feedback

## src/app/api/users.ts

### Line 10 (new)
Эту логику можно упростить, предлагаю использовать async/await

### Lines 15-20 (new)
**Suggested code:**
```typescript
async function fetchUserData() {
  const response = await fetch(url);
  return await response.json();
}

Line 25 (old)

Concern: Здесь отсутствует проверка на null, если user равен null, произойдёт ошибка во время выполнения


::: tip Копирование отзыва
Если нужно вручную скопировать содержимое отзыва, кликните кнопку **Copy Feedback** внизу боковой панели, чтобы скопировать отзыв в формате Markdown в буфер обмена.
:::

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

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

- [ ] Кликать по номеру строки или кнопке «+» при наведении для выбора строк кода в diff
- [ ] Добавлять аннотации Comment (общие комментарии)
- [ ] Добавлять аннотации Suggestion (с предлагаемым кодом)
- [ ] Добавлять аннотации Concern (отметка потенциальных проблем)
- [ ] Просматривать все аннотации в боковой панели и переходить к соответствующей позиции по клику
- [ ] Удалять ненужные аннотации
- [ ] Экспортировать отзыв в формате Markdown
- [ ] Копировать содержимое отзыва в буфер обмена

**Если какой-то шаг не удался**, см.:
- [Частые вопросы](../../faq/common-problems/)
- [Основы код-ревью](../code-review-basics/)
- [Устранение неполадок](../../faq/troubleshooting/)

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

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

**Причина**: Возможно, клик был по имени файла или номер строки не входит в диапазон diff.

**Решение**:
- Убедитесь, что кликаете по номеру строки diff (зелёные или красные строки)
- Для удалённых строк (красные) кликайте по номеру слева
- Для добавленных строк (зелёные) кликайте по номеру справа

**Частая ошибка 2**: После выбора нескольких строк аннотация отображается в неправильном месте

**Причина**: Неправильная сторона (old/new).

**Решение**:
- Проверьте, выбрали ли вы старый код (deletions) или новый код (additions)
- Аннотация отображается под последней строкой диапазона
- Если позиция неправильная, удалите аннотацию и добавьте заново

**Частая ошибка 3**: После добавления предлагаемого кода форматирование нарушено

**Причина**: Предлагаемый код может содержать специальные символы или проблемы с отступами.

**Решение**:
- В поле ввода предлагаемого кода убедитесь, что отступы правильные
- Используйте моноширинный шрифт для редактирования предлагаемого кода
- Для переноса строки используйте `Shift + Enter` вместо простого Enter

**Частая ошибка 4**: Новая аннотация не видна в боковой панели

**Причина**: Боковая панель могла не обновиться, или аннотация добавлена к другому файлу.

**Решение**:
- Переключитесь на другой файл и обратно
- Проверьте, добавлена ли аннотация к текущему просматриваемому файлу
- Обновите страницу браузера (незакоммиченные аннотации могут быть потеряны)

**Частая ошибка 5**: После экспорта отзыва ИИ не внёс предложенные изменения

**Причина**: ИИ мог неправильно понять намерение аннотации, или предложение невыполнимо.

**Решение**:
- Используйте более явные аннотации (Suggestion яснее, чем Comment)
- Добавьте комментарии в предлагаемый код с объяснением причин
- Если проблема сохраняется, отправьте отзыв повторно с изменённым содержимым аннотации

## Итоги урока

Аннотации кода — это ключевая функция код-ревью в Plannotator, позволяющая точно сообщать о проблемах в коде:

**Основные операции**:
1. **Запуск**: Выполните `/plannotator-review`, браузер автоматически откроет diff viewer
2. **Просмотр**: Изучите изменения кода (переключение между split/unified видами)
3. **Выбор**: Кликните по номеру строки или кнопке «+» при наведении для выбора диапазона кода
4. **Аннотирование**: Добавьте аннотации Comment/Suggestion/Concern
5. **Управление**: Просматривайте, переходите и удаляйте аннотации в боковой панели
6. **Экспорт**: Send Feedback — ИИ получает структурированный отзыв

**Типы аннотаций**:
- **Comment**: Общий комментарий, предложение без обязательности
- **Suggestion**: Явная рекомендация к изменению с предлагаемым кодом
- **Concern**: Отметка потенциальной проблемы или риска

**Лучшие практики**:
- При использовании Suggestion старайтесь предоставлять полный работающий код
- Для проблем производительности или безопасности используйте Concern
- Содержимое аннотации должно быть конкретным, избегайте размытых описаний (например, «это плохо»)
- Можно прикреплять изображения для пояснения (используя функцию аннотирования изображений)

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

> В следующем уроке мы изучим **[Переключение видов Diff](../code-review-diff-types/)**.
>
> Вы узнаете:
> - Как переключаться между разными типами diff (uncommitted/staged/last commit/branch)
> - Сценарии использования разных типов diff
> - Как быстро переключаться между различными типами diff

---

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

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

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

| Функция | Путь к файлу | Строки |
| --- | --- | --- |
| Определение типа CodeAnnotation | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L53-L56) | 53-56 |
| Интерфейс CodeAnnotation | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L55-L66) | 55-66 |
| Компонент DiffViewer | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L1-L349) | 1-349 |
| Компонент ReviewPanel | [`packages/review-editor/components/ReviewPanel.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/ReviewPanel.tsx#L1-L211) | 1-211 |
| Экспорт отзыва в Markdown | [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx#L86-L126) | 86-126 |
| Кнопка «+» при наведении | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L180-L199) | 180-199 |
| Панель инструментов аннотации | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L267-L344) | 267-344 |
| Рендеринг аннотации | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L140-L177) | 140-177 |

**Ключевые типы**:
- `CodeAnnotationType`: Тип аннотации кода ('comment' | 'suggestion' | 'concern') (`packages/ui/types.ts:53`)
- `CodeAnnotation`: Интерфейс аннотации кода (`packages/ui/types.ts:55-66`)
- `SelectedLineRange`: Выбранный диапазон кода (`packages/ui/types.ts:77-82`)

**Ключевые функции**:
- `exportReviewFeedback()`: Преобразование аннотаций в формат Markdown (`packages/review-editor/App.tsx:86`)
- `renderAnnotation()`: Рендеринг аннотации в diff (`packages/review-editor/components/DiffViewer.tsx:140`)
- `renderHoverUtility()`: Рендеринг кнопки «+» при наведении (`packages/review-editor/components/DiffViewer.tsx:180`)

**API-маршруты**:
- `POST /api/feedback`: Отправка отзыва ревью (`packages/server/review.ts`)
- `GET /api/diff`: Получение git diff (`packages/server/review.ts:111`)
- `POST /api/diff/switch`: Переключение типа diff (`packages/server/review.ts`)

**Бизнес-правила**:
- По умолчанию просматривается незакоммиченный diff (`git diff HEAD`) (`packages/server/review.ts:111`)
- Аннотация отображается под последней строкой диапазона (стиль GitHub) (`packages/review-editor/components/DiffViewer.tsx:81`)
- Поддержка прикрепления предлагаемого кода к аннотации (поле `suggestedCode`) (`packages/ui/types.ts:63`)

</details>

Добавление аннотаций кода: комментарии, предложения и замечания ​

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

С какими проблемами вы сталкиваетесь ​

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

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

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

Что такое аннотации кода ​

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

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

Comment vs Suggestion vs Concern ​

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

Шаг 1: Запуск код-ревью ​

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

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

Шаг 4: Добавление аннотации Comment ​

Шаг 5: Добавление аннотации Suggestion ​

Шаг 6: Добавление аннотации Concern ​

Шаг 7: Просмотр и управление аннотациями ​

Шаг 8: Экспорт отзыва ​

Line 25 (old) ​

Добавление аннотаций кода: комментарии, предложения и замечания

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

С какими проблемами вы сталкиваетесь

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

🎒 Подготовка

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

Что такое аннотации кода

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

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

Comment vs Suggestion vs Concern

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

Шаг 1: Запуск код-ревью

Шаг 2: Просмотр содержимого diff

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

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

Шаг 5: Добавление аннотации Suggestion

Шаг 6: Добавление аннотации Concern

Шаг 7: Просмотр и управление аннотациями

Шаг 8: Экспорт отзыва

Line 25 (old)