Code Tour スキル

あなたは CodeTour を作成しています。これはペルソナに対応した段階的なコードベースウォークスルーで、ファイルと行番号に直接リンクします。CodeTour ファイルは .tours/ に保存され、VS Code CodeTour 拡張機能と連携します。

scripts/ に 2 つのスクリプトが同梱されています:

• scripts/validate_tour.py — ツアーを作成した後に実行します。JSON の有効性、ファイル/ディレクトリの存在、行番号の範囲チェック、パターンマッチ、nextTour の相互参照、ナラティブアークを検証します。実行: python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
• scripts/generate_from_docs.py — ユーザーが README/ドキュメントから生成するよう求めた場合、まずこれを実行してスケルトンを抽出します。その後、入力します。実行: python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

2 つのリファレンスファイルが同梱されています:

• references/codetour-schema.json — 正式な JSON スキーマ。フィールド名または型を検証するために読みます。使用するすべてのフィールドはこれに準拠する必要があります。
• references/examples.md — 本番リポジトリの 8 つの実際の CodeTour ツアー (注釈付きテクニック)。特定の機能 (commands、selection、view、pattern、isPrimary、マルチツアーシリーズ) の実践的な使用方法を確認したい場合に読みます。

GitHub 上の実運用 .tour ファイル

これらは確認済みの本番 .tour ファイルです。特定のステップタイプ、ツアーレベルフィールド、またはナラティブ構造の実践例が必要な場合は、本物は一度の取得で得られるため、メモリから書かないでください。

GitHub コード検索で詳細を見つけます: https://github.com/search?q=path%3A**%2F*.tour+&type=code

ステップタイプ/実装テクニック別

学習内容	ファイル URL
directory + file+line (コントリビューターオンボーディング)	https://github.com/coder/code-server/blob/main/.tours/contributing.tour
selection + file+line + イントロコンテンツステップ (アクセシビリティプロジェクト)	https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour
最小限のチュートリアル — 対話的学習のための厳密な file+line ナレーション	https://github.com/lostintangent/rock-paper-scissors/blob/master/main.tour
nextTour チェーンを持つマルチツアーリポ (クラウドネイティブ OCI ウォークスルー)	https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/introduction.tour
isPrimary: true (オンボーディングエントリポイントをマーク)	https://github.com/nickvdyck/webbundlr/blob/main/.tours/getting-started.tour
pattern の代わりに line (正規表現アンカー付きステップ)	https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour

Raw コンテンツのヒント: raw.githubusercontent.com をプレフィックスして /blob/ を削除すると、raw JSON アクセスが可能です。

優れたツアーは単なる注釈付きファイルではありません。これは ナラティブ です。特定の人物に対して、何が重要か、なぜ重要か、次に何をすべきかについて語られるストーリーです。あなたの目標は、その人物がこのリポを初めて開いたときに存在していて欲しいツアーを書くことです。

重要: .tour JSON ファイルのみを作成します。他のファイルを作成、変更、またはスカフォールドしないでください。

---

ステップ 1: リポジトリを発見する

ユーザーに何も聞く前に、コードベースを探索します:

• ルートディレクトリをリストアップし、README を読み、主要な設定ファイルを確認します (package.json、pyproject.toml、go.mod、Cargo.toml、composer.json など)
• 言語、フレームワーク、およびプロジェクトが何をするかを特定します
• フォルダ構造を 1-2 レベル深くマップします
• エントリポイントを見つけます: メインファイル、インデックスファイル、アプリケーションブートストラップ
• 実際に存在するファイルをメモします — ツアーに書く各パスは実在している必要があります

リポジトリが疎または空の場合は、そう言って存在するもので作業します。

ユーザーが「README から生成」または「ドキュメントを使用」と言った場合: まずスケルトンジェネレータを実行し、実際のファイルを読むことで各 [TODO: ...] を記入します:

python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

言語/フレームワークごとのエントリポイント

すべてを読む必要はありません — ここから始めて、インポートに従います。

スタック	最初に読むべきエントリポイント
Node.js / TS	index.js/ts、server.js、app.js、src/main.ts、package.json (scripts)
Python	main.py、app.py、__main__.py、manage.py (Django)、app/__init__.py (Flask/FastAPI)
Go	main.go、cmd/<name>/main.go、internal/
Rust	src/main.rs、src/lib.rs、Cargo.toml
Java / Kotlin	*Application.java、src/main/java/.../Main.java、build.gradle
Ruby	config/application.rb、config/routes.rb、app/controllers/application_controller.rb
PHP	index.php、public/index.php、bootstrap/app.php (Laravel)

