プランアノテーションの追加：4種類のアノテーションタイプをマスター

この章で学べること

✅ プランテキストを選択し、4種類のアノテーション（削除、置換、挿入、コメント）を追加する
✅ type-to-commentショートカットで直接コメントを入力する
✅ アノテーションに画像（参考画像、スクリーンショットなど）を添付する
✅ 各アノテーションタイプの意味と使用シナリオを理解する
✅ アノテーションをエクスポートした際のMarkdown形式を確認する

現在の課題

課題1：ある段落を削除したいが、テキストを選択した後どのボタンをクリックすればいいかわからない。

課題2：コードの一部を置換したいが、ツールバーには「削除」と「コメント」しかなく、「置換」オプションがない。

課題3：複数行のテキストを選択して直接コメントを入力したいが、毎回「Comment」ボタンをクリックする必要があり、効率が悪い。

課題4：あるコードに参考画像を添付したいが、画像のアップロード方法がわからない。

Plannotatorでできること：

わかりやすいボタンアイコンで、削除、置換、挿入、コメントの違いが一目瞭然
type-to-commentショートカットで、ボタンをクリックせずに直接入力可能
アノテーションに画像添付をサポートし、参考画像の追加が簡単
アノテーションを構造化されたMarkdownに自動変換し、AIが正確に理解

こんなときに使う

適した使用シナリオ：

AIが生成した実装プランをレビューし、正確な修正フィードバックが必要
ある内容が不要（削除）
ある内容を別の書き方に変更したい（置換）
ある内容の後に補足説明を追加したい（挿入）
ある内容に質問や提案がある（コメント）

適さないシナリオ：

プラン全体を承認または却下するだけ（アノテーション不要、直接決定すればOK）
すでにコード変更をレビュー中（コードレビュー機能を使用）

🎒 始める前の準備

前提条件：

✅ プランレビューの基本チュートリアルを完了済み
✅ Plannotatorプランレビュー画面の起動方法を理解している

この章の前提：

Plannotatorプランレビューページを開いている
ページにAIが生成したMarkdownプランが表示されている

コアコンセプト

アノテーションタイプの詳細

Plannotatorは4種類のプランアノテーションタイプ（およびグローバルコメント）をサポートしています：

アノテーションタイプ	アイコン	用途	内容入力の必要性
削除 (DELETION)	🗑️	この内容をプランから削除すべきとマーク	❌ 不要
コメント (COMMENT)	💬	選択した内容に質問や提案を追加	✅ コメント入力が必要
置換 (REPLACEMENT)	コメント経由で実現	選択した内容を新しい内容に置換	✅ 新しい内容の入力が必要
挿入 (INSERTION)	コメント経由で実現	選択した内容の後に新しい内容を挿入	✅ 新しい内容の入力が必要
グローバルコメント (GLOBAL_COMMENT)	ページ下部の入力欄	プラン全体へのフィードバック	✅ コメント入力が必要

なぜ置換と挿入に独立したボタンがないのか？

ソースコードの実装を見ると、置換と挿入は本質的に特殊なコメントタイプです（packages/ui/utils/parser.ts:287-296）：

置換：コメント内容が置換後の新しいテキストになる
挿入：コメント内容が挿入する新しいテキストになる

どちらもコメント (COMMENT) ボタンで作成し、違いは意図の説明方法にあります。

ツールバーのワークフロー

テキスト選択 → ツールバー表示（メニューステップ）
                  │
                  ├── Deleteをクリック → 削除アノテーションを即座に作成
                  ├── Commentをクリック → 入力ステップへ → 内容入力 → 保存
                  └── 文字を直接入力 → type-to-comment → 自動的に入力ステップへ

2つのステップの違い：

メニューステップ：操作タイプを選択（削除、コメント、キャンセル）
入力ステップ：コメント内容を入力または画像を添付（コメント/置換から遷移）

type-to-commentショートカット

効率を上げるための重要な機能です。テキストを選択した後、ボタンをクリックせずに直接入力を開始すると、ツールバーが自動的に：

「コメント」モードに切り替え
入力した最初の文字を入力欄に配置
カーソルを入力欄の末尾に自動配置

