Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
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
每個描述應回答：
- 情境：讀者正在看什麼
- 機制：它如何運作
- 影響：為什麼對這個角色重要
- 陷阱：聰明讀者可能忽略的地方
保持描述簡潔、具體，並基於實際程式碼。
敘事結構
除非任務明確需要不同結構，否則使用以下架構：
- 方向定位
- 模組地圖
- 核心執行路徑
- 邊界情況或陷阱
- 結尾 / 下一步行動
導覽應像一條路徑，而非清單。
範例
{
"$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-onboardingcoding-standardscouncil- 官方上游格式：
microsoft/codetour
