diffity-tour

Diffity ツアースキル

コードベースを案内するツアーを作成します。これは、ユーザーの質問に答えたり、機能の仕組みを説明したりする、ナレーション付きの段階的なウォークスルーです。ツアーをブラウザーで開くと、ナラティブとハイライトされたコードセクションを表示するサイドバーが表示されます。

引数

• question（必須）：ユーザーの質問、トピック、概念、または GitHub PR の URL。例：
  • /diffity-tour how does authentication work?
  • /diffity-tour explain the request lifecycle
  • /diffity-tour how are comments stored and retrieved?
  • /diffity-tour closures
  • /diffity-tour React hooks
  • /diffity-tour walk me through this branch before I merge
  • /diffity-tour https://github.com/owner/repo/pull/123

引数が GitHub PR の URL（github.com/owner/repo/pull/N に一致するもの）の場合、ツアーは自動的に レビュー モードに固定されます。PR の差分が対象範囲を決定し、結論には PR フラグのリストを含める必要があります。詳しくは、以下の レビュー ツアーセクションをご覧ください。

CLI リファレンス

diffity agent tour-start --topic "<text>" [--body "<text>"] --json
diffity agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json
diffity agent tour-done --tour <id> --json
diffity list --json

前提条件

1. diffity が利用可能であることを確認します。which diffity を実行してください。見つからない場合は、npm install -g diffity でインストールします。
2. 引数が GitHub PR の URL の場合：
   • gh がインストールされ、認証済みであることを確認します。gh auth status を実行してください。認証されていない場合は停止し、gh auth login を実行するようユーザーに依頼します。
   • 現在のリポジトリが PR のリポジトリと一致することを確認します。gh repo view --json nameWithOwner -q .nameWithOwner を実行し、URL の owner/repo と一致することを確認してください。一致しない場合は停止し、PR のリポジトリをクローンしたディレクトリ内で作業する必要があるとユーザーに伝えます。diffity では、チェックアウトしていないリポジトリの PR をツアーできません。
   • PR に対して diffity を起動します。Bash ツールで diffity --no-open <pr-url> を run_in_background: true にして実行してください。--no-open フラグは URL の前に置く必要があります。commander's passThroughOptions() は位置引数の URL の後にあるフラグをすべて refs 配列に取り込むため、PR の処理がスキップされ、「unknown ref」エラーが発生します。このコマンドは PR のブランチをローカルにチェックアウトし、差分の範囲に限定したセッションを開始します。2 秒待ってから、ポートを取得するために diffity list --json を実行します。ツリーインスタンスも起動する必要はありません。差分セッションは agent tour-* コマンドに対応しています。
3. それ以外の場合は、ツリーインスタンスが実行中であることを確認します。diffity list --json を実行してください。
   • インスタンスが実行されていない場合は、Bash ツールで diffity tree --no-open を run_in_background: true にして起動し、2 秒待ってから、ポートを取得するために diffity list --json を実行します。

手順

まずモードを選びます

何かを始める前に、このツアーがどのモードに該当するかを決めます。以降のスキルはこの選択に応じて分岐します。対象範囲、調査方法、出力形式がすべてモードによって異なります。ツールを呼び出す前に選択してください。

ショートカット： 引数が GitHub PR の URL（github.com/owner/repo/pull/N に一致する場合）なら、選択をスキップできます。モードは Review mode に固定されます。

モード	ユーザーの依頼内容	対象範囲	手順の目安
Focused	範囲の狭い「X はどのように動作しますか？」という質問	1 つのコードパス	3～6
Feature	「この機能はどのように動作しますか？」	機能の境界	6～10
System	「全体はどのように動作しますか？」	アーキテクチャ	8～15
Concept	プログラミングの概念について	コード内の例	3～8
Review	マージ前のブランチ／PR／機能の監査	git diff <base>..HEAD	可変 — 意味のある変更をすべて網羅

各モードを選ぶ際の判断材料となるキーワード：

