code-tour

Name: code-tour
Author: github

github.com/github開発40.5k731 回インストール1 日前に更新

リポジトリ

code-tour について

リポジトリ内のファイルや行番号にリンクする、対象者別の CodeTour を作成するスキルです。ドキュメントからの草案生成とツアー検証のスクリプトに加え、スキーマと作例を備えています。

主な機能

01対象者別の CodeTour 作成
02手順をファイルと行番号にリンク
03ドキュメントからツアー草案を生成
04パス、行番号、構造の検証
05スキーマと注釈付き作例の参照

活用シーン

01リポジトリのオンボーディングツアー作成
02コードを通じた機能やアーキテクチャの説明
03README やドキュメントからツアー草案を生成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/github/awesome-copilot --skill code-tour

インストール後、Claude Code で/code-tourを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

codetour-schema.json

examples.md

scripts/

generate_from_docs.py

validate_tour.py

詳細

コードツアースキル

CodeTourを作成します。CodeTourは、対象となるユーザーに合わせてコードベースを段階的に案内し、ファイルや行番号に直接リンクするものです。CodeTourファイルは.tours/に配置し、VS Code CodeTour extensionで動作します。

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

references/には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
`line`の代わりに`pattern`を使用（正規表現を基準とするステップ）	https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour

生データを取得する方法： raw.githubusercontent.comを先頭に付け、/blob/を削除すると、生の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を超えるリポジトリでは、すべてを読もうとしないでください。

まずエントリーポイントとREADMEを読みます
主要なモジュールの上位5～7個について、全体像をつかみます
対象となるペルソナにとって最も重要な2～3個のモジュールを特定し、詳しく読みます
対象外のモジュールは、「このツアーでは対象外」として導入ステップで触れます
全体像を把握したものの読んでいない領域には directory ステップを使います。詳しい知識がなくても、位置づけを把握できます

適切なファイルに絞った10ステップのツアーは、あちこちに散らばった25ステップのツアーよりも有益です。

ステップ2：意図を読み取る — できる限り推測し、推測できないことだけを尋ねる

**ユーザーからのメッセージは1つで十分です。**依頼を読み、質問する前にペルソナ、深さ、注目点を推測してください。

意図のマッピング

ユーザーの発言	→ ペルソナ	→ 詳細度	→ アクション
"tour for this PR" / "PR review" / "#123"	pr-reviewer	standard	PR の `uri` ステップを追加し、ブランチには `ref` を使用します
"why did X break" / "RCA" / "incident"	rca-investigator	standard	障害の因果関係をたどります
"debug X" / "bug tour" / "find the bug"	bug-fixer	standard	エントリーポイント → 障害箇所 → テスト
"onboarding" / "new joiner" / "ramp up"	new-joiner	standard	ディレクトリ、セットアップ、ビジネスコンテキスト
"quick tour" / "vibe check" / "just the gist"	vibecoder	quick	5～8 ステップ、最短経路のみ
"explain how X works" / "feature tour"	feature-explainer	standard	UI → API → バックエンド → ストレージ
"architecture" / "tech lead" / "system design"	architect	deep	境界、設計判断、トレードオフ
"security" / "auth review" / "trust boundaries"	security-reviewer	standard	認証フロー、検証、機密データの送信先
"refactor" / "safe to extract?"	refactorer	standard	境界、隠れた依存関係、抽出順序
"performance" / "bottlenecks" / "slow path"	performance-optimizer	standard	ホットパス、N+1、I/O、キャッシュ
"contributor" / "open source onboarding"	external-contributor	quick	安全な領域、規約、注意点
"concept" / "explain pattern X"	concept-learner	standard	概念 → 実装 → 根拠
"test coverage" / "where to add tests"	test-writer	standard	契約、境界、カバレッジの不足箇所
"how do I call the API"	api-consumer	standard	公開インターフェース、認証、エラーの意味

暗黙に推測します： ペルソナ、詳細度、注目領域、uri／ref を追加するかどうか、isPrimary。

本当に推測できない場合に限り質問します：

"bug tour" だがバグの説明がない → バグの説明を尋ねます
"feature tour" だが機能が指定されていない → どの機能かを尋ねます
「特定のファイル」が明示的に指定されている → 必須の立ち寄り先として扱います

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

PR ツアーの手順

