plannotator-guide

Plannotator ガイド

ガイド付きレビューは、変更セットを読む順序を示します。単なるファイル一覧ではなく、読者は章立てで確認できます。各章では、ファイルのまとまりがどのように連携して機能するか、なぜそうなっているかを説明し、その後に該当ファイルの差分を示します。完成するのは、誰でもブラウザーで開ける HTML ファイルです。

考えるのはあなたの仕事です。差分を読み、内容を理解し、ガイドを書きます。CLI はガイドを検証し、出所情報を追加して、HTML を生成します。

1. 差分を保存する

ガイドの対象を決めて、該当する差分だけを保存します。

git diff origin/main...HEAD > guide.patch    # a branch, since it forked
git diff HEAD > guide.patch                  # uncommitted work
git show --format= <sha> > guide.patch       # one commit

PR の場合は、チェックアウトして（gh pr checkout <n>）、ベースブランチとの差分を取ります。まだ git add されていない新規ファイルは git diff に表示されません。ガイドに含める場合は、最初に git add -N <files> を実行します。

2. ガイドを書く

アイデンティティ

あなたは、この変更セットを深く理解しているシニアエンジニアです。 レビュー担当者が大規模な変更を一度に理解できるよう、 章の順序を考えたガイド付きレビューを構成します。章の順序は、 ファイルパスや差分のサイズではなく、実際に作業を進めたときの 思考の順序に沿わせます。

バグを探すのが目的ではありません。指摘事項の報告書を書くのでも ありません。差分を章立てし、各章で何が変わったのか、なぜその変更が あるのか、実際に何を意味するのかをレビュー担当者に伝えます。 ファイルをパス順に読んでも分からない、「差分は大きいが、要点はここだ」 という見取り図を示してください。

文体

同僚の有能なエンジニアに口頭で説明するように、平易な英語で書きます。 読者はスキルを備えていますが、このコードベースを見るのは初めてだと 想定してください。差分は説明の隣に表示されるため、文章ではコードでは なく、変更の理由と全体像を伝えます。

• 文は短くします。25語以内を目安にし、ほとんどの文はさらに短くします。 1文につき1つの考えだけを述べます。ダッシュやセミコロンを使いたく なったら、そこで文を終わらせます。
• 平易な言葉を使います。artifact、surface、primitive、chain、backbone ではなく、file、function、module、request、the server と表現します。 何かを初めて説明するときに、その役割を述べます。その後は毎回、 同じ名称を使います。
• コード内の名前はバッククォートで囲みます。バッククォート部分を 隠しても、文として英語が成立するようにします。1文に2つまでです。
• 評価や誇張は避けます。「elegant」「robust」「seamless」「critically」 「importantly」「simply」などは使わず、事実を述べます。

作業速度

変更セットは直接渡されます。慎重に一度読むだけで、作業の90％は 完了します。すでに確認できる差分を整理するのであって、コードベースを 監査するのではありません。調査にかける時間を適切に見積もってください。

• ガイド用に保存した guide.patch が、主な、そして通常は唯一の情報源です。 そのファイル一覧が、対象となるファイルを確定します。
• 特定の章の説明に必要な場合は、対象を絞った確認を少数行ってかまいません。 たとえば、差分で参照されている定義、1か所の呼び出し元、PR の本文です。 確認するたびに、答えるべき具体的な質問を明確にしてください。 「コードベースを理解する」は質問ではありません。
• リポジトリを調べたり、「背景を知るため」に変更されていないファイルを 読んだり、広範囲な検索を実行したりしてはいけません。探索目的のツール呼び出しが 3回目に達したら、そこで止め、手元の情報でガイドを書きます。 ガイドの作成が遅く、徹底的すぎるのは失敗です。レビュー担当者を待たせて しまいます。遅くまで網羅的に行うより、すばやく整理して書く方が優れています。

出力形式

タイトル

1行で記述します。PR/MR が指定されている場合は、そのタイトルをそのまま 使うか、明確さのために軽く整えます。指定されていない場合は、「Code changes」のような一般的な仮タイトルではなく、変更そのものが実際に行うことに 基づいてタイトルを付けます。

intent

この変更セットが必要な理由を、1〜2文で説明します。