ソースコードの実装場所：packages/ui/components/AnnotationToolbar.tsx:127-147

ステップバイステップ

ステップ1：プランレビューを起動

なぜアノテーション追加の練習には実際のプランが必要です。

操作

Claude CodeまたはOpenCodeでプランレビューをトリガー：

bash

# Claude Codeの例：AIにプランを生成させると、ExitPlanModeが呼び出される
"ユーザー認証機能の実装プランを作成してください"

# AIがプランを完成させると、Plannotatorが自動的にブラウザで開く

期待される結果：

ブラウザがプランレビューページを開く
ページにMarkdown形式の��装プランが表示される

ステップ2：削除アノテーションを追加

なぜ削除アノテーションは、最終プランに含めたくない内容をマークするために使用します。

操作

プラン内で不要な段落を見つける（例：関係のない機能説明）
マウスでテキストを選択
ツールバーが自動的に表示されるので、削除ボタン（🗑️） をクリック

期待される結果：

選択したテキストが削除スタイルで表示される（通常は取り消し線または赤い背景）
ツールバーが自動的に閉じる

削除アノテーションの特徴

削除アノテーションは内容の入力が不要です。削除ボタンをクリックすると、アノテーションが即座に作成されます。

ステップ3：type-to-commentでコメントを追加

なぜコメントは最もよく使うアノテーションタイプで、type-to-commentを使えばボタンクリックを1回省略できます。

操作

プラン内でテキストを選択（例：関数名や説明文）
ボタンをクリックせずに、直接入力を開始
コメント内容を入力（例：「この関数名はわかりにくい」）
Enterキーで保存、またはSaveボタンをクリック

期待される結果：

ツールバーが自動的に入力欄モードに切り替わる
入力した最初の文字がすでに入力欄に表示されている
カーソルが入力欄の末尾に自動配置される
Enterを押すと、選択したテキストがコメントスタイルで表示される（通常は黄色い背景）

type-to-commentのショートカットキー

Enter：アノテーションを保存（入力欄に内容がある場合）
Shift + Enter：改行（複数行のコメントを入力する場合）
Escape：入力をキャンセルし、メニューステップに戻る

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

なぜ置換アノテーションは選択した内容を新しい内容に置き換えるために使用し、AIがアノテーションに基づいてプランを修正します。

操作

プラン内でテキストを選択（例：「JWTトークンで認証を行う」）
type-to-commentを使用するか、コメントボタンをクリック
入力欄に新しい内容を入力（例：「セッションCookieで認証を行う」）
Enterで保存

期待される結果：

選択したテキストがコメントスタイルで表示される
アノテーションサイドバーにコメント内容が表示される

エクスポート後の形式（packages/ui/utils/parser.ts:292-296）：

markdown

## 1. Change this

**From:**

JWTトークンで認証を行う


**To:**

セッションCookieで認証を行う

置換と削除の違い

削除：内容を直接削除、理由の説明は不要
置換：古い内容を新しい内容に置き換え、新しい内容の指定が必要

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

なぜ挿入アノテーションは、選択した内容の後に補足説明やコードスニペットを追加するために使用します。

操作

プラン内でテキストを選択（例：関数シグネチャの末尾）
type-to-commentを使用するか、コメントボタンをクリック
入力欄に挿入する内容を入力（例：「、認証失敗時の処理が必要」）
Enterで保存

期待される結果：

選択したテキストがコメントスタイルで表示される
アノテーションサイドバーにコメントが表示される

エクスポート後の形式（packages/ui/utils/parser.ts:287-290）：

markdown

## 1. Add this

、認証失敗時の処理が必要

ステップ6：アノテーションに画像を添付

なぜテキストだけでは説明が不十分な場合、参考画像やスクリーンショットを添付する必要があります。

操作

任意のテキストを選択し、入力ステップに入る（コメントボタンをクリックまたはtype-to-comment）
ツールバーの入力欄の横にある添付ボタン（📎） をクリック
アップロードする画像を選択（PNG、JPEG、WebP形式をサポート）
コメント内容の入力を続けることも可能
Enterで保存

期待される結果：