• Focused：「X はどのように検証しますか」「Y エンドポイントを順に説明してください」
• Feature：「認証はどのように動作しますか」「コメントシステムを説明してください」
• System：「アプリはどのように動作しますか」「アーキテクチャの概要を説明してください」
• Concept：単独で挙げられた概念（closures、React hooks、async/await、generics）
• Review：「マージする前に」「このブランチをレビューしてください」「機能全体を順に説明してください」「この PR を監査してください」「これからマージするところです」

複数のモードが当てはまる場合は、より具体的なモードを優先します（Review > Concept > Focused > Feature > System）。ユーザーが何を求めているか本当に判断できない場合は、調査を始める前に確認してください。推測して、誤った形式のツアーを作成してはいけません。

モードによって、このスキルのどのセクションが適用されるかが変わります。

• Concept mode → 以下の Concept tours セクションを読みます。調査方法（フローをたどるのではなく、例を検索する）と手順の進め方が異なります。
• Review mode → 以下の Review tours セクションを読みます。対象範囲は差分を基準に決め、スレッドを 1 つずつ確認し、結論には PR のフラグ一覧を含める必要があります。
• Focused / Feature / System mode → デフォルトの Phase 1-3 の指示がそのまま適用されます。

Phase 1: 対象範囲と調査

ツアーの手順を作成する前に、ユーザーの質問への答えを深く理解しておく必要があります。

1. 対象範囲を確認します。 選択したモードによって、おおよその手順数が決まります（上記の Pick a mode を参照）。ユーザーの質問がその規模に収まらないほど広い場合（たとえば「すべてを説明して」という依頼を System mode で扱う場合）は、最も重要な側面に対象を絞り、冒頭で説明する内容と対象外とする内容を明示します。

2. 対象者を特定します。 質問の表現を考慮してください。

   • 「X はどのように動作しますか？」→ このコードベースに初めて触れる人を想定し、コードの仕組みだけでなく、アーキテクチャ上の判断も説明します。
   • 「なぜ X は Y をするのですか？」→ デバッグ中、またはレビュー中の人を想定し、理由とエッジケースに焦点を当てます。
   • 「X を順に説明してください」→ 全体像を知りたい人を想定し、背景も含めて十分に説明します。

3. コードベースを調査します。 関連するソースファイルを十分に読みます。エントリーポイントから処理の完了までコードパスをたどります。

   特にレビューのツアーでは、git log --reverse <base>..HEAD も読み、メッセージに自明でない修正、リファクタリング、または防御的な変更が記されているコミットを開いてください。作者自身の説明は、多くの場合、コードだけから意図を推測するよりも、変更の「理由」を知る最良の情報源です。設計上の判断を明らかにする場合は、手順の本文でコミットの説明を引用または言い換えてください（例：「本番環境でのインシデントを受けて、このチェックを導入したコミット abc1234 では……」）。 GitHub の PR を調査するときは、メタデータと差分の取得に gh を使用します：

   • gh pr view <url> --json title,body,baseRefName,headRefName,commits,files — PR のタイトル、本文、ベース／ヘッドブランチ、コミット一覧、変更ファイル一覧を取得します。PR の本文には、設計の背景、スクリーンショット、作成者が検討したトレードオフなど、最も詳しい「理由」が記載されていることがよくあります。導入部分では、その内容を引用または要約してください。
   • gh pr diff <url> — ツアーの対象範囲を定める統一形式の差分です。git diff で見える範囲だけでなく、変更の全体像を確認するために使用してください。
   • デフォルトで master／main を使うのではなく、差分のベースには（上記の JSON から取得した）PR の baseRefName を使用してください。git log --reverse <baseRefName>..<headRefName> などのコマンドを使うと、PR のコミットを作成者の順序でたどれます。
   • diffity <pr-url> によって PR のブランチがローカルにチェックアウト済みのため、作業ツリーからソースファイルを参照できます。

4. ストーリーを伝える重要な箇所、つまり答えを理解するために確認が必要なファイルと行範囲を特定してください。