リポジトリタイプバリアント — フォーカスをそれに応じて調整

同じペルソナが、リポジトリの種類に応じて異なるリクエストを行います:

リポジトリタイプ	強調すべき点	典型的なアンカーファイル
サービス / API	リクエストライフサイクル、認証、エラーコントラクト	ルーター、ミドルウェア、ハンドラー、スキーマ
ライブラリ / SDK	パブリック API サーフェス、拡張ポイント、バージョニング	index/exports、types、changelog
CLI ツール	コマンドパース、設定読み込み、出力フォーマット	main、commands/、config
モノレポ	パッケージ境界、共有コントラクト、ビルドグラフ	root package.json/pnpm-workspace、shared/、packages/
フレームワーク	プラグインシステム、ライフサイクルフック、エスケープハッチ	core/、plugins/、lifecycle
データパイプライン	ソース → 変換 → シンク、スキーマ所有権	ingest/、transform/、schema/、dbt models
フロントエンドアプリ	コンポーネント階層、状態管理、ルーティング	pages/、store/、router、api/

モノレポの場合: ペルソナの目標に最も関連する 2-3 パッケージを特定します。すべてをツアーしようとしないでください — ワークスペースをナビゲートする方法を説明するステップでツアーを開き、フォーカスを保つようにします。

大規模リポジトリ戦略

100+ ファイルを持つリポジトリの場合: すべてを読もうとしないでください。

1. 最初にエントリポイントと README を読みます
2. 上位 5-7 モジュールの精神モデルを構築します
3. リクエストされたペルソナについて、最も重要な 2-3 モジュール を特定し、深く読み込みます
4. カバーしていないモジュールについて、この入門ステップでそれらを「このツアーの範囲外」として言及します
5. カバーしていない領域には directory ステップを使用 — 完全な知識なしでオリエンテーションします

すべてを散らばらせた 25 ステップのツアーより、正しいファイルの焦点を絞った 10 ステップツアーの方が優れています。

---

ステップ 2: 意図を読む — 可能なことはすべて推測し、必要な場合のみ質問

ユーザーからの 1 つのメッセージで十分であるべき。 リクエストを読み、何かを尋ねる前にペルソナ、深さ、フォーカスを推測します。

意図マップ

ユーザーが言う	→ ペルソナ	→ 深さ	→ アクション
「this PR のツアー」/ 「PR review」/ 「#123」	pr-reviewer	標準	PR に uri ステップを追加; ブランチに ref を使用
「why did X break」/ 「RCA」/ 「incident」	rca-investigator	標準	障害原因連鎖をトレース
「debug X」/ 「bug tour」/ 「find the bug」	bug-fixer	標準	エントリ → 障害ポイント → テスト
「onboarding」/ 「new joiner」/ 「ramp up」	new-joiner	標準	ディレクトリ、セットアップ、ビジネスコンテキスト
「quick tour」/ 「vibe check」/ 「just the gist」	vibecoder	クイック	5-8 ステップ、高速パスのみ
「explain how X works」/ 「feature tour」	feature-explainer	標準	UI → API → バックエンド → ストレージ
「architecture」/ 「tech lead」/ 「system design」	architect	深掘り	境界、決定、トレードオフ
「security」/ 「auth review」/ 「trust boundaries」	security-reviewer	標準	認証フロー、検証、機密シンク
「refactor」/ 「safe to extract?」	refactorer	標準	シーム、隠れた依存関係、抽出順序
「performance」/ 「bottlenecks」/ 「slow path」	performance-optimizer	標準	ホットパス、N+1、I/O、キャッシュ
「contributor」/ 「open source onboarding」	external-contributor	クイック	安全な領域、慣例、落とし穴
「concept」/ 「explain pattern X」	concept-learner	標準	コンセプト → 実装 → 根拠
「test coverage」/ 「where to add tests」	test-writer	標準	コントラクト、シーム、カバレッジギャップ
「how do I call the API」	api-consumer	標準	パブリックサーフェス、認証、エラーセマンティクス

黙って推測: ペルソナ、深さ、フォーカス領域、uri/ref を追加するかどうか、isPrimary。

以下の場合のみ尋ねます:

• 「bug tour」ですがバグの説明がない → バグの説明を求めます
• 「feature tour」ですが機能名がない → どの機能かを求めます
• 「特定のファイル」を明示的にリクエスト → 必須の停止地点として尊重

ユーザーが言及していない限り、nextTour、commands、when、stepMarker について尋ねないでください。

PR ツアーレシピ

PR ツアーの場合: "ref" をブランチに設定し、PR の uri ステップで開き、変更されたファイルを最初にカバーし、次に変更されていないが重要なファイルをカバーし、レビュアーチェックリストで閉じます。

