コードレビュー基礎：/plannotator-reviewでGit Diffをレビュー

この章で学べること

✅ /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の2つのビューをサポート
行番号をクリックするだけでコード範囲を選択し、問題箇所を正確にマーク
行レベルのアノテーション（comment/suggestion/concern）を追加、提案コードも添付可能
ワンクリックでdiffタイプを切り替え（uncommitted、staged、last commit、branch）
アノテーションが自動的にMarkdownに変換され、Agentがフィードバックを正確に理解

こんなときに使う

適した使用シナリオ：

Agentがコード修正を完了し、変更内容をレビューする必要がある
コードをコミットする前に、自分の変更を全体的にチェックしたい
チームで協力する際、コードの問題を構造化してフィードバックする必要がある
複数のdiffタイプを切り替えたい（未コミット vs ステージ済み vs 前回のコミット）

適さないシナリオ：

AI生成の実装プランをレビューする（プランレビュー機能を使用）
ターミナルで直接git diffを使用する（ビジュアルインターフェースが不要）

🎒 始める前の準備

前提条件：

✅ Plannotator CLIをインストール済み（詳細はクイックスタートを参照）
✅ Claude CodeまたはOpenCodeプラグインを設定済み（対応するインストールガイドを参照）
✅ 現在のディレクトリがGitリポジトリ内にある

トリガー方法：

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

コアコンセプト

コードレビューとは

コードレビューはPlannotatorが提供するビジュアルGit Diffレビューツールで、ブラウザでコード変更を確認し、行レベルのアノテーションを追加できます。

なぜコードレビューが必要？

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は3種類のコードアノテーションタイプをサポートしています：

アノテーションタイプ	用途	UI表示
Comment	コード行にコメント、質問や説明を提示	紫/青の枠線マーク
Suggestion	具体的なコード修正提案を提供	緑の枠線マーク、提案コードブロック付き
Concern	注意が必要な潜在的問題をマーク	黄/オレンジの枠線マーク

アノテーションタイプの違い

Comment：質問、説明、一般的なフィードバックに使用
Suggestion：具体的なコード修正案を提供（提案コード付き）
Concern：修正が必要な問題や潜在的リスクをマーク

Diffタイプ

Diffタイプ	Gitコマンド	説明
Uncommitted	`git diff HEAD`	未コミットの変更（デフォルト）
Staged	`git diff --staged`	ステージ済みの変更
Unstaged	`git diff`	未ステージの変更
Last commit	`git diff HEAD~1..HEAD`	前回のコミット内容
Branch	`git diff main..HEAD`	現在の��ランチとデフォルトブランチの比較

ステップバイステップ

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

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

ユーザー：/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：ステージ済みの変更
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`で現在の状態を確認

## この章のまとめ

コードレビューはPlannotatorが提供するビジュアルGit Diffレビューツールです：

**コア操作**：
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**：ステージ済みの変更
- **Unstaged**：未ステージの変更
- **Last commit**：前回のコミット内容
- **Branch**：現在のブランチとデフォルトブランチの比較

## 次の章の予告

> 次の章では**[コードアノテーションの追加](../code-review-annotations/)**を学びます。
>
> 学べる内容：
> - Comment、Suggestion、Concernアノテーションの正確な使い方
> - 提案コードの追加とフォーマット表示方法
> - アノテーションの編集と削除方法
> - アノテーションのベストプラクティスとよくあるシナリオ
> - side-by-sideビューでold/new側を選択する方法

---

## 付録：ソースコード参照

<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`）
- vs main diffへの切り替えをサポート（`packages/server/git.ts:131`）
- フィードバックをMarkdown形式にフォーマット（`packages/review-editor/App.tsx:86`）
- 承認時に「LGTM」テキストを送信（`packages/review-editor/App.tsx:430`）

</details>

5分でクイックスタート

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

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

問題が発生したら

コードレビュー基礎：/plannotator-reviewでGit Diffをレビュー

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

コードレビューとは

ワークフロー

ビューモード

アノテーションタイプ

Diffタイプ

ステップバイステップ

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

ステップ2：ファイル一覧を確認

ステップ3：ビューモードを切り替え

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

ステップ5：Diffタイプを切り替え

ステップ6：フィードバックをAgentに送信

ステップ7：フィードバック内容を確認（オプション）

src/api/routes.ts

Line 10 (new)

コードレビュー基礎：/plannotator-reviewでGit Diffをレビュー ​

この章で学べること ​

現在の課題 ​

こんなときに使う ​

🎒 始める前の準備 ​

コアコンセプト ​

コードレビューとは ​

ワークフロー ​

ビューモード ​

アノテーションタイプ ​

Diffタイプ ​

ステップバイステップ ​

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

ステップ2：ファイル一覧を確認 ​

ステップ3：ビューモードを切り替え ​

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

ステップ5：Diffタイプを切り替え ​

ステップ6：フィードバックをAgentに送信 ​

ステップ7：フィードバック内容を確認（オプション） ​

src/api/routes.ts ​

Line 10 (new) ​

コードレビュー基礎：/plannotator-reviewでGit Diffをレビュー

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

コードレビューとは

ワークフロー

ビューモード

アノテーションタイプ

Diffタイプ

ステップバイステップ

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

ステップ2：ファイル一覧を確認

ステップ3：ビューモードを切り替え

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

ステップ5：Diffタイプを切り替え

ステップ6：フィードバックをAgentに送信

ステップ7：フィードバック内容を確認（オプション）

src/api/routes.ts

Line 10 (new)