5. 設定による依存関係に注意してください。 環境変数、機能フラグ、設定ファイル、または実行時の条件によって動作が変わる場合は、その点を記載してください。読者が「X を設定するとこう動作しますが、代わりに Y を設定すると、ここでフローが変わります」と理解できるよう、ツアーで必ず取り上げてください。

6. 理解が段階的に深まる、論理的な順序を計画してください。各ステップが自然に次のステップへつながるようにします。

ステップを選ぶ際のガイドライン：

• 実際のエントリーポイント、つまり外部入力が届く場所（HTTP ルート、CLI コマンド、スケジュールされたジョブ、Webhook）から始めてください。設定、スキーマ、定数、ヘルパー関数はエントリーポイントではなく、フローの依存要素です。
• 基礎となる要素は、必要になった時点で紹介してください。フローでスキーマを初めて読み取るときに、そのスキーマを説明します。ヘルパーを初めて呼び出すときに、そのヘルパーを説明します。設定値を初めて参照するときに、その設定を説明します。フローを始める前に、基礎要素を先回りして並べないでください。
• エントリーポイントより前に置けるのは、ルート表ですべてのエンドポイントを示すなどの「概要説明」ステップを最大 1 つです。それ以外の内容は、読者が直前に見た内容を踏まえて紹介してください。
• 実際の実行順序に沿ってください。
• 理解に欠かせない箇所だけを取り上げ、定型処理は省略してください。
• 最終的な結果（レスポンスの送信、データの永続化、UI の描画）で終えてください。
• 各ステップでは、1 つの概念またはコードセクションだけを扱ってください。
• 可能な場合は具体例を含めてください（例：「ユーザーが diffity main を実行すると、これは……になります」）。

ボトムアップではなく、トップダウンで。 ツアーでは、コードが実行時にどのように動くかをたどります。コードがどのように構築されたかをたどるのではありません。設定 → スキーマ → ヘルパー → ルート → アクションの順に説明しないでください。ルート → アクション →（クエリが読み取る箇所でスキーマを紹介）→（ハンドラーが参照する箇所で設定を紹介）→（呼び出し元の箇所でヘルパーを紹介）の順に進めてください。新しい要素が必要になった時点で紹介すると、読者はそれまでの流れを保ちやすくなります。デモの前にアーキテクチャの講義を受けるのではなく、実際のリクエストをたどるあなたの隣に座っているように読者が感じられる構成にしてください。

モジュールをまたぐフローの扱い： コードパスがライブラリ、ユーティリティモジュール、または深くネストされた抽象化に入る場合は、そこまで追うかどうかを判断してください。

• 追う： 答えを理解するうえで、そのロジックが重要な場合（例：リクエストを変換するカスタムミドルウェア）
• 要約する： モジュールが標準的、またはよく知られた処理を行う場合（例：「Express ルーターを呼び出し、パスに一致するルートを見つけてハンドラーを実行します」）。その処理を別のステップにはせず、ステップ本文で説明してください。
• 省略する： 純粋な定型処理や配線コードの場合（例：再エクスポート、型定義のみのファイル） 複数のファイルに適用されるパターン。 1 つの変更を N 個の類似する呼び出し箇所に複製する場合（たとえば、同じガードを 8 つのハンドラーに追加する、すべてのルートに同じミドルウェアを登録するなど）、N 個のステップを作成しないでください。最も代表的なファイルを 1 つ選び、十分な文脈を含めたステップを 1 つ作成したうえで、本文に他の呼び出し箇所への goto リンクを列挙します（「同じガードは X、Y、Z にも追加されています」）。1 つの概念につき 1 つのステップにします。このツアーでは、読者にパターンを一度だけ説明し、N 回繰り返さないようにしてください。例外として、適用箇所のうち 1 つが他と微妙に異なる場合（転送フロー内で 2 回呼び出される、引数が異なるなど）は、その箇所について別のステップを作成します。

フェーズ 2：ツアーを作成する