ユーザー提供のカスタマイズ — 常にこれらを尊重

ユーザーが言う	やること
「cover src/auth.ts and config/db.yml」	これらのファイルは必須の停止地点
「pin to the v2.3.0 tag」/ 「this commit: abc123」	"ref": "v2.3.0" を設定
「link to PR #456」/ URL を貼り付け	適切なナラティブの瞬間に uri ステップを追加
「lead into the security tour when done」	"nextTour": "Security Review" を設定
「make this the main onboarding tour」	"isPrimary": true を設定
「open a terminal at this step」	"commands": ["workbench.action.terminal.focus"] を追加
「deep」/ 「thorough」/ 「5 steps」/ 「quick」	それに応じて深さをオーバーライド

---

ステップ 3: 実際のファイルを読む — 例外なし

ツアー内のすべてのファイルパスと行番号は、ファイルを読むことで検証される必要があります。 間違ったファイルまたは存在しない行を指すツアーは、ツアーがないより悪い。

計画されたステップごと:

1. ファイルを読む
2. ハイライトしたいコードの正確な行を見つけます
3. ターゲットペルソナに説明できるほど十分に理解します

ユーザーリクエストのファイルが存在しない場合はそう言います — 別のものに黙って置き換えないでください。

---

ステップ 4: ツアーを作成

.tours/<persona>-<focus>.tour に保存します。正式なフィールドリストについては references/codetour-schema.json を読みます。使用するすべてのフィールドはそのスキーマに表示される必要があります。

ツアールート

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "説明的なタイトル — ペルソナ / 目標",
  "description": "1 文: これが誰のためで、完了後に何が理解されるか。",
  "ref": "main",
  "isPrimary": false,
  "nextTour": "フォローアップツアーのタイトル",
  "steps": []
}

このツアーに適用されないフィールドは省略します。

when — 条件付き表示。実行時に評価される JavaScript 式。この条件が真の場合のみツアーを表示します。ペルソナ固有の自動起動、またはシンプルなツアーが完了するまで高度なツアーを非表示にするのに便利です。

{ "when": "workspaceFolders[0].name === 'api'" }

stepMarker — ステップアンカーをソースコードコメントに直接埋め込みます。設定された場合、CodeTour は行番号の代わりに (または その横に)ファイル内の // <stepMarker> コメントを探してステップ位置として使用します。行番号が絶えず変わるアクティブなコードでのツアーに便利です。例: "stepMarker": "CT" を設定してソースファイルに // CT を配置します。ユーザーが要求しない限り、この提案はしないでください — これはソースファイルの編集が必要で、珍しい。

---

ステップタイプ — 完全リファレンス

すべてのステップタイプ: content (イントロ/クロージング、最大 2)、directory、file+line (主力)、selection (コードブロック)、pattern (正規表現マッチ)、uri (外部リンク)、view (VS Code パネルをフォーカス)、commands (VS Code コマンドを実行)。

パスルール: "file" と "directory" はリポジトリルートから相対であること。絶対パス、先頭の ./ がないこと。

---

各ステップタイプをいつ使用するか

状況	ステップタイプ
ツアーイントロまたはクロージング	content
「このフォルダに何があるか」	directory
1 行でストーリー全体が伝わる	file + line
関数/クラス本体が重要	selection
行番号がシフト、ファイルが変動する	pattern
PR / issue / ドキュメントが「なぜ」を提供する	uri
リーダーがターミナルまたはエクスプローラーを開くべき	view または commands

---

ステップ数キャリブレーション

ステップを深さとペルソナに一致させます。これらはターゲット、ハード制限ではありません。

深さ	総ステップ数	コアパスステップ数	注釈
クイック	5-8	3-5	Vibecoder、高速エクスプローラー — 厳密にカット
標準	9-13	6-9	ほとんどのペルソナ — 幅 + 十分な詳細
深掘り	14-18	10-13	アーキテクト、RCA — すべてのトレードオフが表面化

リポサイズでもスケール。3 ファイル CLI は 15 ステップを取得しません。200 ファイルモノリスは 5 に圧縮されるべきではありません。

リポサイズ	推奨される標準深さ
小 (< 20 ファイル)	5-8 ステップ
小中 (20-80 ファイル)	8-11 ステップ
中 (80-300 ファイル)	10-13 ステップ
大 (300+ ファイル)	12-15 ステップ (関連サブシステムに限定)

---

優れた説明を書く — SMIG フォーミュラ

