コードツアー は何をしますか？
コードベースのウォークスルー用に、実際のファイルと行範囲に直接ジャンプできる CodeTour .tour ファイルを作成します。ツアーファイルは .tours/ に配置し、CodeTour 形式に従います。アドホックな Markdown メモではありません。
良いツアーは、特定の読者のためのナラティブです：
- 何を見ているのか
- それがなぜ重要なのか
- 次にどのパスをたどるべきか
.tour JSON ファイルのみを作成します。このスキルの一部としてソースコードを変更してはいけません。
使用すべきタイミング
以下の場合にこのスキルを使用します：
- ユーザーがコードツアー、オンボーディングツアー、アーキテクチャウォークスルー、PRツアーを依頼したとき
- ユーザーが「Xの仕組みを説明して」と依頼し、再利用可能なガイド付き成果物を求めているとき
- ユーザーが新しいエンジニアやレビューア向けのランプアップパスを求めているとき
- タスクがフラットな要約よりもガイド付きのシーケンスで表現する方が適しているとき
例：
- 新しいメンテナーをオンボーディングする
- あるサービスやパッケージのアーキテクチャツアー
- 変更ファイルにアンカーを張った PR レビューウォークスルー
- 障害パスを示す RCA ツアー
- 信頼境界と重要なチェックを示すセキュリティレビューツアー
使用すべきでないタイミング
| コードツアーを使わない場合 | 代わりに使用するもの |
|---|---|
| チャットでの一回限りの説明で十分な場合 | 直接回答する |
ユーザーが .tour 成果物ではなく散文のドキュメントを求めている場合 | documentation-lookup またはリポジトリのドキュメント編集 |
| タスクが実装やリファクタリングの場合 | 実装作業を行う |
| ツアー成果物なしで広範なコードベースオンボーディングを行う場合 | codebase-onboarding |
ワークフロー
1. 発見
何かを書く前にリポジトリを探索します：
- README とパッケージ/アプリのエントリポイント
- フォルダ構造
- 関連する設定ファイル
- ツアーが PR に焦点を当てている場合は、変更されたファイル
コードの構造を理解する前にステップを書き始めてはいけません。
2. 読者を推測する
リクエストからペルソナと深さを決定します。
| リクエストの形状 | ペルソナ | 推奨ステップ数 |
|---|---|---|
| 「オンボーディング」「新規メンバー」 | new-joiner | 9-13 ステップ |
| 「クイックツアー」「感触を確かめたい」 | vibecoder | 5-8 ステップ |
| 「アーキテクチャ」 | architect | 14-18 ステップ |
| 「このPRのツアー」 | pr-reviewer | 7-11 ステップ |
| 「なぜ壊れたのか」 | rca-investigator | 7-11 ステップ |
| 「セキュリティレビュー」 | security-reviewer | 7-11 ステップ |
| 「この機能の仕組みを説明して」 | feature-explainer | 7-11 ステップ |
| 「このパスをデバッグして」 | bug-fixer | 7-11 ステップ |
3. アンカーを読み、検証する
すべてのファイルパスと行アンカーは実際に存在する必要があります：
- ファイルが存在することを確認する
- 行番号が範囲内であることを確認する
- 選択範囲を使用する場合は、正確なブロックを確認する
- ファイルが変動しやすい場合は、パターンベースのアンカーを推奨する
行番号を推測してはいけません。
4. .tour を書く
以下の場所に書き込みます：
.tours/<persona>-<focus>.tour
パスは決定論的で読みやすいものに保ちます。
5. 検証する
終了する前に：
- 参照されているすべてのパスが存在すること
- すべての行または選択範囲が有効であること
- 最初のステップが実際のファイルまたはディレクトリにアンカーされていること
refがツアーが参照するすべてのファイルを実際に持つブランチまたはコミットを指していること（下記参照）- ツアーがファイルを列挙するのではなく、一貫性のあるストーリーを語っていること
ref フィールド
ref はツアーを git ブランチまたはコミットに紐付けます。見た目以上に重要です：ref が読者がチェックアウトしているブランチと異なる場合、CodeTour は各ステップのファイルをディスク上のファイルではなく、そのリビジョンの git から開きます。そのリビジョンにファイルが存在しない場合、ステップは開かれません——読者は「エディタを開けませんでした。ファイルが見つかりませんでした」というメッセージを目にすることになります。実際にはファイルはすぐそこにあるにもかかわらずです。ツアーとそのコメントは表示されるため、本当の原因を見逃しがちです。
ツアーの種類に応じて ref を選びます：
| ツアーの種類 | ref の設定値 |
|---|---|
| PR ツアー | PR ブランチ — ベースブランチにしてはいけません |
| オンボーディング / アーキテクチャ | 読者がいるであろうブランチ（多くの場合 main）、または省略する |
| 不明な場合 | ref を省略し、CodeTour がディスクから直接ファイルを読み込むようにする |
PR のケースはよくある落とし穴です：PR は通常新しいファイルを追加し、新しいファイルはベースブランチにはまだ存在しません。ref をベース（例：develop）に設定すると、新しいファイルのすべてのステップが開けなくなります。
終了する前に、各ステップのファイルが選択した ref に実際に存在することを確認します。
ステップの種類
コンテンツ
控えめに、通常はクロージングステップのみに使用します：
{ "title": "次のステップ", "description": "これでリクエストパスをエンドツーエンドで追跡できます。" }
最初のステップをコンテンツのみにしてはいけません。
ディレクトリ
読者をモジュールに誘導するために使用します：
{ "directory": "src/services", "title": "サービス層", "description": "コアのオーケストレーションロジックはここにあります。" }
ファイル + 行
これがデフォルトのステップタイプです：
{ "file": "src/auth/middleware.ts", "line": 42, "title": "認証ゲート", "description": "すべての保護されたリクエストは最初にここを通過します。" }
選択範囲
ファイル全体よりも特定のコードブロックが重要な場合に使用します：
{
"file": "src/core/pipeline.ts",
"selection": {
"start": { "line": 15, "character": 0 },
"end": { "line": 34, "character": 0 }
},
"title": "リクエストパイプライン",
"description": "このブロックは、検証、認証、および下流の実行を結びつけます。"
}
パターン
正確な行が変動する可能性がある場合に使用します：
{ "file": "src/app.ts", "pattern": "export default class App", "title": "アプリケーションエントリ" }
URI
PR、Issue、ドキュメントなどに便利な場合に使用します：
{ "uri": "https://github.com/org/repo/pull/456", "title": "このPR" }
記述ルール：SMIG
各説明は以下に答える必要があります：
- 状況 (Situation)：読者が何を見ているか
- 仕組み (Mechanism)：どのように動作するか
- 含意 (Implication)：このペルソナにとってなぜ重要か
- 見落としがちな点 (Gotcha)：賢い読者が見逃しそうなこと
説明はコンパクトで具体的に、実際のコードに基づいて記述します。
ナラティブの形
タスクが明確に別の形を必要としない限り、この流れを使用します：
- オリエンテーション
- モジュールマップ
- コア実行パス
- エッジケースまたは見落としがちな点
- クロージング / 次のアクション
ツアーは、目録ではなく、パスのように感じられるべきです。
例
{
"$schema": "https://aka.ms/codetour-schema",
"title": "API サービスツアー",
"description": "決済サービスのリクエストパスのウォークスルー。",
"ref": "main",
"steps": [
{
"directory": "src",
"title": "ソースルート",
"description": "サービスのすべてのランタイムコードはここから始まります。"
},
{
"file": "src/server.ts",
"line": 12,
"title": "エントリポイント",
"description": "サーバーはここで起動し、任意のルートに到達する前にミドルウェアを配線します。"
},
{
"file": "src/routes/payments.ts",
"line": 8,
"title": "決済ルート",
"description": "すべての決済リクエストは、サービスロジックに到達する前にこのルーターを通過します。"
},
{
"title": "次のステップ",
"description": "これで、主要なアンカーを使用して任意の決済リクエストをエンドツーエンドで追跡できます。"
}
]
}
アンチパターン
| アンチパターン | 修正方法 |
|---|---|
| フラットなファイルリスト | ステップ間の依存関係を持つストーリーを語る |
| 一般的な説明 | 具体的なコードパスやパターンを名指しする |
| 推測によるアンカー | すべてのファイルと行を最初に検証する |
| クイックツアーにしてステップが多すぎる | 積極的に削減する |
| 最初のステップがコンテンツのみ | 最初のステップを実際のファイルまたはディレクトリにアンカーする |
| ペルソナの不一致 | 一般的なエンジニアではなく、実際の読者に向けて書く |
ベストプラクティス
- ステップ数はリポジトリのサイズとペルソナの深さに比例させる
- オリエンテーションにはディレクトリステップを、実質的な内容にはファイルステップを使用する
- PR ツアーの場合は、変更されたファイルを最初にカバーする
- モノレポの場合は、すべてをツアーするのではなく、関連するパッケージにスコープを絞る
- まとめではなく、読者が次に何ができるようになったかを示して締めくくる
関連スキル
codebase-onboardingcoding-standardscouncil- 公式アップストリーム形式：
microsoft/codetour