ツアー UI には専用の説明パネルがあります。tour-start --body のイントロはステップ 0 として表示され、読者が最初に目にする内容として、パネル全体を使って表示されます。その後の各ステップでは、ハイライトされたコードとともに、同じパネルに説明が表示されます。パネルには十分なスペースがあるため、内容豊富で詳しい説明を書いてください。

1. ツアーを開始し、短いトピックタイトルと導入本文を設定します。

   diffity agent tour-start --topic "<short title>" --body "<intro>" --json
   

   --topic はツアーパネルのヘッダーに表示されるため、3～6 語に収めてください（例：「認証フロー」「ルーティングの仕組み」「コメントシステムのアーキテクチャ」）。ユーザーの質問全文をトピックとして使わないでください。

   イントロ本文（ステップ 0）の書き方： 読者が最初に目にする内容であり、説明パネル全体を使って表示されます。このスペースを使って、コードに入る前に必要なことをすべて理解できる、十分なアーキテクチャ概要を説明してください。次の内容を含めます。

   • 関連する主要なコンポーネント／パッケージ／モジュールと、それぞれの役割
   • コンポーネント間のつながり（データフロー、呼び出しチェーン、依存関係など）
   • 読者が知っておくべき主要な抽象化やパターン
   • 太字テキストを使った概要フロー図（例：CLI 引数 → git diff → パーサー → JSON API → React のレンダリング）
   • 設定の背景 — 機能の動作が設定、環境変数、または機能フラグに左右される場合は、ツアーがどのモード／状態を前提としているのか読者にわかるよう、ここで説明します。

   範囲を絞って広範な質問に対応した場合は、何を扱うのかを明記してください。「このツアーでは OAuth ログインフローに焦点を当てます。トークンの更新とセッション管理も関連しますが、別途扱います。」

   段落、太字、code、表、コードブロックなどを使い、Markdown で内容豊かに整形してください。ツアーで扱う内容を列挙する目次ではなく、読者が全体像を把握できる独立した概要にしてください。

   JSON 出力からツアー ID を取得します。

