code-tour

code-tour スキルの概要

code-tour スキルでできること

code-tour スキルは、実際のファイルパスと行範囲を使ってリポジトリ内を案内する、再利用可能な CodeTour の .tour ファイルを生成します。1回きりのチャット説明ではなく、.tours/ にガイド付きの順路として開ける成果物を作るため、CodeTour 対応ツールでそのまま閲覧できます。

最適な利用者と想定タスク

この code-tour スキルは、コードを構造的に案内する必要があるメンテナー、レビュー担当者、テクニカルライターに向いています。たとえば、オンボーディングツアー、アーキテクチャツアー、PR ウォークスルー、RCA の追跡、セキュリティレビュー経路などです。実際の仕事は「リポジトリを要約する」ことではなく、「特定の読者を、適切な順序で適切なファイルへ案内する」ことです。

汎用プロンプトではなく code-tour を選ぶ理由

汎用プロンプトは、コードから切り離された説明文を返しがちです。code-tour は範囲が狭いぶん、永続的に使えるナビゲーションが必要な場面で強みがあります。各ステップが実在のファイルと行範囲を指し、そこに文脈説明と次のステップへの流れが付くからです。Technical Writing、オンボーディング、繰り返し使うレビュー手順では、code-tour は特に効果的です。

インストール前に知っておくべき主な制約

code-tour スキルは .tour の JSON ファイルを作成するだけで、ソースコードの編集、大規模なドキュメント書き換え、気軽な Q&A には向きません。リポジトリに明確なファイル構成があり、依頼の範囲がサービス、機能、インシデントの経路、または PR 差分に絞られているときに最も力を発揮します。「全部を説明して」という依頼には不向きです。

code-tour スキルの使い方

インストール時の前提と最初に読むもの

通常の skills ワークフローで親の skills リポジトリをインストールし、その環境から code-tour を呼び出します。このスキルフォルダでは SKILL.md が唯一のソースファイルなので、まずこれを読みます。補助スクリプトや参照ファイルはないため導入はシンプルですが、良いリポジトリ文脈は自分で与える必要があります。

code-tour スキルに必要な入力

高品質な code-tour を作るには、次の情報を与えてください。

• audience: “new backend engineer,” “security reviewer,” “technical writer”
• goal: onboarding, architecture, PR review, RCA, trust-boundary review
• scope: package, service, feature, or changed files
• output target: .tours/<name>.tour
• repo anchors: key files, entrypoints, modules, or commit/PR context

弱い依頼は: “Make a tour of this repo.”
より強い依頼は: “Create a code-tour for Technical Writing that explains how auth requests flow through src/server.ts, middleware, token validation, and session storage. Keep it to 8–10 stops and optimize for a new doc writer.”

ざっくりした目的を使えるプロンプトに変える

code-tour では、読者、経路、除外対象を明示するのが重要です。例:

• “Create a code-tour onboarding tour for new maintainers of the billing service.”
• “Anchor each stop to real files and line ranges.”
• “Start from the request entrypoint, then config loading, domain logic, persistence, and tests.”
• “Avoid unrelated admin tooling.”
• “Write concise step text that explains why this file matters and where to look next.”

この形にすると、スキルが「要約」よりも「順路」を重視しやすくなります。こうした前提がないと、ツアーはファイル一覧のように平板になりがちです。

実務フローと出力チェック

推奨フローは次のとおりです。

1. 読者と、知りたいことを正確に決める。
2. リポジトリ内で entrypoint、コアモジュール、支援テストを確認する。
3. システムを実際に理解する順序に合わせて stop 順を設計する。
4. .tours/ に .tour ファイルを生成する。
5. すべてのファイルパスと行アンカーを検証する。
6. ツアーを開いて、弱い stop を削る。

重要な品質チェックは次のとおりです。

• 各 stop に存在理由がある
• 順序が単なる一覧ではなく、ひとつの流れになっている
• 行アンカーが import ブロックではなく、意味のあるコードを指している
• ツアーの最後に「次に確認すべき箇所」または要約ステップがある

code-tour スキル FAQ

code-tour は初心者に向いていますか？

はい、ただし範囲が狭い場合に限ります。初心者には、1つのフロー、サービス、または PR に絞ったツアーが最も役立ちます。リポジトリ全体を対象にした code-tour は、たいてい情報量が多すぎます。新しく参加する人向けなら、メイン実行経路に加えて、支援ファイルを 1〜2 個ほど通る短い経路を依頼するのがよいです。

通常のドキュメントではなく code-tour を使うべきなのはどんなときですか？

ソースに結びついたファイル単位の案内が必要なら code-tour を使います。概念的な概要、製品の振る舞い、長文の説明が必要なら通常のドキュメントが向いています。Technical Writing チームでは、code-tour は磨き込まれた docs の代替ではなく、ソースに沿って読める補助ツールとして使うのが最適です。

code-tour スキルの主な制限は何ですか？

機能実装、コードのリファクタリング、大規模なドキュメントセットの作成はできません。また、安定した file path と意味のあるコード構造に依存します。リポジトリが混沌としている、生成物が多い、命名が不十分といった場合でもツアー自体は作れますが、結果はかなり手作業での確認が必要になります。

どんな場合に不向きですか？

チャットでの短い回答で足りる場合、ユーザーが .tour ではなく Markdown ドキュメントを求めている場合、または範囲が広すぎて順序立てて案内しにくい場合は、code-tour は避けてください。読者が誰か不明な場合も相性がよくありません。ツアーは、誰向けかが分かるほど質が上がります。

code-tour スキルを改善する方法

リポジトリを読むためのガイドをもっと具体的に与える

品質を大きく左右するのは、生成前の探索経路を与えることです。entrypoint、router、handler、主要サービス、テスト、config のどこから始めるかを明示してください。必要なら PR 差分やインシデントメモも含めます。アンカーが良いほど、ツアーも良くなります。

code-tour のよくある失敗を防ぐ

よくある弱い出力は次のとおりです。

• stop が多すぎる
• 重要でない行にアンカーしている
• どのリポジトリにも当てはまる一般論になっている
• 読者が誰か明確でない
• ステップ間に物語的なつながりがない

これを避けるには、stop 数の上限を決め、読者を名指しし、各 stop で「このファイルが重要な理由」と「次に確認する箇所」を求めてください。

audience と intent でプロンプトを改善する

Technical Writing 向けの code-tour では、用語、境界の定義、ドキュメント化すべき概念を求めます。PR review なら、変更ファイルの順序とリスクが高い箇所を求めます。オンボーディングなら、アーキテクチャを先にし、テストは最後に回すよう依頼します。同じ repo でも、プロンプトが違えばツアーの質は大きく変わります。

最初の下書きのあとに必ず反復する

最初の出力は完成品ではなく、地図として扱ってください。.tour を開き、重複した stop を消し、行範囲を絞り、最後のほうに要約 stop を 1 つ追加します。ツアーがディレクトリ一覧のように見えるなら、範囲を狭めて再生成してください。良い code-tour スキルの成果は、広く一発で作ることではなく、焦点を絞って 1 回直すことから生まれます。