code-tour

code-tour skillの概要

code-tourで作成できるもの

code-tour skillは、AIエージェントがVS CodeのCodeTour拡張機能向けに、CodeTourの.tour JSONファイルを作成するためのスキルです。ツアーは、説明ステップを実際のファイルや行番号に紐づけたガイド付きウォークスルーで、通常は.tours/配下に保存します。このスキルはコード編集ではなく、構造化されたリポジトリ探索のために設計されています。中核となる制約は、ツアーファイルだけを作成し、ソースコードは変更しないことです。

Technical Writingとオンボーディングに向いているケース

code-tourは、オンボーディング手順、コントリビューター向けガイド、アーキテクチャ解説、PRレビュー用ツアー、セキュリティレビューの確認経路、原因分析の追跡、あるいは「この仕組みがどう動くか」を説明するウォークスルーが必要なTechnical Writingに適しています。特に、読み手のペルソナが明確な場合に力を発揮します。たとえば、新任のバックエンドエンジニア、フロントエンドメンテナー、レビュー担当者、インシデント対応者、スタッフエンジニア、実装の詳細を順序立てて把握したい非エンジニアのステークホルダーなどです。

汎用プロンプトより優れている点

汎用プロンプトでは、ファイルの内容を大まかに要約するだけになりがちです。code-tour skillは、ペルソナに合わせた説明ステップと、具体的なファイル・行番号のアンカーを持つ、実際に使える成果物の作成へエージェントを導きます。これは重要です。ツアーはVS Code上で移動可能でなければならず、実在するパスを参照し、それぞれの立ち寄り箇所がなぜ重要なのかを説明する必要があります。有用な出力は「このリポジトリに何が含まれているか」ではなく、「この読み手が最初にどこをクリックし、次にどこへ進み、なぜそこを見るべきなのか」です。

インストール前に確認したい採用上のポイント

このスキルには、焦点を絞ったSKILL.mdがあり、追加のスクリプト、ルール、参照パックは含まれていません。そのためcode-tour installは軽量ですが、出力品質はリポジトリへのアクセス状況とプロンプトの具体性に大きく左右されます。エージェントがファイルツリー、README、設定ファイル、ソースのエントリーポイントを確認できる場合に最も効果的です。文章だけのドキュメント、Mermaid図、ソースコード編集、あるいはエージェントが読めないファイルに対するツアーを求めている場合には向いていません。

code-tour skillの使い方

code-tour installとリポジトリコンテキスト

使用しているskillsツールで、たとえば次のようにソースリポジトリからインストールします。

npx skills add alirezarezvani/claude-skills --skill code-tour

インストール後、必要に応じてスキルのパスを確認します: engineering/code-tour/skills/code-tour/SKILL.md。対象プロジェクトでは、下書きを作成する前に、エージェントがまずルートディレクトリ、README.md、パッケージまたはビルド設定、上位1〜2階層のフォルダを確認するべきです。ツアーはVS Code CodeTour拡張機能と互換性のある.tour JSONファイルとして、.tours/配下に保存します。

このスキルに必要な入力

質の高いcode-tour usageのために、次の5点を指定します。対象読者、目的、範囲、希望する深さ、必ず含めたいファイルや機能名です。弱い依頼の例は「このリポジトリのツアーを作って」です。強い依頼の例は、「新任のバックエンドエンジニア向けに、ログインのリクエストライフサイクルを説明するCodeTourを作成してください。ルート登録からバリデーション、サービスロジック、データベースアクセス、エラーハンドリングまでを対象にします。8〜12ステップに収め、各ステップを実在するファイルと行番号に紐づけてください。」です。

Technical Writing向けのツアーであれば、公開目的も追加します。たとえば、オンボーディングドキュメント、リリースノートの補助、社内アーキテクチャガイド、レビュー支援、インシデントからの学習資料などです。

最初のツアーにおすすめの進め方

いきなり書き始めるのではなく、まず発見から始めます。プロジェクトの目的、使用言語、フレームワーク、エントリーポイント、重要なディレクトリをエージェントに特定させます。次に、物語としてたどる経路を選びます。たとえば、セットアップから最初の機能まで、リクエストからレスポンスまで、UI操作からAPIまで、バグ症状から根本原因まで、PR差分からリスクまで、などです。その後で初めて.tourファイルを生成します。この順序にすることで、壊れたアンカーを減らし、ディレクトリ名を並べるだけで仕組みを教えない浅い「フォルダツアー」を防げます。