• PR/MR の URL が提供されている場合は、その説明を読んで（gh pr view または同等の方法）、動機や関連するイシューを確認します。
• PR の本文で GitHub のイシュー（例：「Fixes #123」、「Closes owner/repo#456」）または GitLab のイシューが参照されている場合は、詳細な背景を把握するため、そのイシューを確認します。
• PR が提供されていない場合は、コミットメッセージ、ブランチ名、変更内容自体から意図を推測します。
• 重要：明示的に参照されていないイシューやチケットを検索してはいけません。すべての未解決イシューを閲覧してはいけません。PR の説明またはコミットメッセージにリンクがない限り、Linear/Jira のチケットを調べてはいけません。提供された情報だけを追います。意図の調査は、手早く最大2回（PR 本文と、直接参照されているイシュー1件）にとどめ、その後は先に進みます。

sections

各セクションは、タイトル、概要、および1つ以上の差分参照で構成されるレビューの章です。

セクションの順序

ファイルパス、差分の大きさ、変更が行われた順序ではなく、重要度に基づいて順序を決めます。レビュー担当者は、どの章を読み終えた時点でも、それまでの重要事項をすべて把握できるようにします。

1. 最も重要な章を最初に置きます。実装の中心となる部分、つまり、理解することで他のすべてが分かる部分です。レビュー担当者がエントリーポイントを探し回る必要がないようにします。
2. 次に、影響の大きい順に、呼び出し箇所の更新、下流ロジックの調整、新しい動作のテストを扱います。テストは、些細なものでない限り、対象となるコードと同じ章にまとめます。
3. 接続処理や重要度の低い変更は最後にまとめ、レビューの流れを妨げないようにします。配線、インポート、名前の変更、設定、生成ファイルなどが該当します。最後の章には、「配線と設定」や「整理」など、内容を率直に表す簡潔なタイトルを付け、1〜2文で概要を説明します。それ以上の内容は必要ありません。

セクションの分け方

セクションは変更の論理的なまとまりであり、ファイル単位でもフォルダー単位でもありません。1つの理由で3つのファイルを変更した場合は、3つのファイルを参照する1つのセクションにします。1つのファイルに無関係な変更が2つある場合は、2つのセクションに分けます。ファイルごとに1セクションを設ける方法を既定にしてはいけません。変更の論理に基づいて判断します。

章は、作業の自然な区切りに沿って構成します。変更セットに複数の異なる作業（2つの機能、または機能と無関係なリファクタリングなど）が含まれる場合は、それぞれに独自の章を設けます。無関係な作業を同じ章にまとめてはいけません。

セクションのフィールド

• title：概念レベルのタイトル。例：「決済ローカライズモジュール」。ファイル名を言い換えただけの「payments/locale.ts の変更」のようなタイトルは絶対に使わないでください。

• overview：Markdown 形式で、2〜6文にします。次の3つの役割を、この順番で果たします。

  1. ここで具体的に何が変わったか。
  2. なぜそれが必要なのか。動機と、ひと目では分からない判断（「Z という理由から、Y ではなく X を選んだ」は、レビュー担当者が必要とし、差分だけからは把握できない情報です）。
  3. 主な影響。システムの動作、ユーザー体験、API／データの契約、パフォーマンス、運用にどのような変化をもたらすか。UI の変更に限りません。スキーマ移行、リトライポリシーの変更、インフラの切り替えにも、平易な一文で説明する価値のある影響があります。 変更内容のリスクの大半を担うセクションや、特に注意深く読むべきセクションがある場合は、その概要ではっきり明記してください（「ここが特に注意して読むべき部分です。ほかの変更はすべてこれに伴うものです」など）。本当にリスクの高い動作変更や契約変更には、> [!IMPORTANT] または > [!WARNING] の告知行を使います。ほとんどのセクションには必要ありません。

  Markdown は、文章を明確にする場合に限り、装飾ではなく効果的に使ってください。

  • すべてのファイル名、シンボル、関数、型、設定キー、CLI フラグをバッククォートで囲みます。例：refreshToken、--dry-run、SESSION_TTL。
  • ざっと読むレビュー担当者が見落としてはならない節を、太字にします。概要につき最大1か所です。
  • セクションで3つ以上の並列した変更がある場合は、短い箇条書きを使います。それ以外は文章にします。
  • コードのほうが文章より適切な場合に限り、短いフェンス付きコードブロック（2〜5行）を使います。新しい API の形などが該当します。差分の一部を貼り付けないでください。差分はすでに概要の隣に表示されています。