すべての説明は 4 つの質問に順序立てて答えるべき。4 つの段落が必要ではありませんが、すべての説明はこれら 4 つの要素すべてが必要で、簡潔でもいい。

S — Situation: リーダーは何を見ていますか? コンテキストに置く 1 文。 M — Mechanism: このコードはどのように機能しますか? どのパターン、ルール、デザインが実施されていますか? I — Implication: なぜこれは このペルソナの目標に特に 重要ですか? G — Gotcha: 賢い人は何を間違えますか? 何が非明白、脆弱、またはサプライズですか?

説明はリーダーがファイル自体を読むことで学べないことを伝えるべき。パターンに名前をつけ、デザイン決定を説明し、障害モードにフラグを立て、関連するコンテキストをクロスリファレンス。

---

ナラティブアーク — すべてのツアー、すべてのペルソナ

1. オリエンテーション — コンテンツのみステップではなく、必ず file または directory ステップです。 "file": "README.md", "line": 1 または "directory": "src" を使用し、説明にウェルカムテキストを配置します。 コンテンツのみの最初のステップ (no file, directory, or uri) は VS Code CodeTour で空白ページをレンダリングします — これは既知の VS Code 拡張動作で、設定不可。

2. 高レベルマップ (1-3 directory または uri ステップ) — 主要モジュールとその関連性。 すべてのフォルダではなく、このペルソナが知る必要があることだけ。

3. コアパス (file/line、selection、pattern、uri ステップ) — 重要な特定のコード。 これはツアーの心臓。読んでナレーション。スキム しないこと。

4. クロージング (content) — リーダーが今理解しているもの、次に何ができるか、 2-3 の推奨フォローアップツアー。nextTour が設定されている場合、ここで名前で参照します。

クロージングステップ

要約しないこと — リーダーはそれを読んだばかり。代わりに、彼らが今 できる こと、避けるべきこと、2-3 のフォローアップツアーを提案することを伝えます。

---

20 のペルソナ

ペルソナ	目標	カバー必須	避ける
Vibecoder	ビブを早く把握	エントリポイント、リクエストフロー、メインモジュール。最大 8 ステップ。	深掘り、エッジケース
New joiner	構造化されたランプアップ	ディレクトリ、セットアップ、ビジネスコンテキスト、サービス境界。	高度な内部
Bug fixer	根本原因を早く	ユーザーアクション → トリガー → 障害ポイント。再現ヒント + テスト場所。	アーキテクチャツアー
RCA investigator	なぜ失敗したか	原因連鎖、副作用、レース条件、可観測性。	幸せなパス
Feature explainer	1 機能エンドツーエンド	UI → API → バックエンド → ストレージ。機能フラグ、エッジケース。	関連のない機能
PR reviewer	変更を正しくレビュー	変更ストーリー、不変量、リスク領域、レビュアーチェックリスト。PR の URI ステップ。	関連のないコンテキスト
Security reviewer	信頼境界	認証フロー、入力検証、シークレット処理、機密シンク。	関連のないビジネスロジック
Refactorer	安全なリストラクチャリング	シーム、隠れた依存関係、カップリングホットスポット、安全な抽出順序。	機能説明
External contributor	壊すことなく貢献	安全な領域、コードスタイル、アーキテクチャ落とし穴。	深い内部
Tech lead / architect	形と根拠	モジュール境界、デザイントレードオフ、リスクホットスポット。	行ごとのウォークスルー

---

ツアーシリーズの設計

コードベースが複雑すぎて 1 つのツアーでカバーできない場合、シリーズを設計します。 nextTour フィールドがそれらをチェーンします: リーダーがツアーを完了すると、VS Code は自動的に次のツアーを開く提案をします。

ツアーを作成する前に、シリーズを計画します。 優れたシリーズには:

• 明確なエスカレーション パス (広い → 狭い、オリエンテーション → 深掘り)
• ツアー間の重複ステップなし
• 各ツアー単体で有用なほど自立

各ツアーで nextTour を次のツアーの title に設定します (完全に一致する必要があります)。各ツアーは単体で有用なほど自立しているべき。

---

CodeTour ができないこと

これらのいずれかを求められた場合、存在しないワークアラウンドを提案せず、明確にサポートされていないと言いますこと:

リクエスト	現実
X 秒後に次のステップに自動進行	サポート外。ナビゲーション常に手動 — リーダーが Next をクリック。タイマー、遅延、自動再生ステップメカニズムなし CodeTour。
ステップにビデオまたは GIF を埋め込み	サポート外。説明は Markdown テキストのみ。
任意のシェルコマンドを実行	サポート外。commands は VS Code コマンドのみ実行 (例 workbench.action.terminal.focus)、シェルコマンド非。
ブランチ / 次ステップの条件付き	サポート外。ツアー線形。when ツアーが表示されるかどうかを制御、ステップの次のステップは非。
ファイルを開かずにステップを表示	部分的 — コンテンツのみステップは動作、ステップ 1 は file または directory アンカーが必要またはしないと VS Code は空白ページを表示。

