AI Skills
code-tour

code-tour

熱門

建立 CodeTour `.tour` 檔案 — 針對特定角色、逐步引導的程式碼導覽，包含真實檔案與行號錨點。適用於入門導覽、架構解說、PR 導覽、RCA 導覽，以及結構化的「解釋這個如何運作」請求。

23萬星標
3.5萬分支
更新於 2026/7/21
獲取技能源代碼

相關技能

ponytail-help8.4萬skill-share7萬agent-manager-skill4.7萬
SKILL.md
唯讀
名稱
code-tour
描述

建立 CodeTour `.tour` 檔案 — 針對特定角色、逐步引導的程式碼導覽，包含真實檔案與行號錨點。適用於入門導覽、架構解說、PR 導覽、RCA 導覽，以及結構化的「解釋這個如何運作」請求。

Code Tour

建立 CodeTour .tour 檔案，用於程式碼庫導覽，可直接開啟真實檔案與行號範圍。導覽檔案存放在 .tours/ 目錄中，採用 CodeTour 格式，而非臨時的 Markdown 筆記。

一個好的導覽是為特定讀者設計的敘事：

  • 他們正在看什麼
  • 為什麼重要
  • 下一步該往哪走

僅建立 .tour JSON 檔案。此技能不應修改原始碼。

使用時機

在以下情況使用此技能：

  • 使用者要求程式碼導覽、入門導覽、架構解說或 PR 導覽
  • 使用者說「解釋 X 如何運作」，且希望得到可重複使用的引導產出
  • 使用者需要為新進工程師或審查者建立上手路徑
  • 比起平面摘要，引導式序列更適合該任務

範例：

  • 新維護者入門
  • 單一服務或套件的架構導覽
  • 針對變更檔案的 PR 審查導覽
  • 顯示失敗路徑的 RCA 導覽
  • 信任邊界與關鍵檢查的安全性審查導覽

何時不該使用

不使用 code-tour 的情況 改用
在對話中一次性解釋就夠了 直接回答
使用者想要文字文件，而非 .tour 產出 documentation-lookup 或編輯 repo 文件
任務是實作或重構 執行實作工作
任務是廣泛的程式碼庫入門，但不需要導覽產出 codebase-onboarding

工作流程

1. 探索

在開始撰寫前先探索 repo：

  • 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/<角色>-<主題>.tour

保持路徑明確且可讀。

5. 驗證

完成前：

  • 每個參照的路徑都存在
  • 每個行號或選取範圍都有效
  • 第一個步驟錨定到真實的檔案或目錄
  • ref 指向的分支或提交確實包含導覽中參照的所有檔案（見下方說明）
  • 導覽講述連貫的故事，而非列出檔案清單

ref 欄位

ref 將導覽綁定到 git 分支或提交。它比看起來更重要：當 ref 不是讀者目前檢出的分支時，CodeTour 會從該修訂版本中開啟每個步驟的檔案，而非從磁碟上的檔案開啟。如果該修訂版本中沒有該檔案，步驟將無法開啟——讀者會看到「無法開啟編輯器，因為找不到檔案」，即使檔案就在那裡。導覽與其註解仍會顯示，因此真正的原因很容易被忽略。

根據導覽類型選擇 ref：

導覽類型 設定 ref 為
PR 導覽 PR 分支——絕不是基礎分支
入門 / 架構 讀者將使用的分支（通常是 main），或留空
不確定 留空 ref，讓 CodeTour 直接從磁碟讀取檔案

PR 的情況是常見陷阱：PR 通常會新增檔案，而新檔案在基礎分支上還不存在。將 ref 指向基礎分支（例如 develop），則每個在新檔案上的步驟都無法開啟。

完成前，確認每個步驟的檔案在你選擇的 ref 下確實存在。

步驟類型

純內容

謹慎使用，通常僅用於結尾步驟：

{ "title": "下一步", "description": "你現在可以端到端追蹤請求路徑。" }

不要讓第一個步驟是純內容。

目錄

用於引導讀者了解某個模組：

{ "directory": "src/services", "title": "服務層", "description": "核心編排邏輯位於此處。" }

檔案 + 行號

這是預設的步驟類型：

{ "file": "src/auth/middleware.ts", "line": 42, "title": "認證閘道", "description": "每個受保護的請求都會先經過這裡。" }

選取範圍

當某段程式碼比整個檔案更重要時使用：

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "請求管線",
  "description": "此區塊連接驗證、認證與下游執行。"
}

模式

當確切行號可能變動時使用：

{ "file": "src/app.ts", "pattern": "export default class App", "title": "應用程式進入點" }

URI

在需要時用於 PR、Issue 或文件：

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

撰寫規則：SMIG

每個描述應回答：

  • 情境：讀者正在看什麼
  • 機制：它如何運作
  • 影響：為什麼對這個角色重要
  • 陷阱：聰明讀者可能忽略的地方

保持描述簡潔、具體，並基於實際程式碼。

敘事結構

除非任務明確需要不同結構，否則使用以下架構：

  1. 方向定位
  2. 模組地圖
  3. 核心執行路徑
  4. 邊界情況或陷阱
  5. 結尾 / 下一步行動

導覽應像一條路徑，而非清單。

範例

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API 服務導覽",
  "description": "付款服務請求路徑的逐步解說。",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "原始碼根目錄",
      "description": "服務的所有執行時期程式碼從這裡開始。"
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "進入點",
      "description": "伺服器在此啟動，並在路由到達前連接中介層。"
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "付款路由",
      "description": "所有付款請求在進入服務邏輯前，先通過此路由器。"
    },
    {
      "title": "下一步",
      "description": "現在你可以利用主要錨點，端到端追蹤任何付款請求。"
    }
  ]
}

反模式

反模式 修正方式
平面檔案列表 講述一個步驟間有依賴關係的故事
通用描述 指出具體的程式碼路徑或模式
猜測的錨點 先驗證每個檔案與行號
快速導覽步驟過多 大膽刪減
第一個步驟是純內容 將第一個步驟錨定到真實檔案或目錄
角色不符 為實際讀者撰寫，而非泛泛的工程師

最佳實踐

  • 步驟數量與 repo 大小及角色深度成比例
  • 使用目錄步驟進行方向定位，檔案步驟提供實質內容
  • 對於 PR 導覽，優先涵蓋變更的檔案
  • 對於 monorepo，範圍限於相關套件，而非導覽所有內容
  • 結尾說明讀者現在可以做什麼，而非總結

相關技能

  • codebase-onboarding
  • coding-standards
  • council
  • 官方上游格式：microsoft/codetour