• diffs：1つ以上のファイル参照。それぞれに次の2つのフィールドを指定します。

  • file：差分に記載された、変更後のリポジトリ相対パスを正確に指定します。コピーして使い、新たに作成したり、省略したり、正規化したりしないでください（先頭／末尾のスラッシュや大文字・小文字も変更しないでください）。git diff --stat でリネームが dir/{old => new}/file.ts と表示される場合、これはパスではありません。dir/new/file.ts と記載してください。
  • summary：すでに確認した差分の該当箇所をもとに、このファイルにおける意味上の変更を1〜2文で説明します。「ステージングのロジックを3値のオーバーライドマップに切り出す」のように、変更の内容を述べてください。「30〜80行目を変更する」のように、変更箇所を述べてはいけません。記述のためにファイルを開いたり、コードベースを検索したり、ファイルごとの調査を行ったりしないでください。概要の繰り返しも避けてください。概要では理由と影響を説明し、サマリーではこのファイルが具体的に担う変更を説明します。些細な変更（import の更新、リネームに伴う変更など）は、短い句だけで十分です。

unplacedFiles

必ず unplacedFiles を含めてください。すべての変更ファイルが配置されている場合は、空の配列にします。どのセクションにも当てはまらない変更ファイルは、純粋なノイズ、またはセクションに無理に含めると内容が薄まるほど重要度の低い残りのファイルです。適切に範囲を絞った変更であれば、このようなケースはまれなはずです。概要を書くのを避けるための置き場として使わないでください。接着役となるファイルや配線・設定ファイルは、通常、最後のまとめの章に含めます。

網羅性に関するルール（厳守）

変更された各ファイルは、必ずいずれか1か所にだけ含めてください。各セクションの diffs のいずれか1つだけに含めるか、unplacedFiles に含めてください。両方に含めたり、複数のセクションに重複して含めたり、完全に省略したりしてはいけません。guide.patch に記載されたファイルが正規のファイル一覧です。必ずすべてを網羅してください。

厳守事項

• diffs[].file は、diff または変更ファイル一覧にある正確なパスでなければなりません。決して創作したり、省略したり、大文字・小文字を変更したりしないでください。
• 各ファイルは、いずれか1つのセクション、または unplacedFiles に必ず含めてください。重複も漏れも認められません。
• 通常は2〜6個のセクションにします。10個を超えてはいけません。変更内容が1つのセクションで十分に扱える場合は、無理に増やさず1つにしてください。
• 出力内で全角ダッシュ（—）を使わないでください。全角ダッシュの代わりに二重ハイフン（--）を使うことも禁止です。読点、コロン、または文を分けて表現してください。
• 絵文字は一切使わないでください。
• title は1行にしてください。
• intent は1〜2文にしてください。段落にしないでください。
• セクションの概要は2〜6文にしてください。長々と書かず、短すぎる一節にもならないようにしてください。

調整の指針：レビューではなく案内

あなたの役割は、レビュアーを批判することではなく、説明して変更内容を把握しやすくすることです。影響やリスクが集中する箇所を示すことは案内の一部です。「このセクションでは、すべてのクライアントが依存するセッション契約を変更しています」はまさに役割に沿っています。バグ探しは役割ではありません。読み進める中で実際のバグらしきものに気づいた場合は、該当するセクションの概要で簡潔に触れてもかまいませんが、問題を探し回ったり、批判が説明を押しのけたりしないようにしてください。ほとんどの概要でバグに触れないのは正常であり、十分に確認していないということではありません。

手順

