程式碼導覽 (Code Tour)
建立 CodeTour .tour 檔案，用於程式碼庫的逐步導覽，這些檔案會直接開啟到真實的檔案和行號範圍。導覽檔案位於 .tours/ 目錄中，專屬於 CodeTour 格式，並非臨時的 Markdown 筆記。
一個好的導覽是針對特定讀者的敘事：
- 他們正在看什麼
- 為什麼這很重要
- 他們下一步應該走哪條路徑
僅建立 .tour JSON 檔案。不要作為此技能的一部分修改原始碼。
何時使用
在以下情況使用此技能：
- 使用者要求程式碼導覽、入門導覽、架構解說或 PR 導覽
- 使用者說「解釋 X 是如何運作的」，並想要一個可重複使用的引導式產出物
- 使用者想要為新工程師或審查者建立快速上手路徑
- 比起平鋪直敘的摘要，此任務更適合用引導式的順序來處理
範例：
- 引導新維護者入門
- 針對某個服務或套件的架構導覽
- 錨定在變更檔案上的 PR 審查導覽
- 展示失敗路徑的 RCA 導覽
- 關於信任邊界與關鍵檢查的安全審查導覽
何時不要使用
| 不要用 code-tour | 改用 |
|---|---|
| 一次性的聊天說明就夠了 | 直接回答 |
使用者想要文字文件，而非 .tour 產出物 | documentation-lookup 或編輯儲存庫文件 |
| 任務是實作或重構 | 執行實作工作 |
| 任務是沒有導覽產出物的廣泛程式碼庫入門 | 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 不是讀者目前 checkout 的分支時，CodeTour 會從該修訂版本開啟每個步驟的檔案（來自 git），而不是從磁碟上的檔案開啟。如果某個檔案不在該修訂版本中，則該步驟將無法開啟——讀者會看到 「無法開啟編輯器，因為找不到檔案」，即使該檔案就在那裡。導覽和其註解仍然會顯示，因此真正的錯誤原因很容易被忽略。
根據導覽類型選擇 ref：
| 導覽類型 | 將 ref 設定為 |
|---|---|
| PR 導覽 | PR 分支 — 絕對不是基底分支 |
| 入門 / 架構 | 讀者將會 checkout 的分支（通常是 main），或者留空 |
| 不確定 | 留空 ref，這樣 CodeTour 就會直接從磁碟讀取檔案 |
PR 的情況是常見的陷阱：一個 PR 通常會新增檔案，而新檔案在基底分支上還不存在。將 ref 指向基底分支（例如 develop），則每個位於新檔案上的步驟都會無法開啟。
完成之前，請確認你所選擇的 ref 上確實存在每個步驟的檔案。
步驟類型
內容 (Content)
謹慎使用，通常僅用於結束步驟：
{ "title": "後續步驟", "description": "你現在可以從頭到尾追蹤請求路徑了。" }
不要讓第一個步驟是純內容。
目錄 (Directory)
用於引導讀者到一個模組：
{ "directory": "src/services", "title": "服務層", "description": "核心編排邏輯在這裡。" }
檔案 + 行號 (File + line)
這是預設的步驟類型：
{ "file": "src/auth/middleware.ts", "line": 42, "title": "認證閘道", "description": "每個受保護的請求都會先經過這裡。" }
選取範圍 (Selection)
當某個程式碼區塊比整個檔案更重要時使用：
{
"file": "src/core/pipeline.ts",
"selection": {
"start": { "line": 15, "character": 0 },
"end": { "line": 34, "character": 0 }
},
"title": "請求管線",
"description": "此區塊串接了驗證、認證和下游執行。"
}
模式 (Pattern)
當確切的行號可能會變動時使用：
{ "file": "src/app.ts", "pattern": "export default class App", "title": "應用程式進入點" }
URI
在需要時用於 PR、Issue 或文件：
{ "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