code-tour

Code Tour

CodeTour ファイルを作成します。コードベースを対象者に合わせて段階的に案内し、ファイルや行番号に直接リンクするウォークスルーです。CodeTour ファイルは .tours/ に保存され、VS Code CodeTour extension で利用できます。

概要

優れたツアーは物語です。特定の人に向けて、何が重要なのか、なぜ重要なのか、次に何をすべきかを伝えるストーリーです。作成するのは .tour JSON ファイルのみです。ソースコードは絶対に変更しないでください。

このスキルを使うタイミング

• ユーザーがコードツアー、オンボーディングツアー、アーキテクチャのウォークスルーの作成を依頼した場合
• ユーザーが「この PR のツアー」「X の仕組みを説明して」「雰囲気を確認」「RCA ツアー」と言った場合
• ユーザーがコントリビューターガイド、セキュリティレビュー、バグ調査のウォークスルーを求めている場合
• ファイルや行番号を示す、構成化されたウォークスルーを求める場合

基本的なワークフロー

1. リポジトリを調べる

何か質問する前に、コードベースを調べます。

並行して、ルートディレクトリの一覧表示、README の読み込み、設定ファイルの確認を行います。 次に、言語、フレームワーク、プロジェクトの目的を特定します。フォルダー構造を1～2階層まで把握します。エントリーポイントを見つけます。ツアー内のすべてのパスが実在する必要があります。

ソースファイルが5つ未満のリポジトリでは、ペルソナに関係なく、簡易ツアーを作成します。深いツアーを作るほどの内容がないためです。

2. 意図を推測する

メッセージ1つで十分です。ペルソナ、深さ、焦点を内部で推測します。

ユーザーの発言	ペルソナ	深さ
「この PR のツアー」	pr-reviewer	standard
「なぜ X が壊れたのか」／「RCA」	rca-investigator	standard
「オンボーディング」／「新しい参加者」	new-joiner	standard
「簡単なツアー」／「雰囲気を確認」	vibecoder	quick
「アーキテクチャ」	architect	deep
「セキュリティ」／「認証レビュー」	security-reviewer	standard
（指定なし）	new-joiner	standard

意図が曖昧な場合は、new-joiner ペルソナ、standard 深さを既定値にします。最も幅広く役立つ設定です。

3. 実際のファイルを読む

すべてのファイルパスと行番号を確認する必要があります。 誤った行を示すツアーは、ツアーがないよりも悪いものです。

4. ツアーを作成する

.tours/<persona>-<focus>.tour に保存します。

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Descriptive Title — Persona / Goal",
  "description": "Who this is for and what they'll understand after.",
  "ref": "<current-branch-or-commit>",
  "steps": []
}

ステップの種類

種類	使用するタイミング	例
Content	導入／締めくくりのみ（最大2つ）	{ "title": "Welcome", "description": "..." }
Directory	モジュールを案内する	{ "directory": "src/services", "title": "..." }
File + line	基本となる形式	{ "file": "src/auth.ts", "line": 42, "title": "..." }
Selection	コードブロックを強調表示する	{ "file": "...", "selection": {...}, "title": "..." }
Pattern	正規表現で一致箇所を指定する（変更されやすいファイル向け）	{ "file": "...", "pattern": "class App", "title": "..." }
URI	PR、Issue、ドキュメントへのリンク	{ "uri": "https://...", "title": "..." }

ステップ数

深さ	ステップ数	用途
Quick	5-8	Vibecoder、すばやい探索
Standard	9-13	ほとんどのペルソナ
Deep	14-18	Architect、RCA

説明文の作成 — SMIG の公式

• S — Situation（状況）：読者は何を見ていますか？
• M — Mechanism（仕組み）：このコードはどのように動作しますか？
• I — Implication（意味合い）：このペルソナにとって、なぜ重要ですか？
• G — Gotcha（落とし穴）：知識のある人でも、何を誤解しそうですか？

5. 検証する

• すべての file パスがリポジトリのルートからの相対パスである（先頭に / や ./ がない）
• すべての file の存在を確認済みである
• ファイルを読んで、すべての line を確認済みである
• 最初のステップに file または directory のアンカーがある
• コンテンツのみのステップは最大2つである
• nextTour を設定する場合、別のツアーの title と完全に一致している

ペルソナ

ペルソナ	目標	必ず扱う内容
Vibecoder	すぐに全体像をつかむ	エントリーポイント、主要モジュール。最大8ステップ。
新しい参加者	段階的に習得する	ディレクトリ、セットアップ、ビジネスの背景
バグ修正担当者	すばやく根本原因を特定する	発生条件 -> 障害箇所 -> テスト
RCA 調査担当者	なぜ失敗したのかを調べる	因果関係の連鎖、可観測性の手がかり
機能の説明担当者	エンドツーエンドで理解する	UI -> API -> バックエンド -> ストレージ
PR レビュアー	正しくレビューする	変更の経緯、不変条件、リスクの高い箇所
アーキテクト	構造と設計理由を理解する	境界、トレードオフ、拡張ポイント
セキュリティレビュアー	信頼境界を把握する	認証フロー、検証、シークレットの取り扱い
リファクタリング担当者	安全に再構成する	継ぎ目、隠れた依存関係、抽出の順序
外部コントリビューター	安全に貢献する	安全な領域、規約、注意点

ナラティブの流れ

1. 概要の把握 — file または directory のステップ（最初のステップをコンテンツのみにはしない。VS Code で空白になるため）
2. 高レベルのマップ — 主要モジュールを示すディレクトリのステップを1～3個
3. コアパス — ツアーの中心となるファイル／行のステップ
4. 締めくくり — 読者ができるようになること、推奨する次のステップ

アンチパターン

アンチパターン	改善策
ファイル一覧 — 「このファイルにはモデルが含まれています」	ストーリーを伝えます。各ステップを前のステップにつなげます。
一般的な説明	このコードベース特有のパターンを具体的に示します。
行番号の推測	実際に読んで確認していない行を決して記載しません。
手早く深く理解するためのステップが多すぎる	実際にステップを削ります。
存在しないファイル	存在しない場合は、そのステップを省きます。
要約で締めくくる — 「X、Y、Zを説明しました」	読者がこれからできることを伝えます。
最初のステップがコンテンツのみ	ステップ1をファイルまたはディレクトリに紐づけます。

相互参照

• 関連：engineering/codebase-onboarding — ツアーにとどまらない、より幅広いオンボーディングについて
• 関連：engineering/pr-review-expert — PR レビューの自動化ワークフローについて
• CodeTour 拡張機能：microsoft/codetour
• 実際のツアー：coder/code-server