code-tour

code-tour skill 概覽

code-tour 會建立什麼

code-tour skill 可協助 AI agent 產生 VS Code CodeTour extension 使用的 CodeTour .tour JSON 檔。Tour 是一種導覽式 walkthrough，會把說明步驟連到實際檔案與行號，通常存放在 .tours/ 底下。這個 skill 的設計重點是有結構地探索 repository，而不是編輯程式碼：它的核心界線是只建立 tour 檔案，並避免修改 source code。

最適合 Technical Writing 與 onboarding 的情境

當你需要 onboarding 路徑、contributor guide、架構 walkthrough、PR review tour、安全審查路徑、root-cause analysis trail，或「說明這段系統如何運作」的 walkthrough 時，可以在 Technical Writing 中使用 code-tour。它最適合讀者角色明確的情境：新進 backend engineer、frontend maintainer、reviewer、incident responder、staff engineer，或需要透過策展式路徑理解實作細節的非程式背景 stakeholder。

為什麼比一般 prompt 更好

一般 prompt 可能只會鬆散地摘要檔案。code-tour skill 會把 agent 推向可直接使用的成果物：針對特定 persona 撰寫的敘事步驟，並附上具體檔案與行號錨點。這很重要，因為 tour 必須能在 VS Code 中導覽、必須引用既有路徑，也必須說明每一站為什麼重要，而不是丟出一份資料夾摘要。真正有用的輸出不是「這個 repo 裡有什麼」，而是「這位讀者應該先點哪裡、接著去哪裡，以及為什麼」。

安裝前的採用考量

這個 skill 只有聚焦明確的 SKILL.md，沒有額外 scripts、rules 或 reference packs。因此 code-tour install 很輕量，但也代表品質高度取決於 repository 存取權與 prompt 細節。當 agent 能檢視 file tree、README、config files 與 source entry points 時，效果最好。如果你只需要純文字文件、Mermaid diagrams、source edits，或希望為 agent 無法讀取的檔案建立 tour，這個 skill 就不太適合。

如何使用 code-tour skill

code-tour install 與 repository context

使用你的 skills tooling 從 source repository 安裝，例如：

npx skills add alirezarezvani/claude-skills --skill code-tour

安裝後，如有需要可確認 skill path：engineering/code-tour/skills/code-tour/SKILL.md。在目標專案中，agent 應先檢視 root directory、README.md、package 或 build config，以及最上層一到兩層資料夾，再開始起草。tour 應儲存為 .tours/ 底下的 .tour JSON 檔，並與 VS Code CodeTour extension 相容。

skill 需要的輸入

要讓 code-tour usage 產出品質更好，請提供五件事：audience、goal、scope、desired depth，以及任何必須納入的 files 或 feature names。較弱的需求是：「make a tour of this repo。」較強的需求是：「Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines。」

如果 tour 是為 Technical Writing 而做，請補上發佈目的：onboarding doc、release note support、internal architecture guide、review aid，或 incident learning artifact。

第一次建立 tour 的建議流程

先做 discovery，不要一開始就寫。請 agent 先辨識專案目的、languages、frameworks、entry points 與重要 directories。接著選擇一條敘事路徑：setup-to-first-feature、request-to-response、UI-action-to-API、bug-symptom-to-root-cause，或 PR-diff-to-risk。完成這些之後，才產生 .tour 檔。這個順序可以減少失效錨點，也能避免做出只會列出資料夾名稱、卻無法教會讀者系統如何運作的淺層「folder tour」。

實用 prompt 模板

可以使用這樣的 prompt：

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

這個 prompt 有效，是因為它給 agent 一個決策框架，而不只是丟出一個主題。

code-tour skill FAQ

什麼時候該用 code-tour，而不是一般文件？

當「透過程式碼導覽」本身就是產品時，適合使用 code-tour。傳統文件更適合概念、政策或 API reference。當讀者需要依序開啟檔案，並理解 routes、services、tests、configs 與 entry points 之間的關係時，CodeTour 會更合適。

初學者可以使用 code-tour skill 嗎？

可以，但初學者應該縮小需求範圍。先要求一個小型 tour：一個 feature、一條 bug path，或一個 architecture slice。像「explain the entire codebase」這類過於寬泛的請求，除非 repository 非常小，否則常會產出雜訊很多的 tour。對於 source files 少於幾個的小型 repositories，快速但有深度的 tour 通常就足夠。

code-tour 會編輯我的 application code 嗎？

不會。預期輸出是一個 .tour JSON 檔，通常放在 .tours/。這個 skill 的明確界線是避免修改 source code。如果你的 workflow 需要 code fixes、tests 或 refactors，請先使用其他 engineering skill，然後再用 code-tour 記錄最後形成的路徑。

什麼會阻礙 code-tour 產出好結果？

最大的阻礙包括缺少 repository 存取權、audience 模糊、沒有 scope limit，以及 file paths 未驗證。CodeTour 步驟仰賴真實錨點。如果 agent 無法讀取目標檔案，或在頻繁編輯期間行號大幅變動，請等程式碼穩定後再產生 tour，或先要求 path-level anchors，之後再細修行號。

如何改善 code-tour skill

讓 code-tour prompts 具備明確 persona

改善 code-tour 輸出最快的方法，就是直接說明讀者是誰。「New contributor」會產生與「security reviewer」或「technical writer preparing onboarding material」不同的導覽路徑。請包含讀者已經知道什麼，以及完成 tour 後必須能做到什麼。這會改變步驟選擇、說明深度與用字。

要求敘事，而不是清單

弱的 tour 只會列出檔案。強的 tour 會說一個故事：執行從哪裡開始、資料如何流動、決策在哪裡發生、風險藏在哪裡，以及哪些 tests 證明行為正確。請要求 agent 把每一站連回上一站，並在每個步驟加入一句「why this matters」。這對 Technical Writing 特別有價值，因為最後成果會變得可教學，而不只是可點擊。

在第一版輸出後迭代

拿到第一版 .tour draft 後，請檢查三件事：file paths 是否失效或不精確、步驟是否過於寬泛，以及轉場是否缺失。接著要求有目標的修改，例如：「split step 4 into route and service steps」、「add the test that covers this behavior」，或「reduce frontend detail and focus on API error handling」。通常，迭代會比一次要求產出完美的 full-repo tour 更有效。

分享前先驗證錨點

發佈 CodeTour 前，請在 VS Code 中搭配 CodeTour extension 開啟，確認每個 path 與 line 都落在預期位置。如果 repository 經常變動，請優先建立連到穩定 architecture files、tests 或 entry points 的 tour，並在大型 refactors 後重新產生行號。這能讓 code-tour skill 持續作為有用的 onboarding asset，而不是一張過期地圖。