コードアノテーションの追加：行レベルのコメント、提案、懸念点

この章で学べること

✅ コードdiffに行レベルのアノテーション（comment/suggestion/concern）を追加する
✅ コード修正に対して提案コード（suggestedCode）を提供する
✅ 注意が必要なコード箇所（concern）をマークする
✅ すべてのアノテーションを確認・管理する（サイドバー）
✅ 3種類のアノテーションタイプの使用シナリオを理解する
✅ フィードバックをMarkdown形式でエクスポートする

現在の課題

課題1：コード変更をレビューする際、ターミナルでdiffを見て「3行目に問題がある」「XXXに変更すべき」と書くしかなく、位置が不正確。

課題2：コードに対してコメントしたいだけの場合（comment）、修正提案をしたい場合（suggestion）、深刻な問題で注意が必要な場合（concern）があるが、それらを区別するツールがない。

課題3：ある関数に修正提案をしたいが、コードスニペットをAIに渡す方法がわからない。

課題4：複数のアノテーションを追加した後、どこをレビューしたか忘れてしまい、全体像が把握できない。

Plannotatorでできること：

行番号をクリックするだけでコード範囲を選択、行単位で正確に指定
3種類のアノテーションタイプ（comment/suggestion/concern）がそれぞれ異なるシナリオに対応
提案コードを添付でき、AIが修正案を直接確認可能
サイドバーにすべてのアノテーションを一覧表示、ワンクリックでジャンプ

こんなときに使う

適した使用シナリオ：

/plannotator-reviewコマンド実行後にコード変更を確認する
特定のコード行にフィードバックを提供する必要がある
AIにコード修正提案を提供したい
潜在的な問題やリスクポイントをマークする必要がある

適さないシナリオ：

AIが生成した実装プランをレビューする（プランレビュー機能を使用）
diffを素早く確認するだけ（コードレビュー基礎機能を使用）

🎒 始める前の準備

前提条件：

✅ Plannotator CLIがインストール済み（詳細はクイックスタートを参照）
✅ コードレビュー基礎を習得済み（詳細はコードレビュー基礎を参照）
✅ ローカルにGitリポジトリがあり、未コミットの変更がある

トリガー方法：

OpenCodeまたはClaude Codeで/plannotator-reviewコマンドを実行

コアコンセプト

コードアノテーションとは

コードアノテーションはPlannotatorコードレビューの中核機能で、Git diffに行レベルのフィードバックを追加するために使用します。行番号をクリックしてコード範囲を選択することで、特定のコード行に対してコメント、提案、懸念点を正確に追加でき、アノテーションはdiffの下に表示されるため、AIがあなたのフィードバック意図を正確に理解できます。

なぜコードアノテーションが必要なのか？

コードレビューでは、特定のコード行にフィードバックを提供する必要があります。「5行目に問題がある」「XXXに変更すべき」とテキストで説明するだけでは、AIが自分でコードを探す必要があり、エラーが発生しやすくなります。Plannotatorでは行番号をクリックしてコード範囲を選択し、その位置に直接アノテーションを追加できます。アノテーションはdiffの下（GitHub風）に表示され、AIはあなたがどのコードに対して提案しているかを正確に把握できます。

ワークフロー

┌─────────────────┐
│  /plannotator-   │  コマンドをトリガー
│  review コマンド  │
└────────┬────────┘
         │
         │ git diffを実行
         ▼
┌─────────────────┐
│  Diff Viewer    │  ← コードdiffを表示
│  (split/unified) │
└────────┬────────┘
         │
         │ 行番号をクリック / Hover +
         ▼
┌─────────────────┐
│  コード範囲を選択 │
│  (lineStart-    │
│   lineEnd)      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  アノテーション追加 │  ← ツールバーがポップアップ
│  - Comment     │     コメント内容を入力
│  - Suggestion  │     オプション：提案コードを提供
│  - Concern     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  アノテーション表示 │  diffの下に表示
│  (GitHub風)     │  サイドバーに全アノテーション一覧
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  フィードバック   │  Send Feedback
│  エクスポート     │  AIが構造化フィードバックを受信
│  (Markdown)     │
└─────────────────┘

アノテーションタイプ

Plannotatorは3種類のコードアノテーションタイプをサポートしており、それぞれ異なる用途があります：

アノテーションタイプ	用途	典型的なシナリオ	提案コード
Comment	コードにコメントし、一般的なフィードバックを提供	「このロジックは簡略化できる」「変数名が不明瞭」	オプション
Suggestion	具体的なコード修正提案を提供	「forループの代わりにmapを使用すべき」「Promise.thenの代わりにawaitを使用」	推奨
Concern	潜在的な問題やリスクポイントをマーク	「このSQLクエリにはパフォーマンス問題がある可能性」「エラーハンドリングが不足」	オプション

アノテーションタイプの選択ガイド

Comment：「提案するが強制しない」場合に使用。コードスタイル、最適化の方向性など
Suggestion：「修正を強く推奨」し、明確な修正案がある場合に使用
Concern：「必ず注意すべき問題」に使用。バグ、パフォーマンスリスク、セキュリティ脆弱性など

Comment vs Suggestion vs Concern