実用的なプロンプト例

次のようなプロンプトを使います。

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

この書き方が有効なのは、単なるトピックではなく、エージェントが判断するための枠組みを与えているからです。

code-tour skill FAQ

ドキュメントではなくcode-tourを使うべきタイミング

コード内をたどる体験そのものが成果物になる場合は、code-tourを使います。従来型のドキュメントは、概念、ポリシー、APIリファレンスに向いています。一方でCodeTourは、読み手がファイルを順番に開き、ルート、サービス、テスト、設定、エントリーポイントの関係を理解する必要がある場合に適しています。

初心者でもcode-tour skillを使えるか

はい。ただし初心者は依頼範囲を絞るべきです。まずは小さなツアーを依頼します。対象は1つの機能、1つのバグ経路、またはアーキテクチャの一部分に限定します。「コードベース全体を説明して」のような広すぎる依頼は、リポジトリが非常に小さくない限り、ノイズの多いツアーになりがです。ソースファイルが数個未満のごく小さなリポジトリであれば、短時間で全体像を追うツアーでも十分なことが多いです。

code-tourはアプリケーションコードを編集するか

いいえ。想定される出力は.tour JSONファイルで、通常は.tours/に配置します。このスキルの明確な境界は、ソースコードを変更しないことです。コード修正、テスト、リファクタリングが必要なワークフローでは、先に別のエンジニアリング系スキルを使い、その後でcode-tourを使って結果としての経路をドキュメント化してください。

良いcode-tour結果を妨げる要因

最大の阻害要因は、リポジトリにアクセスできないこと、対象読者が曖昧なこと、範囲制限がないこと、ファイルパスが検証されていないことです。CodeTourのステップは実在するアンカーに依存します。エージェントが対象ファイルを読めない場合や、活発な編集で行番号が大きく変わる場合は、コードが安定してからツアーを生成するか、まずパス単位のアンカーを作成し、行番号は後で精査するよう依頼します。

code-tour skillを改善する方法

code-tourプロンプトをペルソナ別にする

code-tourの出力を改善する最短の方法は、読み手を具体的に指定することです。「新しいコントリビューター」と「セキュリティレビュー担当者」や「オンボーディング資料を準備するテクニカルライター」では、たどるべき経路が変わります。読み手がすでに知っていることと、ツアー後にできるようになるべきことを含めてください。これにより、ステップの選び方、説明の深さ、語彙が変わります。

一覧ではなくストーリーを求める

弱いツアーはファイルを列挙します。強いツアーは、実行がどこから始まり、データがどう流れ、どこで判断が行われ、どこにリスクがあり、どのテストが挙動を保証しているかを物語として示します。各ステップを前のステップとつなげ、ステップごとに「なぜこれが重要か」を1文入れるようエージェントに依頼してください。これはTechnical Writingでは特に有用です。最終成果物が、単にクリックできるだけでなく、教えられる資料になるからです。

初回出力のあとに反復する

最初の.tour下書きができたら、3点を確認します。壊れている、または不正確なファイルパスがないか。ステップが広すぎないか。ステップ間のつながりが抜けていないか。そのうえで、狙いを絞った修正を依頼します。たとえば、「step 4をrouteとserviceのステップに分けてください」「この挙動をカバーするtestを追加してください」「frontendの詳細を減らし、API error handlingに集中してください」のように依頼します。一度で完璧な全リポジトリツアーを求めるより、反復したほうが多くの場合効果的です。

共有前にアンカーを検証する

CodeTourを公開する前に、VS CodeでCodeTour拡張機能を使って開き、すべてのパスと行番号が意図した場所に着地することを確認します。リポジトリの変更が多い場合は、安定したアーキテクチャファイル、テスト、エントリーポイントに紐づくツアーを優先し、大きなリファクタリング後には行番号を再生成します。これにより、code-tour skillを古い地図ではなく、オンボーディング資産として使い続けられます。