2. ステップを追加します。順番に、各ステップについて次のようにします。

   diffity agent tour-step --tour <id> --file <path> --line <start> --end-line <end> --body "<narrative>" --annotation "<short label>" --json
   

   ステップ内容の書き方：

   • --file：リポジトリのルートからの相対パス（例：src/server.ts）
   • --line／--end-line：ハイライトする正確な行範囲。関連する箇所に絞ってください。
   • --annotation：ステップのタイトルとして表示される短いラベル（3～6 語）。章の見出しとして考えてください。
   • --body：説明パネルに表示される文章。十分なスペースがあるため、Markdown を使って詳しく説明してください。

   ステップを決定する前に、対象を確認してください。 tour-step を実行する前に、--file のパスがリポジトリのルートから読み取り可能であることと、説明する関数またはブロックが指定した --line／--end-line の範囲に実際にあることを確認してください。以前のセッションでの記憶を信頼せず、その範囲を読み取ってください。本文内のすべての goto: リンクにも同じことが当てはまります。リンク切れの goto リンクは、読者が信頼してクリックした結果、リンクが間違っているという手がかりもなく、誤った場所に移動してしまうため、リンクがないよりも問題です。正確な行がわからない場合は、goto リンクではなく通常のバッククォート付きコードを使ってください。

   ステップ本文の構成。 各ステップ本文は、次の流れに沿って順番に構成してください。

   1. つなぎ（1文）：前のステップからつなげます。以下の例を参照してください。
   2. 解説（大部分）：このコードが何をするのか、そして なぜ このような構成になっているのかを説明します。設計上の判断、トレードオフ、具体例を含めてください。範囲が明確なセクションに分かれる場合は、サブハイライト（focus:X-Y）を使用してください。
   3. 要点（1～2文）：注意点、エッジケース、または「ここを変更するのはこんなとき」という手がかりを示します。

   つなぎのないステップ本文は唐突に感じられ、要点のないものは未完に感じられます。各ステップ本文は、およそ 150～300語を目安にしてください。ロジック上どうしても必要な場合に限り、長くしてかまいません。下書きが400語を超える場合は、ひとつのステップで2つの内容を扱おうとしている可能性があります。分割を検討してください。

   ステップ間のつなぎ — 語りの流れをつなぐ： 各ステップが前のステップから自然に続くようにします。各ステップ本文は、前の内容とのつながりを示すつなぎの文から始めてください。

   • 「リクエストの解析方法がわかったので、次はどこで検証されるのか見ていきましょう……」
   • 「先ほど見たハンドラーはこのサービスに処理を委譲します。ここに実際のビジネスロジックがあります……」
   • 「この時点でデータの変換が完了し、永続化できる状態になっています。どのように行われるのか見ていきましょう……」

   読者が文脈なしで読み始めるようなステップにしてはいけません。コードツアーはひとつの物語です。各ステップは孤立した段落ではなく、章のように構成してください。

   推奨事項：

   • 構造化コンテンツが役立つ場合はそれを補助的に使いつつ、文章で説明します。

   • 関数名、変数、参照、コマンドには code を使用します。既知のファイルと行にある関数、クラス、コードシンボルを参照する場合は、読者がクリックして移動できる goto リンクにしてください。構文：[`symbolName`](goto:path/to/file.ts:startLine-endLine) または、1行の場合は [`symbolName`](goto:path/to/file.ts:line) です。これらはクリック可能なインラインコードとして表示され、ファイル内の該当行に移動してハイライトします。例：[`handleDragEnd`](goto:src/KanbanContent.jsx:42-58)。一般的な用語、CLI コマンド、コードベース内の場所を特定していないシンボルには、通常のバッククォート付きコードを使用します。

   • 導入する重要な概念には 太字 を使用します。

   • コードが何をするかだけでなく、なぜ存在するのか、その背後にある設計上の判断も説明します。

   • 具体例を使います。「diffity main を実行すると、この行は normalizeRef('main') を呼び出し、git merge-base main HEAD を計算します」

   • 対応関係（入力 → 出力、参照 → git コマンド）には表を使用します。

   • データ構造やコマンド出力にはコードブロックを使用します。

   • 各ステップを、導入部で説明した全体像につなげます。

   • エッジケースや注意点を明示します。一見してわかりにくい挙動、既知の制限、「誤りに見えるが意図的」な箇所があれば、必ず説明してください。後からこのコードを変更する人がつまずきやすいのは、こうした点です。

   • 大きな範囲をハイライトする場合は、ステップ内の特定のサブセクションに焦点を当てる サブハイライトリンクを使用します。構文：[ラベル](focus:startLine-endLine)。これらはクリック可能なチップとして表示され、指定した行にハイライトを移動します。例：

     まず、関数がパラメーターを検証します：
     [パラメーターの検証](focus:15-22)
     
     次に、コア変換処理で各エントリーを処理します：
     [コア変換処理](focus:25-40)
     
     最後に、結果をキャッシュしてから返します：
     [結果のキャッシュ](focus:42-48)
     

     ひとつのステップが30行以上を扱い、説明の流れに沿って明確なセクションに分かれる場合は、サブハイライトを使用してください。行の範囲は、そのステップの --line / --end-line の範囲内に収めてください。 Mermaid 図： 概念を視覚的に示すほうが理解しやすい場合（アーキテクチャの関係、データフロー、ステートマシン、シーケンス図など）は、mermaid のコードブロックを含めてください。すべてのステップに無理に図を入れる必要はありません。説明を本当にわかりやすくする場合に使ってください。適した例：

   • 導入（ステップ 0）の概要：コンポーネントの接続方法を示すフロー

   • 複数のコンポーネント間のやり取りやリクエストフローを含むステップ

   • ステートマシンやライフサイクルの遷移

   最も適した図の種類を選んでください：

   • アーキテクチャ、モジュールの依存関係、データフローには graph TD/LR
   • 呼び出しチェーン、リクエスト／レスポンスのフローには sequenceDiagram
   • ステートマシン、ライフサイクルの遷移には stateDiagram-v2
   • 型の階層、構造体の関係には classDiagram
   • アルゴリズム、決定木、制御フローには flowchart

   図は簡潔にしてください（ノード数は約 12 個未満）。ツアーパネル内にインラインで表示されます。

   避けること：

   • 箇条書きばかりを並べること。書式を使った文章の段落にしてください
   • 構文を説明するだけで終わること。設計上の判断について説明してください
   • ハイライトされたコードに表示されている情報を繰り返すこと
   • ステップの本文に見出しを使うこと（注釈がタイトルの役割を果たします）
   • すべてのステップに無理に図を入れること。本当に役立つ場合にのみ追加してください
   • 前のステップとのつながりを示さずにステップを始めること