画像のサムネイルが入力欄に表示される
保存後、画像がアノテーションサイドバーに表示される

画像の保存場所

アップロードした画像はローカルの/tmp/plannotatorディレクトリに保存されます（ソースコードの場所：packages/server/index.ts:163）。一時ファイルをクリーンアップすると、画像が失われます。

ステップ7：グローバルコメントを追加

なぜプラン全体へのフィードバック（特定のテキストに対するものではない）がある場合、グローバルコメントを使用します。

操作

ページ下部の入力欄を見つける（ラベルは「Add a general comment about the plan...」など）
コメント内容を入力
Enterで保存または送信ボタンをクリック

期待される結果：

コメントがページ下部のグローバルコメントエリアに表示される
コメントは独立したカードとして表示され、テキストブロックには関連付けられない

グローバルコメント vs テキストコメント

グローバルコメント：プラン全体へのフィードバック、特定のテキストに関連付けない（例：「プラン全体でパフォーマンスの考慮が欠けている」）
テキストコメント：特定のテキストへのフィードバック、対応するテキストがハイライト表示される

チェックポイント ✅

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

[ ] 少なくとも1つの削除アノテーションを追加できた
[ ] type-to-commentでコメントを追加できた
[ ] 置換と挿入アノテーションを追加できた
[ ] アノテーションに画像を添付できた
[ ] グローバルコメントを追加できた
[ ] 右側のサイドバーにすべてのアノテーションリストが表示されている

よくあるトラブル

トラブル1：「置換」ボタンが見つからない

誤った操作：

テキストを選択した後、ツールバーにはDeleteとCommentしかなく、ReplaceやInsertボタンがない

正しい方法：

置換と挿入はコメント (COMMENT) ボタンで実現する
コメント内容で意図（置換または挿入）を説明する
AIがコメント内容から意図を理解する

トラブル2：type-to-commentが動作しない

考えられる原因：

テキストを選択していない
先にボタンをクリックしたため、ツールバーがすでに入力ステップに入っている
特殊キー（Ctrl、Alt、Escapeなど）を入力した

正しい方法：

まずテキストを選択し、ツールバーがメニューステップ（Delete、Commentボタンがある状態）であることを確認
通常の文字（アルファベット、数字、句読点）を直接入力
ファンクションキーは押さない

トラブル3：アップロードした画像が見つからない

考えられる原因：

画像は/tmp/plannotatorディレクトリに保存される
システムが一時ファイルをクリーンアップした

正しい方法：

画像を長期保存する必要がある場合は、プロジェクトディレクトリにコピーすることを推奨
アノテーションをエクスポートする際、画像パスは絶対パスなので、他のツールからアクセスできることを確認

トラブル4：`Enter`で改行しようとしたらアノテーションが保存された

誤った操作：

入力欄で改行しようとして直接Enterを押したら、アノテーションが保存された

正しい方法：

改行にはShift + Enterを使用
Enterキーはアノテーション保存専用

この章のまとめ

4種類のアノテーションタイプ：

削除 (DELETION)：プランに含めたくない内容をマーク
置換 (REPLACEMENT)：選択��た内容を新しい内容に置き換え（コメント経由で実現）
挿入 (INSERTION)：選択した内容の後に内容を補足（コメント経由で実現）
コメント (COMMENT)：選択した内容に質問や提案を追加
グローバルコメント (GLOBAL_COMMENT)：プラン全体へのフィードバック

主な操作：

選択 → ツールバー表示 → 操作タイプを選択
type-to-comment：文字を直接入力すると、自動的にコメントモードに入る
Shift + Enter：改行、Enter：保存
添付ボタン：アノテーションに画像をアップロード

アノテーションのエクスポート形式：

削除：## Remove this + 元のテキスト
挿入：## Add this + 新しいテキスト
置換：## Change this + From/To比較
コメント：## Feedback on: "..." + コメント内容

次の章の予告

次の章では**画像アノテーションの追加**を学びます。
学べる内容：
プランレビューで画像を添付する方法
ペン、矢印、円形ツールでアノテーションを追加
アノテーション付き画像を参考フィードバックとして使用

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日：2026-01-24