シナリオ	選択タイプ	例文
コードは動作するが、最適化の余地がある	Comment	「この部分はasync/awaitで簡略化できる」
コードに明確な改善案がある	Suggestion	「スプレッド演算子の代わりに`Array.from()`を使用すべき」（コード付き）
バグや深刻な問題を発見	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アノテーションを追加

シナリオ：明確なコード修正案を提供し、AIに直接採用してほしい

ツールバーのテキスト欄に提案説明を入力（オプション）
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アノテーションを追加

シナリオ：潜在的な問題やリスクポイントをマークし、AIに注意を促す

注意：現在のPlannotator UIでは、アノテーションタイプはデフォルトで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形式のフィードバック内容が表示
AIが構造化フィードバックを受信し、自動的に応答可能

エクスポートされる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で行番号をクリックまたはHover「+」ボタンでコード行を選択
- [ ] Commentアノテーションを追加（一般的なコメント）
- [ ] Suggestionアノテーションを追加（提案コード付き）
- [ ] Concernアノテーションを追加（潜在的な問題をマーク）
- [ ] サイドバーですべてのアノテーションを確認し、クリックで対応位置にジャンプ
- [ ] 不要なアノテーションを削除
- [ ] フィードバックをMarkdown形式でエクスポート
- [ ] フィードバック内容をクリップボードにコピー

**いずれかのステップで失敗した場合**は、以下を参照：
- [よくある質問](../../faq/common-problems/)
- [コードレビュー基礎](../code-review-basics/)
- [トラブルシューティング](../../faq/troubleshooting/)

## よくあるトラブル

**よくあるエラー1**：行番号をクリックしてもツールバーがポップアップしない

**原因**：ファイル名をクリックしたか、行番号がdiff範囲外の可能性。

**解決方法**：
- diff行の行番号（緑または赤の行）をクリックしていることを確認
- 削除行（赤）の場合、左側の行番号をクリック
- 追加行（緑）の場合、右側の行番号をクリック

**よくあるエラー2**：複数行を選択後、アノテーションが間違った位置に表示される

**原因**：side（old/new）が正しくない。

**解決方法**：
- 選択したのが旧コード（deletions）か新コード（additions）かを確認
- アノテーションは範囲の最後の行の下に表示される
- 位置が間違っている場合、アノテーションを削除して再追加

**よくあるエラー3**：提案コードを追加後、コードフォーマットが崩れる

**原因**：提案コードに特殊文字やインデント問題が含まれている可能性。

**解決方法**：
- 提案コード入力欄でインデントが正しいことを確認
- 等幅フォントで提案コードを編集
- 改行がある場合、直接Enterではなく`Shift + Enter`を使用

**よくあるエラー4**：サイドバーに新しく追加したアノテーションが表示されない

**原因**：サイドバーが更新されていないか、アノテーションが別のファイルに追加された可能性。

**解決方法**：
- ファイルを切り替えてから戻る
- アノテーションが現在表示中のファイルに追加されているか確認
- ブラウザページを更新（未送信のアノテーションが失われる可能性あり）

**よくあるエラー5**：フィードバックをエクスポート後、AIが提案通りに修正しない

**原因**：AIがアノテーションの意図を正しく理解していないか、提案が実行不可能な可能性。

**解決方法**：
- より明確なアノテーションを使用（SuggestionはCommentより明確）
- 提案コードに理由を説明するコメントを追加
- 問題が続く場合、再度フィードバックを送信し、アノテーション内容を調整

## この章のまとめ

コード��ノテーションはPlannotatorコードレビューの中核機能で、コードの問題を正確にフィードバックできます：

**コア操作**：
1. **トリガー**：`/plannotator-review`を実行、ブラウザが自動的にdiff viewerを開く
2. **確認**：コード変更を確認（split/unifiedビュー切り替え）
3. **選択**：行番号をクリックまたはHover「+」ボタンでコード範囲を選択
4. **アノテーション**：Comment/Suggestion/Concernアノテーションを追加
5. **管理**：サイドバーで確認、ジャンプ、アノテーションを削除
6. **エクスポート**：Send Feedback、AIが構造化フィードバックを受信

**アノテーションタイプ**：
- **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  |
| Hover「+」ボタン     | [`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()`：Hover「+」ボタンをレンダリング（`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>

5分でクイックスタート

AIプランとコードのレビュー

チームコラボ+ノート保存

問題が発生したら

コードアノテーションの追加：行レベルのコメント、提案、懸念点

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

コードアノテーションとは

ワークフロー

アノテーションタイプ

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) ​

コードアノテーションの追加：行レベルのコメント、提案、懸念点

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

コードアノテーションとは

ワークフロー

アノテーションタイプ

Comment vs Suggestion vs Concern

ステップバイステップ

ステップ1：コードレビューをトリガー

ステップ2：diff内容を確認

ステップ3：コード行を選択してアノテーションを追加

ステップ4：Commentアノテーションを追加

ステップ5：Suggestionアノテーションを追加

ステップ6：Concernアノテーションを追加

ステップ7：アノテーションの確認と管理

ステップ8：フィードバックをエクスポート

Line 25 (old)