3. 結論のステップを追加します。 ツアーの最後のステップで全体をまとめてください。最後の意味のあるステップと同じファイル／行範囲を使い、次の内容を含む本文を書いてください。

   • 全体の流れを要約する： 2〜3 文でまとめます。すべての要素を確認したところで、全体を俯瞰したメンタルモデルを示し、読者が今後も活用できるようにしてください
   • 重要な設計上の判断を強調する： このコードにおける最も重要なアーキテクチャ上の選択肢を 2〜3 点挙げ、なぜその選択がなされたのか説明してください
   • 拡張ポイントを示す： この機能を変更または拡張する場合、どこから始めればよいでしょうか。どのファイルを変更すればよいでしょうか
   • 関連領域に触れる： この機能につながる関連機能やフローを 1〜2 個挙げ、次に調べる場所がわかるようにしてください

   このステップには注釈 "Putting It Together" を使ってください。

4. ツアーを完了します：

   diffity agent tour-done --tour <id> --json
   

フェーズ 3：ブラウザーで開く

1. diffity list --json から実行中のインスタンスのポートを取得します。

2. ツアーを開きます：open "http://localhost:<port>/tour/<tour-id>"（またはユーザーの OS に適したコマンド）。

3. ツアーの準備ができたことをユーザーに伝えます：

   ツアーの準備ができました。ブラウザーをご確認ください。

概念ツアー

ユーザーが機能やフローではなく、プログラミングの概念（例：「クロージャ」「ジェネリクス」「エラー処理のパターン」）について尋ねた場合、ツアーは学習ツールになります。

概念ツアーと機能ツアーの違い：

• 調査フェーズ：実行経路をたどる代わりに、コードベースを検索して概念の実例を探します。grep、glob、ファイルの読み取りを使ってパターンを見つけます。広く調べてください。クロージャはコールバック、ファクトリー関数、イベントハンドラーなどに現れる場合があります。
• 例の選定：概念の異なる側面をカバーする例を3～8個選び、簡単なものから複雑なものへと進めます。同じ使い方の例を5つ並べないでください。
• 導入本文：この概念に初めて触れる人にもわかるように書きます。専門用語を使わない定義、概念が存在する理由（どのような問題を解決するか）、メンタルモデルや類推、注目すべき構文上の手がかりを含めてください。
• 各ステップの本文：実際の例を通して、各ステップで1つの側面を教えます。コードの位置づけを説明 → 概念がどのように使われているかを示す → ここで使われている理由を説明 → 要点を伝える、という構成にします。専門用語は初出時にその場で定義します。
• 順序：最初の例は、読者が「なるほど、これだけなんだ」と思えるものにします。最後の例は、最も高度な使い方にします。
• まとめのステップ：重要なルールを3～5個振り返り、よくある間違いを2～3個挙げ、次に学ぶ関連概念を提案します。
• 例が少ないコードベース：実例が3つ未満の場合は、一時的な学習用スニペットファイルを作成し、それらをツアーのステップとして使います（独立した例であることを明記してください）。ツアー作成後にファイルを削除します。

その他のツアーガイドライン（つなぎ、gotoリンク、サブハイライト、mermaid図、結論）も引き続き適用されます。

レビューツアー