PR ツアーでは、"ref" にブランチを設定し、PR の uri ステップから開始して、まず変更されたファイルを扱い、次に変更されていないものの重要なファイルを扱い、レビュアー向けチェックリストで締めくくります。

ユーザー指定のカスタマイズ — 常に尊重してください

ユーザーの発言	対応
"`src/auth.ts` と `config/db.yml` を取り上げて"	これらのファイルを必須の立ち寄り先にします
"`v2.3.0` タグに固定して" / "このコミット：abc123"	`"ref": "v2.3.0"` を設定します
"PR #456 へのリンクを追加して" / URL を貼り付ける	説明の流れに適した位置に `uri` ステップを追加します
"終わったらセキュリティツアーにつなげて"	`"nextTour": "Security Review"` を設定します
"これをメインのオンボーディングツアーにして"	`"isPrimary": true` を設定します
"このステップでターミナルを開いて"	`"commands": ["workbench.action.terminal.focus"]` を追加します
"deep" / "thorough" / "5 steps" / "quick"	詳細度をそれに応じて上書きします

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

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

予定している各ステップについて：

ファイルを読む
取り上げるコードの正確な行を見つける
対象のペルソナに説明できるだけ十分に理解する

ユーザー指定のファイルが存在しない場合は、その旨を伝えてください。別のファイルで黙って代用してはいけません。

ステップ 4：ツアーを書く

.tours/<persona>-<focus>.tour に保存します。正式なフィールド一覧を確認するには、references/codetour-schema.json を読んでください。使用するすべてのフィールドがそのスキーマに含まれている必要があります。

ツアーのルート

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Descriptive Title — Persona / Goal",
  "description": "One sentence: who this is for and what they'll understand after.",
  "ref": "main",
  "isPrimary": false,
  "nextTour": "Title of follow-up tour",
  "steps": []
}

このツアーに該当しないフィールドは省略してください。

when — 条件付き表示。実行時に評価される JavaScript 式です。条件が true の場合にのみ、このツアーを表示します。ペルソナに応じて自動起動したり、より簡単なツアーを完了するまで高度なツアーを非表示にしたりするのに便利です。