機能	ファイルパス	行番号
アノテーションタイプの列挙定義	`packages/ui/types.ts`	1-7
Annotationインターフェース	`packages/ui/types.ts`	11-33
アノテー��ョンツールバーコンポーネント	`packages/ui/components/AnnotationToolbar.tsx`	29-272
---	---	---
アノテーションエクスポートのフォーマット	`packages/ui/utils/parser.ts`	246-323
MarkdownをBlocksにパース	`packages/ui/utils/parser.ts`	70-244
Viewerコンポーネント（テキスト選択処理）	`packages/ui/components/Viewer.tsx`	66-350

主要な定数：

AnnotationType.DELETION = 'DELETION'：削除アノテーションタイプ
AnnotationType.INSERTION = 'INSERTION'：挿入アノテーションタイプ
AnnotationType.REPLACEMENT = 'REPLACEMENT'：置換アノテーションタイプ
AnnotationType.COMMENT = 'COMMENT'：コメントアノテーションタイプ
AnnotationType.GLOBAL_COMMENT = 'GLOBAL_COMMENT'：グローバルコメントタイプ

主要な関数：

exportDiff(blocks, annotations)：アノテーションをMarkdown形式にエクスポート、From/To比較を含む
parseMarkdownToBlocks(markdown)：Markdownを線形Blockの配列にパース
createAnnotationFromSource()：テキスト選択からAnnotationオブジェクトを作成

5分でクイックスタート

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

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

問題が発生したら

プランアノテーションの追加：4種類のアノテーションタイプをマスター

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

アノテーションタイプの詳細

ツールバーのワークフロー

type-to-commentショートカット

ステップバイステップ

ステップ1：プランレビューを起動

ステップ2：削除アノテーションを追加

ステップ3：type-to-commentでコメントを追加

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

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

ステップ6：アノテーションに画像を添付

ステップ7：グローバルコメントを追加

チェックポイント ✅

よくあるトラブル

トラブル1：「置換」ボタンが見つからない

トラブル2：type-to-commentが動作しない

トラブル3：アップロードした画像が見つからない

トラブル4：`Enter`で改行しようとしたらアノテーションが保存された

この章のまとめ

次の章の予告

付録：ソースコード参照

プランアノテーションの追加：4種類のアノテーションタイプをマスター ​

この章で学べること ​

現在の課題 ​

こんなときに使う ​

🎒 始める前の準備 ​

コアコンセプト ​

アノテーションタイプの詳細 ​

ツールバーのワークフロー ​

type-to-commentショートカット ​

ステップバイステップ ​

ステップ1：プランレビューを起動 ​

ステップ2：削除アノテーションを追加 ​

ステップ3：type-to-commentでコメントを追加 ​

ステップ4：置換アノテーションを追加 ​

ステップ5：挿入アノテーションを追加 ​

ステップ6：アノテーションに画像を添付 ​

ステップ7：グローバルコメントを追加 ​

チェックポイント ✅ ​

よくあるトラブル ​

トラブル1：「置換」ボタンが見つからない ​

トラブル2：type-to-commentが動作しない ​

トラブル3：アップロードした画像が見つからない ​

トラブル4：Enterで改行しようとしたらアノテーションが保存された ​

この章のまとめ ​

次の章の予告 ​

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

プランアノテーションの追加：4種類のアノテーションタイプをマスター

この章で学べること

現在の課題

こんなときに使う

🎒 始める前の準備

コアコンセプト

アノテーションタイプの詳細

ツールバーのワークフロー

type-to-commentショートカット

ステップバイステップ

ステップ1：プランレビューを起動

ステップ2：削除アノテーションを追加

ステップ3：type-to-commentでコメントを追加

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

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

ステップ6：アノテーションに画像を添付

ステップ7：グローバルコメントを追加

チェックポイント ✅

よくあるトラブル

トラブル1：「置換」ボタンが見つからない

トラブル2：type-to-commentが動作しない

トラブル3：アップロードした画像が見つからない

トラブル4：`Enter`で改行しようとしたらアノテーションが保存された

この章のまとめ

次の章の予告

付録：ソースコード参照