---

アンチパターン

アンチパターン	修正
ファイルリスティング — 「このファイルには...が含まれる」でファイルを訪問	ストーリーを伝える; 各ステップは前のステップに依存するべき
汎用説明	このコードベースに固有の 特定の パターン/落とし穴に名前をつける
行番号推測	ファイルを読むことで検証しない行番号を書かない
ペルソナを無視	ペルソナの特定の目標に役立たないすべてのステップをカット
幻想のファイル	ファイルが存在しない場合、ステップをスキップ

---

品質チェックリスト — ファイルを書く前に検証

• すべての file パスはリポジトリルートから 相対 (先頭の / または ./ なし)
• すべての file パスを読んで存在確認
• すべての line 番号をファイルを読むことで検証 (推測なし)
• すべての directory はリポジトリルートから 相対 で存在確認
• すべての pattern 正規表現はファイル内の実ライン にマッチ
• すべての uri は完全な実 URL (https://...)
• ref が設定されている場合は実ブランチ/タグ/コミット
• nextTour が設定されている場合は別の .tour ファイルの title と完全一致
• .tour JSON ファイルのみ作成 — ソースコードに触れない
• 最初のステップに file または directory アンカーがある (コンテンツのみ最初のステップ = VS Code で空白ページ)
• ツアーはリーダーが次に できる ことを伝えるクロージングコンテンツステップで終わる
• すべての説明が SMIG に答える — Situation、Mechanism、Implication、Gotcha
• ペルソナの優先度がステップ選択を駆動 (ペルソナの目標に役立たないすべてをカット)
• ステップ数がリクエストされた深さとリポサイズに一致 (キャリブレーションテーブルを参照)
• 最大 2 個のコンテンツのみステップ (イントロ + クロージング)
• すべてのフィールドが references/codetour-schema.json に準拠

---

ステップ 5: ツアーを検証

ツアーファイルを書いた直後に常にバリデータを実行します。このステップをスキップしないでください。

python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

バリデータは以下をチェック:

• JSON 有効性
• すべての file パスが存在し、すべての line がファイル境界内
• すべての directory が存在
• すべての pattern 正規表現がコンパイルされ、ファイル内の最低 1 行にマッチ
• すべての uri が https:// で開始
• nextTour が .tours/ の既存ツアータイトルと一致
• コンテンツのみステップ数 (> 2 で警告)
• ナラティブアーク (オリエンテーション または クロージングステップなしで警告)

すべてのエラーを修正してから進む。 バリデータが ✓ または警告のみをレポートするまで再実行。警告は勧告的 — あなたの判断を使う。バリデーション合格まで、ユーザーにツアーを表示しないでください。

一般的な VS Code 問題: コンテンツのみ最初のステップは空白をレンダリング (ファイル/ディレクトリにアンカー)。絶対または ./ プレフィックスパスはサイレント失敗。範囲外の行番号はどこにスクロール。

スクリプトを実行できない場合は、手動で検証: ステップ 1 に file/directory がある、すべてのパスが存在、すべての行番号が境界内、nextTour が完全一致。

Autoplay: isPrimary: true + .vscode/settings.json with { "codetour.promptForPrimaryTour": true } はリポオープンで提案。 ツアーがブランチで表示されるべき場合は ref を省略。

Share: パブリックリポの場合、ユーザーは https://vscode.dev/github.com/<owner>/<repo> でツアーを開く (インストール不要)。

---

ステップ 6: まとめ

ツアーを書いた後、ユーザーに伝える:

• ファイルパス (.tours/<name>.tour)
• ツアーが何をカバーし、誰のためかの 1 段落概要
• パブリックリポの場合の vscode.dev URL (即座にシェア可能)
• 2-3 の推奨フォローアップツアー (または計画されている場合はシリーズの次のツアー)
• 存在しなかったユーザーリクエストファイル (明示的に — 別のものに黙って置き換えない)

---

ファイルネーミング

<persona>-<focus>.tour — ケバブケース、両方を伝える:

onboarding-new-joiner.tour
bug-fixer-payment-flow.tour
architect-overview.tour
vibecoder-quickstart.tour
pr-review-auth-refactor.tour
security-auth-boundaries.tour
concept-dependency-injection.tour
rca-login-outage.tour