{ "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 つの段落に分ける必要はありませんが、短くてもすべての要素を含めてください。

S — Situation（状況）：読者は何を見ていますか？背景を示す 1 文を添えます。 M — Mechanism（仕組み）：このコードはどのように動作しますか？どのようなパターン、ルール、設計が用いられていますか？ I — Implication（意義）：このペルソナ固有の目標にとって、なぜ重要ですか？ G — Gotcha（注意点）：理解力のある人でも、ここで何を誤解しそうですか？自明でない点、壊れやすい点、意外な点は何ですか？

説明では、ファイルを読むだけではわからないことを読者に伝えてください。パターンに名前を付け、設計上の判断を説明し、障害につながるケースを指摘し、関連する背景情報を相互参照してください。

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

オリエンテーション — 必ず file または directory のステップにしてください。コンテンツのみのステップは使えません。 "file": "README.md", "line": 1 または "directory": "src" を指定し、説明に歓迎のメッセージを書きます。 file、directory、uri のいずれもないコンテンツのみの最初のステップは、VS Code CodeTour で空白ページとして表示されます。これは VS Code 拡張機能の既知の動作であり、設定では変更できません。
概要マップ（ディレクトリまたは uri のステップを 1～3 個）—主要なモジュールと、それらの関連性を示します。すべてのフォルダーを取り上げる必要はありません。このペルソナが知っておくべきことだけを扱います。
中核となる道筋（file/line、selection、pattern、uri のステップ）—重要なコードを具体的に示します。ここがツアーの中心です。読み、説明しましょう。流し読みは禁物です。
締めくくり（コンテンツ）—読者が理解したこと、次にできること、おすすめのフォローアップツアーを 2～3 個紹介します。nextTour が設定されている場合は、ここでその名前を挙げます。

締めくくりのステップ

要約はしないでください。読者は今、それを読んだばかりです。代わりに、これからできること、避けるべきことを伝え、フォローアップツアーを 2～3 個提案します。

20 のペルソナ

ペルソナ	目標	必ず取り上げること	避けること
Vibecoder	雰囲気をすばやくつかむ	エントリーポイント、リクエストの流れ、主要なモジュール。最大 8 ステップ。	詳細な掘り下げ、エッジケース
新規参加者	段階的に理解を深める	ディレクトリ、セットアップ、ビジネス上の背景、サービスの境界。	高度な内部実装
バグ修正担当者	すばやく根本原因を特定する	ユーザー操作 → トリガー → 障害箇所。再現のヒントとテストの場所。	アーキテクチャのツアー
RCA 調査担当者	なぜ失敗したのかを明らかにする	因果関係の連鎖、副作用、競合状態、可観測性。	正常系の流れ
機能解説担当者	1 つの機能を最初から最後まで説明する	UI → API → バックエンド → ストレージ。機能フラグ、エッジケース。	関連のない機能
PR レビュアー	変更を正しくレビューする	変更の経緯、不変条件、リスクの高い箇所、レビュアー向けチェックリスト。PR の uri ステップ。	関連のないコンテキスト
セキュリティレビュアー	信頼境界を確認する	認証の流れ、入力検証、シークレットの取り扱い、機密情報を扱うシンク。	関連のないビジネスロジック
リファクタリング担当者	安全に構造を変更する	分離点、隠れた依存関係、結合のホットスポット、安全な抽出の順序。	機能の説明
外部コントリビューター	既存の動作を壊さずに貢献する	安全に変更できる箇所、コードスタイル、アーキテクチャ上の落とし穴。	内部実装の詳細
テックリード／アーキテクト	方向性と設計の根拠を把握する	モジュールの境界、設計上のトレードオフ、リスクの高い箇所。	1 行ずつの解説

ツアーシリーズの設計

コードベースが複雑で、1 つのツアーでは十分に説明できない場合は、シリーズを設計します。 nextTour フィールドでツアーを連結します。読者がツアーを終えると、VS Code が次のツアーを自動的に開始するよう提案します。

ツアーを書く前に、シリーズを計画してください。 良いシリーズには、次の特徴があります。

明確な段階的展開（広い内容から狭い内容へ、概要から詳細へ）
ツアー間で重複するステップがない
各ツアーが単独でも役立つだけの内容を備えている

各ツアーの nextTour に、次のツアーの title を設定します（完全一致が必要です）。各ツアーは、単独でも役立つだけの内容を備えている必要があります。

CodeTour ではできないこと

以下のいずれかを求められた場合は、サポートされていないことを明確に伝えてください。存在しない回避策を提案してはいけません。

リクエスト	実際の仕様
X 秒後に次のステップへ自動で進む	サポートされていません。ナビゲーションは常に手動で、読者が「次へ」をクリックします。CodeTour にタイマー、遅延、自動再生のステップ機能はありません。
ステップに動画や GIF を埋め込む	サポートされていません。説明に使えるのは Markdown テキストのみです。
任意のシェルコマンドを実行する	サポートされていません。`commands` で実行できるのは VS Code のコマンド（例：`workbench.action.terminal.focus`）のみで、シェルコマンドは実行できません。
分岐／条件付きの次のステップ	サポートされていません。ツアーは直線的です。`when` はツアーを表示するかどうかを制御するもので、次に進むステップを制御するものではありません。
ファイルを開かずにステップを表示する	一部可能です。コンテンツのみのステップは使えますが、ステップ 1 には `file` または `directory` のアンカーが必要です。そうでない場合、VS Code には空白ページが表示されます。

アンチパターン

アンチパターン	修正方法
ファイルの羅列 — 「このファイルには……が含まれています」とファイルを順に訪問する	ストーリーを語ります。各ステップは前のステップを踏まえたものにします
一般的な説明	このコードベース固有のパターンや注意点を具体的に挙げます
行番号の推測	ファイルを読んで確認していない行番号は、決して記載しません
ペルソナの無視	その人の具体的な目標に役立たないステップは、すべて削除します
存在しないファイルの記載	ファイルが存在しない場合、そのステップは省略します

品質チェックリスト — ファイルを書く前に確認する

ステップ 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 が完全に一致することを確かめます。

自動再生： isPrimary: true と .vscode/settings.json の { "codetour.promptForPrimaryTour": true } を設定すると、リポジトリを開いたときにプロンプトが表示されます。どのブランチでも表示するツアーでは ref を省略します。

共有： 公開リポジトリの場合、ユーザーはインストールせずに 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

Markdown 対応

ログインしてコメント

基本情報

作者: github
リポジトリ: github/awesome-copilot
カテゴリ: 開発
インストール数: 731
GitHub スター: 40,516

問題を報告