CodeTour 程式碼導覽 是做什麼的？
建立 CodeTour .tour 檔案，用於程式碼庫走查，這些檔案會直接開啟到真實的檔案和行範圍。導覽檔案存放在 .tours/ 目錄中，採用 CodeTour 格式，而非臨時的 Markdown 筆記。
一個好的導覽是針對特定讀者的敘事：
- 他們在看什麼
- 為什麼重要
- 接下來該走哪條路
僅建立 .tour JSON 檔案。請勿在本技能範圍內修改原始碼。
使用時機
在以下情況使用此技能：
- 使用者要求程式碼導覽、入門導覽、架構走查或 PR 導覽
- 使用者說「解釋 X 如何運作」，且希望得到可重複使用的引導式產出
- 使用者希望為新工程師或審查者建立上手路徑
- 比起平鋪直敘的摘要，引導式的序列更適合該任務
範例：
- 新維護者入職
- 某個服務或套件的架構導覽
- 錨定到變更檔案的 PR 審查走查
- 展示失敗路徑的 RCA 導覽
- 審查信任邊界與關鍵檢查的安全性導覽
何時不該使用
| 不要用 code-tour | 改用 |
|---|---|
| 在聊天中一次性解釋就夠了 | 直接回答 |
使用者想要散文式文件，而不是 .tour 產出 | documentation-lookup 或編輯 repo 文件 |
| 任務是實作或重構 | 執行實作工作 |
| 任務是廣泛的程式碼庫入門，但不需要導覽產出 | codebase-onboarding |
工作流程
1. 探索
在寫任何東西之前先探索倉庫：
- 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/<persona>-<focus>.tour
保持路徑確定性且易讀。
5. 驗證
完成前：
- 每個參照的路徑都存在
- 每行或選取範圍都有效
- 第一步錨定到真實的檔案或目錄
ref指向一個分支或提交，且該修訂版確實包含導覽中參照的所有檔案（見下文）- 導覽講述一個連貫的故事，而非列出檔案
ref 欄位
ref 將導覽綁定到一個 Git 分支或提交。它的重要性遠比看起來高：當 ref 不是讀者目前檢出的分支時，CodeTour 會從該修訂版開啟每個步驟的檔案（來自 Git），而非磁碟上的檔案。如果該檔案不存在於該修訂版中，步驟將無法開啟——讀者會看到「無法開啟編輯器，因為找不到檔案」，即使檔案明明就在那裡。導覽和其註解仍然會顯示，因此真正的成因很容易被忽略。
根據導覽類型選擇 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、議題或文件（視情況使用）：
{ "uri": "https://github.com/org/repo/pull/456", "title": "此 PR" }
寫作規則：SMIG
每個描述應回答：
- 情境 (Situation)：讀者正在看什麼
- 機制 (Mechanism)：它是如何運作的
- 影響 (Implication)：為什麼對該人物角色重要
- 陷阱 (Gotcha)：聰明讀者可能會錯過什麼
保持描述簡潔、具體，並立足於實際程式碼。
敘事架構
除非任務明確需要不同安排，否則使用此架構：
- 定位
- 模組地圖
- 核心執行路徑
- 邊緣案例或陷阱
- 結尾 / 下一步
導覽應感覺像一條路徑，而不是一份清單。
範例
{
"$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": "你現在可以透過已建立的主要錨點，從頭到尾追蹤任何付款請求。"
}
]
}
反模式
| 反模式 | 修正 |
|---|---|
| 平鋪直敘的檔案列表 | 講述一個有步驟間依賴關係的故事 |
| 通用描述 | 具體指出程式碼路徑或模式 |
| 猜測的錨點 | 先驗證每個檔案和行號 |
| 快速導覽步驟數過多 | 嚴格刪減 |
| 第一步是純內容 | 將第一步錨定到真實檔案或目錄 |
| 人物角色不符 | 為實際讀者撰寫，而非泛泛的工程師 |
最佳實踐
- 步驟數與倉庫大小及人物角色深度成比例
- 使用目錄步驟進行定位，使用檔案步驟展示實質內容
- 對於 PR 導覽，先涵蓋變更的檔案
- 對於 monorepo，將範圍限定在相關套件，而非導覽所有內容
- 結尾處告訴讀者他們現在可以做什麼，而不是總結
相關技能
codebase-onboardingcoding-standardscouncil- 官方上游格式：
microsoft/codetour