ユーザーがマージ前にブランチ、PR、または機能をレビューするためのツアーを求めた場合、アーキテクチャの解説ではなく、ユーザー向けのフローに沿ったリクエストの追跡としてツアーを構成します。この形式が、読者が実際の対応に活用できる監査につながる可能性が最も高いです。

レビューツアーと機能ツアーの違い：

• 差分に基づく範囲設定：読者は変更内容を監査しようとしています。まず git diff <base>...HEAD（および関連するコミット）を読み、変更範囲全体を把握します。単なる定型コードを除き、意味のある変更はすべて確認します。
• 導入の構成：機能について1段落で述べた後、各要素の表（領域 → 場所 → 目的）、概要フロー図、簡潔な設定コンテキストブロック（環境変数、新しい定数、動作のデフォルト値）を含めます。導入部分で、読者がこれからたどる道筋を把握できるようにします。
• 位置づけのステップは1つだけ許可：ルートテーブル、Webhookの切り替え処理、その他エンドポイントの一覧がある場合は、それをステップ1に置き、ツアーでたどるスレッドのメニューとして使えます。それ以降はすべてフローに沿って進めます。
• 一度に1つのスレッドを扱う：最も一般的なユーザージャーニー（通常は「作成 → 有効化 → 継続的な管理」）から始め、必要な基盤部分を適宜説明しながら、最初から最後までたどります。その後、残りのスレッドを1つずつ扱います。スレッドを交互に扱わないでください。
• 横断的なゲート処理は最後に扱う：複数のアクションに適用されるアクセスチェック、レート制限、機能フラグ、共有ガードなどは、メインフローの後に扱います。そうすることで、読者は「何が制御されているか」を把握してから、「どのように制御されているか」を確認できます。
• レビュー担当者向けの結論：通常のメンタルモデルと拡張ポイントに加えて、**「PRの議論で指摘すべき点」**のリストを含めます。ここには、わかりにくいトレードオフ、防御的なコード、競合が発生する隙間、古くなったデフォルト値、トランザクションを伴わない書き込みなどを挙げます。これはレビューツアーで最も価値のある部分となることがよくあります。

その他のツアーガイドライン（つなぎ、gotoリンク、サブハイライト、mermaid図、結論）も引き続き適用されます。

品質チェックリスト

仕上げる前に、以下を確認してください。

• 導入（ステップ 0）で目次を示すのではなく、アーキテクチャの概要を詳しく説明している
• 質問の範囲が限定されている場合、導入で対象となる内容と対象外の内容を明示している
• 関連する箇所で、設定上の依存関係（環境変数、機能フラグ、設定）を示している
• 最初のコードステップが実際のエントリーポイント（ルート、CLI ハンドラー、イベントハンドラー）であり、設定ファイル、スキーマ、ヘルパーではない
• 基盤となる要素（スキーマ、設定、定数、ヘルパー）は、事前説明にまとめるのではなく、フロー内で最初に参照されるステップに登場する
• エントリーポイントより前の概要説明ステップは 1 つ以内である
• ステップはファイル名のアルファベット順ではなく、実際の実行／データフローに沿っている
• 各ステップの冒頭に、前のステップにつながる移行の説明がある
• 設計上の判断とその理由を説明しており、コードの動作内容だけにとどまっていない
• エッジケースや注意点がある箇所で、それらを明示している
• 同じファイルの同じ行を強調するステップが連続していない
• モジュール間の移動について、後続で説明するか、要約するか、省略するかのいずれかを行い、説明のないまま放置していない
• 結論のステップで、全体像、設計上の判断、拡張ポイントを結び付けている
• 既知のファイル位置がある関数、クラス、シンボルへの参照すべてに、goto リンクを使用している
• すべての goto: リンクと --file ／ --line の値を実際のファイルと照合しており、行番号を推測していない
• 同じパターン（N 個のファイルに共通するガード／ミドルウェア）は N 個のステップに分けず、1 つのステップで扱っている
• 各ステップの本文が「移行の説明 → 解説 → 要点」の順になっており、150～300 語の範囲に収まっている
• レビューツアーでは、結論に「PR の会話で指摘すべき点」のリストがある