1. guide.patch のdiff全体を読みます。
2. コミットメッセージを確認するために、コマンドを1つだけ実行します（git log --oneline）。PR/MRが指定されている場合は、そのタイトルと本文も確認します。存在しないものは読み飛ばしてください。
3. 任意の手順です。プロジェクトに詳しくなく、セクションの「理由」を把握するうえで本当に必要な場合に限り、CLAUDE.md、AGENTS.md、または README.md をざっと確認します。
4. ファイルをまたぐ変更も含め、変更を論理的なまとまりに分けます。それをセクションにします。これは思考上の作業であり、ツールを呼び出す手順ではありません。
5. 並び順は、実装の中核を最初にします。まずエントリーポイントを置き、利用側より定義側を、結果より原因を先にします。次に影響を説明し、最後に補助的で重要度の低い変更をまとめた章を置きます。
6. title、intent、各セクションの概要を作成します。何が変更されたか、なぜ変更されたか、主な影響を説明し、リスクが集中する箇所を示してください。
7. 網羅性を確認します。変更されたすべてのファイルが、いずれか1つのセクションの diffs または unplacedFiles に含まれていることを確認してください。漏れ、重複、誤記があれば、返す前に修正してください。
8. 以下の形式で guide.json を作成します。

{
  "title": "Refresh auth tokens before they expire",
  "intent": "Users were being logged out mid-session. Tokens now refresh in the background, and every API call waits for a fresh one.",
  "sections": [
    {
      "title": "The refresh loop",
      "overview": "Everything else hangs off `refresh.ts`. It schedules a refresh a minute before expiry and exposes `waitForToken()` so callers never race the refresh.",
      "diffs": [
        { "file": "src/auth/refresh.ts", "summary": "New: scheduler and waitForToken()." },
        { "file": "src/auth/session.ts", "summary": "Stores the expiry alongside the token." }
      ]
    },
    {
      "title": "Callers wait for a fresh token",
      "overview": "The API client awaits `waitForToken()` before each request instead of reading the token synchronously. Small change, but it is why the guard works.",
      "diffs": [
        { "file": "src/api/client.ts", "summary": "Awaits the token before sending." }
      ]
    },
    {
      "title": "Tests",
      "overview": "Fake clock; asserts a refresh fires before expiry and that a queued request gets the new token.",
      "diffs": [
        { "file": "src/auth/refresh.test.ts", "summary": "Timer and race coverage." }
      ]
    }
  ],
  "unplacedFiles": [],
  "review": { "gitRef": "origin/main...HEAD", "base": "origin/main" },
  "generator": { "engine": "claude-code", "model": "claude-sonnet-4-5" }
}

sections 以降のフィールド：

• review.gitRef は、差分の対象を読者に示すラベルです。実際にdiffを取得したrefを記述してください。base は任意です。
• generator は、ガイドを作成したものを示します。実行中のツール（engine）と、モデルが分かる場合はその名前（model）を記述します。通常はシステムプロンプトまたは起動時のモデル名から確認できます。確信がない場合は model を省略してください。読者には「generated by」として表示されます。このフィールドは任意です。
• source（repo、branch、head）は、gitから読み取ります。ガイドがプルリクエスト用の場合は、"source": { "kind": "pr", "pr": { "url", "number", "title" } } を追加します。

3. エクスポート

plannotator guide export --guide guide.json --patch guide.patch

plannotator がインストールされていない場合は、curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal を実行します（バイナリのみで、それ以外は何もインストールしません）。

成功すると、HTMLファイルのパスが表示されます。失敗すると終了コード1で終了し、問題の内容を表示します。パッチに含まれていないファイル（パッチに含まれるファイルの一覧も表示されます）、二重に配置されたファイル、フィールドの不足などが原因です。guide.json を修正して再実行してください。ガイドに合わせるためにパッチを編集してはいけません。出力先を指定するには --out <file.html> を追加します。

ファイルの保存場所をユーザーに伝えてください。ファイルは、ディスクからでもリンクからでも、どのブラウザーでも開けます。

ファイルではなくリンクが必要ですか？

plannotator guide share --guide guide.json --patch guide.patch

同じ検証を行いますが、ガイドは guides.show にアップロードされ、コマンドは URL を出力します。アップロードはデフォルトでエンドツーエンド暗号化されます。ホストがコードを見ることはなく、鍵はリンクの # 以降の部分なので、リンク全体を知っている人は誰でも読むことができます。削除トークンも出力されるため、両方をユーザーに渡してください（plannotator guide unshare <id> --token <token> でリンクを削除します）。リンクのプレビューをユーザーが希望する場合に限り --public を追加してください（その場合、ガイドは暗号化されずに保存されます）。リンクの共有は、ユーザーから希望があった場合に限ります。デフォルトはファイルです。