クイックスタート：5分で始めるPlannotator

この章で学べること

✅ Plannotatorのコア機能と使用シナリオを理解する
✅ 5分以内にPlannotatorのインストールを完了する
✅ Claude CodeまたはOpenCodeとの連携を設定する
✅ 初めてのプランレビューとコードレビューを実行する

現在の課題

Plannotatorは、Claude CodeとOpenCode向けに設計されたインタラクティブなレビューツールです。以下の課題を解決します：

課題1：AIが生成した実装プランをターミナルで読むと、テキスト量が多く構造が不明瞭で、レビューが大変。

課題2：AIにフィードバックを伝えたいとき、「3段落目を削除」「この関数を修正」などテキストで説明するしかなく、コミュニケーションコストが高い。

課題3：コードレビュー時に複数のターミナルやIDEを開いて切り替える必要があり、集中しにくい。

課題4：チームメンバーがレビューに参加したいが、プラン内容の共��方法がわからない。

Plannotatorでできること：

ビジュアルUIでターミナル閲覧を置き換え、構造を明確化
テキストを選択するだけでアノテーション（削除、置換、コメント）を追加し、正確なフィードバックが可能
Git diffのビジュアルレビュー、行レベルのアノテーションをサポート
URL共有機能でバックエンド不要のチームコラボレーション

こんなときに使う

適した使用シナリオ：

Claude CodeまたはOpenCodeでAI支援開発を行っている
AIが生成した実装プランをレビューする必要がある
コード変更を審査する必要がある
チームメンバーとプランやコードレビュー結果を共有する必要がある

適さないシナリオ：

純粋に手動でコードを書いている（AI生成プランを使用しない）
すでに完全なコードレビューフローがある（GitHub PRなど）
ビジュアルレビューツールが不要

コアコンセプト

Plannotatorとは

Plannotatorは、AI Coding Agent（Claude Code、OpenCode）向けに設計されたインタラクティブなレビューツールで、主に2つの機能を提供します：

プランレビュー：AIが生成した実装プランをビジュアルでレビューし、アノテーションの追加、承認または却下をサポート
コードレビュー：Git diffをビジュアルでレビューし、行レベルのアノテーションと複数のビューモードをサポート

動作原理

┌─────────────────┐
│  AI Agent      │
│  (プラン生成)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Plannotator   │  ← ローカルHTTPサーバー
│  (ビジュアルUI) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  ブラウザ       │
│  (ユーザーレビュー) │
└─────────────────┘

コアフロー：

AI Agentがプランまたはコード変更を完了
Plannotatorがローカルでサーバーを起動し、ブラウザを開く
ユーザーがブラウザでプラン/コードを確認し、アノテーションを追加
ユーザーが承認または却下し、PlannotatorがAI Agentに決定を返す
AI Agentがフィードバックに基づいて実装を続行または修正

セキュリティ

すべてのデータはローカルで処理され、クラウドにアップロードされません：

プラン内容、コードdiff、アノテーションはすべてローカルマシンに保存
ロー��ルHTTPサーバーはランダムポート（または固定ポート）を使用
URL共有機能はデータをURLハッシュに圧縮して実現、バックエンド不要

🎒 始める前の準備

システム要件：

OS：macOS / Linux / Windows / WSL
ランタイム：Bun（インストールスクリプトが自動処理）
AI環境：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を自動的にダウンロードしてシステムパスに追加し、バージョン番号（例："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を開く
AIが生成したプラン内容が表示される
プランテキストを選択してアノテーション（削除、置換、コメント）を追加できる
下部に「Approve」と「Request Changes」ボタンがある

操作：

ブラウザでプランを確認
プランに問題がなければ、Approveをクリック → AIが実装を続行
修正が必要な場合、変更したいテキストを選択し、Delete、Replace、またはCommentをクリック → Request Changesをクリック

期待される結果：クリック後、ブラウザが自動的に閉じ、Claude Codeがあなたの決定を受け取って実行を続けます。

ステップ5：初めてのコードレビュー

プロジェクトディレクトリで実行：

bash

/plannotator-review

期待される結果：

ブラウザがコードレビューページを開く
Git diff（デフォルトは未コミットの変更）が表示される
左側にファイルツリー、右側にdiff viewerがある
行番号をクリックしてコード範囲を選択し、アノテーションを追加できる

操作：

diff viewerでコード変更を確認
行番号をクリックしてレビューするコードを選択
右側のパネルでアノテーション（comment/suggestion/concern）を追加
Send Feedbackをクリックしてagentに送信、またはLGTMをクリックして承認

期待される結果：Send Feedbackをクリックすると、ブラウザが閉じ、ター��ナルにフォーマットされたフィードバック内容が出力され、agentが自動的に処理します。

チェックポイント ✅

上記のステップを完了すると、以下ができるようになります：

[ ] インストールスクリプトが "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によりプランレビューとコードレビューの効率を向上させます：

コア機能：

プランレビュー：AIが生成したプランをビジュアルでレビュー、正確なアノテーションをサポート
コードレビュー：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分でクイックスタート

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

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

問題が発生したら

クイックスタート：5分で始めるPlannotator

この章で学べること

現在の課題

こんなときに使う

コアコンセプト

Plannotatorとは

動作原理

セキュリティ

🎒 始める前の準備

ステップバイステップ

ステップ1：Plannotator CLIのインストール

ステップ2：Claude Codeの設定（オプション）

ステップ3：OpenCodeの設定（オプション）

ステップ4：初めてのプランレビュー（Claude Codeの例）

ステップ5：初めてのコードレビュー

チェックポイント ✅

よくあるトラブル

この章のまとめ

次の章の予告

付録：ソースコード参照

クイックスタート：5分で始めるPlannotator ​

この章で学べること ​

現在の課題 ​

こんなときに使う ​

コアコンセプト ​

Plannotatorとは ​

動作原理 ​

セキュリティ ​

🎒 始める前の準備 ​

ステップバイステップ ​

ステップ1：Plannotator CLIのインストール ​

ステップ2：Claude Codeの設定（オプション） ​

ステップ3：OpenCodeの設定（オプション） ​

ステップ4：初めてのプランレビュー（Claude Codeの例） ​

ステップ5：初めてのコードレビュー ​

チェックポイント ✅ ​

よくあるトラブル ​

この章のまとめ ​

次の章の予告 ​

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

クイックスタート：5分で始めるPlannotator

この章で学べること

現在の課題

こんなときに使う

コアコンセプト

Plannotatorとは

動作原理

セキュリティ

🎒 始める前の準備

ステップバイステップ

ステップ1：Plannotator CLIのインストール

ステップ2：Claude Codeの設定（オプション）

ステップ3：OpenCodeの設定（オプション）

ステップ4：初めてのプランレビュー（Claude Codeの例）

ステップ5：初めてのコードレビュー

チェックポイント ✅

よくあるトラブル

この章のまとめ

次の章の予告

付録：ソースコード参照