コードツアー

CodeTour .tour ファイルを作成して、コードベースの解説を行います。実際のファイルを直接開き、指定された行範囲に移動できます。ツアーファイルは .tours/ ディレクトリに保存され、CodeTour 形式専用であり、一時的な Markdown ノートではありません。

優れたツアーは、特定の読者に向けてストーリーを語るべきです：

• 彼らが何を見ているのか
• それがなぜ重要なのか
• 次にどのパスをたどるべきか

.tour JSON ファイルのみを作成します。このスキルのスコープ内でソースコードを修正しないでください。

いつ使用するか

以下の場合にこのスキルを使用します：

• ユーザーがコード解説、オンボーディング解説、アーキテクチャ解説、または PR 解説をリクエストしている
• ユーザーが「X がどのように機能するか説明して」と言い、再利用可能なガイド付きの成果物を望んでいる
• ユーザーが新しいエンジニアやレビュアーに開始パスを提供したい
• ガイド付きのシーケンスが、平坦なサマリーよりもタスクに適している

例：

• 新しいメンテナーのオンボーディング
• 単一のサービスまたはパッケージのアーキテクチャツアー
• 変更ファイルにアンカーされた PR レビュー用ツアー
• 障害パスを示す根本原因分析用ツアー
• トラストバウンダリと重要なチェックのセキュリティレビュー用ツアー

いつ使用しないか

コードツアーを使用しない場合	代わりに使用
チャットで一度の説明で十分な場合	直接回答
ユーザーが .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. 検証

完了する前に：

• 参照されるすべてのパスが存在する
• すべての行または選択範囲が有効である
• 最初のステップが実際のファイルまたはディレクトリにアンカーされている
• ツアーがファイルの列挙ではなく、一貫したストーリーを語っている

ステップタイプ

コンテンツ

控えめに使用し、通常は終了ステップのみ：

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

最初のステップを純コンテンツにしないでください。

ディレクトリ

読者にモジュールを案内するために使用：

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

ファイル + 行

これはデフォルトステップタイプです：

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }

選択範囲

特定のコードブロックがファイル全体より重要な場合に使用：

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}

パターン

正確な行番号が変わる可能性がある場合に使用：

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }

URI

PR、イシュー、またはドキュメントが必要な場合に使用：

{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }

作成ルール：SMIG

各説明は以下に答えるべきです：

• 状況（Situation）：読者が何を見ているか
• メカニズム（Mechanism）：それがどのように機能するか
• 影響（Impact）：その役割にとって何が重要か
• 落とし穴（Gotchas）：賢い読者が見落とす可能性があることは何か

説明は簡潔で具体的、そして実際のコードに基づいていることを保ちます。

ナラティブ構造

タスクが明確に異なる構造を必要としない限り、このアークを使用します：

1. 位置付け
2. モジュールマップ
3. 核となる実行パス
4. エッジケースまたは落とし穴
5. 終了 / 次のステップ

ツアーはチェックリストではなく、パスのように感じるべきです。

例

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}

アンチパターン

アンチパターン	修正
平坦なファイルリスト	ステップ間に依存関係のあるストーリーを語る
一般的な説明	具体的なコードパスまたはパターンを指摘
推測されたアンカー	各ファイルと行を最初に検証
クイックツアーにステップが多すぎる	決定的に削減
最初のステップが純コンテンツ	最初のステップを実際のファイルまたはディレクトリにアンカー
役割が一致しない	一般的なエンジニアではなく、実際の読者のために作成

ベストプラクティス

• ステップ数はリポジトリサイズと役割深さに比例させる
• 位置付けにはディレクトリステップを、実質的なコンテンツにはファイルステップを使用
• PR ツアーでは、最初に変更されたファイルをカバー
• モノリポの場合、スコープを関連パッケージに限定し、すべてをツアーしない
• 要約ではなく、読者が今何ができるかで終わる

関連スキル

• codebase-onboarding
• coding-standards
• council
• 公式アップストリーム形式：microsoft/codetour