code-tour

code-tour skill 概覽

code-tour skill 的用途

code-tour skill 會建立可重複使用的 CodeTour .tour 檔案，透過真實的檔案路徑與行號區間，帶讀者一步步走過整個 repository。它不是一次性的聊天說明，而是會在 .tours/ 內產出可保存的成果，並可在相容 CodeTour 的工具中以導覽流程開啟。

最適合的使用者與要完成的工作

這個 skill 很適合需要用結構化方式帶人理解程式碼的維護者、reviewer 與技術寫作者，例如：新人 onboarding 導覽、架構導覽、PR walkthrough、RCA 路徑整理，或安全審查路徑。真正要解決的問題不是「幫我摘要整個 repo」，而是「依照正確順序，引導特定讀者看對的檔案」。

為什麼選 code-tour，而不是一般提示詞

一般提示詞通常只會產出脫離程式碼本體的說明文字。code-tour 的適用範圍雖然更窄，但當你需要可長期重用的導覽時，反而更實用：每一步都會指向實際檔案與行號範圍，並附上敘事脈絡與下一步閱讀動線。這也讓它特別適合用在 Technical Writing、onboarding，以及可重複執行的審查流程中的 code-tour。

安裝前要先知道的關鍵限制

code-tour skill 只會建立 .tour JSON 檔；它不是拿來編輯原始碼、重寫大範圍文件，或進行一般問答的工具。當 repository 本身的檔案結構清楚，而且需求範圍已收斂到某個 service、feature、incident 路徑，或 PR diff，而不是「把全部都解釋一遍」時，它的效果最好。

如何使用 code-tour skill

安裝情境與優先閱讀內容

先依照你平常的 skills workflow 安裝上層 skills repo，之後再從該環境呼叫 code-tour。在這個 skill 資料夾裡，SKILL.md 是唯一的來源檔案，因此應先讀它。這裡沒有額外的 helper script 或參考資料，所以導入門檻低，但也代表你必須自行提供足夠的 repo 脈絡。

code-tour skill 需要哪些輸入

若想把 code-tour 用好，建議提供以下資訊：

• audience：「new backend engineer」、「security reviewer」、「technical writer」
• goal：onboarding、architecture、PR review、RCA、trust-boundary review
• scope：package、service、feature，或變更過的檔案
• output target：.tours/<name>.tour
• repo anchors：關鍵檔案、entrypoints、modules，或 commit/PR 脈絡

一個太弱的請求會是：「Make a tour of this repo.」
更好的請求會是：「Create a code-tour for Technical Writing that explains how auth requests flow through src/server.ts, middleware, token validation, and session storage. Keep it to 8–10 stops and optimize for a new doc writer.」

把模糊目標整理成可用的 prompt

好的 code-tour prompt 應該明確指出讀者、路徑，以及不包含哪些內容。範例：

• “Create a code-tour onboarding tour for new maintainers of the billing service.”
• “Anchor each stop to real files and line ranges.”
• “Start from the request entrypoint, then config loading, domain logic, persistence, and tests.”
• “Avoid unrelated admin tooling.”
• “Write concise step text that explains why this file matters and where to look next.”

這樣可以幫助 skill 優先決定「導覽順序」，而不是只做內容摘要。少了這層 framing，產出的 tour 很容易變成扁平的檔案清單。

實際工作流程與輸出檢查

建議流程如下：

1. 先確認讀者是誰，以及他真正要解答的問題。
2. 檢查 repo，找出 entrypoints、核心 modules，以及支援用的 tests。
3. 先擬定 stop 順序，讓順序符合這個系統實際被理解的方式。
4. 在 .tours/ 中產生 .tour 檔案。
5. 驗證每個檔案路徑與行號 anchor 是否正確。
6. 實際打開 tour，刪掉或修整較弱的 stops。

真正重要的品質檢查包括：

• 每個 stop 都有清楚存在理由
• 整體順序是在講一個流程，而不只是列清單
• line anchors 指向有意義的程式碼，而不是 import 區塊
• tour 結尾有「接下來該看什麼」或總結性的收束步驟

code-tour skill 常見問題

code-tour 適合初學者嗎？

適合，但前提是範圍要小。初學者最適合的是聚焦在單一流程、單一 service 或單一 PR 的 tour。涵蓋整個 repo 的 code-tour 通常只會讓人資訊過載。若你是要帶新人 onboarding，建議要求一條短路徑：先走主要執行流程，再補 1–2 個支援檔案即可。

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

當讀者需要依照原始碼逐檔導覽時，就該用 code-tour。若你需要的是概念性總覽、產品行為說明，或長篇敘述型文件，就應該用一般文件。對 technical writing 團隊而言，code-tour 最適合當作「由原始碼帶路」的輔助材料，而不是取代正式整理過的文件。

code-tour skill 的主要限制是什麼？

它不會實作功能、不會重構程式碼，也不會替你撰寫大範圍的文件集。它同時仰賴穩定的檔案路徑與有意義的程式結構。如果 repo 很混亂、充滿產生式檔案，或命名不清楚，這個 skill 雖然仍能產出 tour，但結果通常需要更多人工審查與修正。

哪些情況下不適合用 code-tour？

如果只需要在聊天中快速得到答案、使用者想要的是 Markdown 文件而不是 .tour 成品，或需求範圍大到很難排出合理順序，就不建議用 code-tour。當目標讀者不明確時，它也不太適合；一旦知道 tour 是寫給誰看的，品質通常會明顯提升。

如何改進 code-tour skill

提供更強的 repo 閱讀指引

想提升 code-tour 品質，最有效的方法，是在產生 tour 之前先提供探索路徑。明確告訴 skill 應從哪裡開始看：entrypoints、routers、handlers、core services、tests 與 config。若有需要，也可以補上 PR diff 或 incident 筆記。anchor 越清楚，產出的 tour 通常越好。

避開常見的 code-tour 失敗模式

常見的弱輸出包括：

• stops 太多
• stop 錨定在不重要的行
• 評論過於泛泛，套到任何 repo 都說得通
• 沒有清楚的目標讀者
• 步驟之間缺少敘事轉場

避免方式是：先設定 stop 數量上限、明確指定讀者，並要求每個 stop 都回答「這裡為什麼重要」以及「下一步該看哪裡」。

用讀者與意圖強化 prompt

若是要做給 Technical Writing 使用的 code-tour，可以要求它特別整理術語、邊界定義，以及值得寫進文件的概念。若是用於 PR review，就要求依照變更檔案排序，並標出風險熱點。若是 onboarding，則可要求先從架構出發，tests 放在最後。相同的 repo，prompt 不同，tour 品質與用途也會差很多。

在第一版之後再迭代一次

把第一版輸出當成地圖，而不是最終成品。實際打開 .tour，移除重複的 stops、收緊行號範圍，並在接近結尾的地方加上一個綜合整理的 stop。若整個 tour 看起來像目錄清單，就代表範圍還是太大，應該縮小後重新產生。code-tour skill 最好的結果，通常不是來自一次做很大，而是來自一次聚焦的修訂。