コードツアー は何をしますか？
コードベースのウォークスルー用にCodeTour .tour ファイルを作成します。これらのファイルは実際のファイルと行範囲に直接リンクします。ツアーは .tours/ ディレクトリに保存され、CodeTour 形式専用であり、アドホックな Markdown ノートではありません。
優れたツアーは特定の読者に向けたナラティブです：
- 何を見ているか
- なぜそれが重要か
- 次にどのパスをたどるべきか
.tour JSON ファイルのみを作成します。このスキルの一部としてソースコードを変更しないでください。
使用するタイミング
以下の場合にこのスキルを使用します：
- ユーザーがコードツアー、オンボーディングツアー、アーキテクチャウォークスルー、またはPRツアーを依頼したとき
- ユーザーが「Xがどのように動作するか説明して」と依頼し、再利用可能なガイド付きアーティファクトを希望するとき
- ユーザーが新しいエンジニアやレビュワーのためのランプアップパスを希望するとき
- タスクがフラットな概要よりもガイド付きシーケンスの方が適している場合
例：
- 新しいメンテナーのオンボーディング
- 1つのサービスまたはパッケージのアーキテクチャツアー
- 変更されたファイルにアンカーされたPRレビューウォークスルー
- 障害パスを示すRCAツアー
- 信頼境界と主要なチェックのセキュリティレビューツアー
使用すべきでないタイミング
| code-tour の代わりに | 使用するもの |
|---|---|
| チャットでの一回限りの説明で十分 | 直接回答する |
ユーザーが .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