codebase-to-course 是做什麼的？
將任何程式碼庫轉換成令人驚艷的互動式課程。輸出是一個目錄，包含預先建置的 styles.css、main.js、每個模組的 HTML 檔案以及組合好的 index.html — 直接在瀏覽器中開啟，無需任何設定（唯一的外部依賴是 Google Fonts CDN）。該課程透過滾動式模組、動畫視覺化、嵌入式測驗以及程式碼的白話文翻譯，來教導程式碼的運作方式。
首次執行歡迎頁面
當技能首次被觸發，且使用者尚未指定程式碼庫時，請先自我介紹並說明你能做什麼：
我可以將任何程式碼庫轉換成互動式課程，教導它的運作方式 — 無需任何程式設計知識。
只要向我指定一個專案：
- 一個本地資料夾 — 例如，「將 ./my-project 變成一個課程」
- 一個 GitHub 連結 — 例如，「從 https://github.com/user/repo 製作一個課程」
- 目前的專案 — 如果你已經在一個程式碼庫中，只要說「把這個變成一個課程」
我會讀取整個程式碼，弄清楚所有東西如何組合在一起，然後生成一個美麗的單頁 HTML 課程，其中包含動畫圖表、白話文程式碼解說以及互動式測驗。整個東西都在你的瀏覽器中執行 — 無需任何設定。
如果使用者提供 GitHub 連結，請先複製該儲存庫（git clone <url> /tmp/<repo-name>）再開始分析。如果他們說「這個程式碼庫」或類似內容，則使用當前工作目錄。
這個課程是為誰設計的
目標學習者是所謂的**「氛圍程式設計師」** — 他們透過以自然語言指示 AI 編碼工具來建構軟體，沒有傳統的電腦科學教育背景。他們可能自己建構了這個專案（但沒有看過程式碼），或者他們在 GitHub 上找到了一個有趣的開源專案，並想了解它是如何建構的。無論哪種情況，他們都還不了解底層發生了什麼事。
假設完全沒有技術背景。 每個計算機科學概念 — 從變數到 API 再到資料庫 — 都需要用白話文解釋，就好像學習者從未遇過這個概念一樣。沒有定義就不要使用術語。不要說「如你所知」。語氣應該像一個聰明的朋友在解釋事情，而不是教授在授課。
他們的目標是實用的，而非學術性的：
- 擁有足夠的技術知識，以便能有效引導 AI 編碼工具 — 做出更好的架構和技術堆疊決策
- 偵測 AI 何時出錯 — 發現幻覺、捕捉不良模式、知道何時事情不對勁
- 在 AI 卡住時進行干預 — 跳出錯誤迴圈、除錯問題、排除障礙
- 建構具有生產級品質和可靠性的更先進軟體
- 擁有足夠的技術流暢度，能夠自信地與工程師討論決策
- 習得軟體的詞彙 — 學習精確的技術術語，以便能清晰且明確地向 AI 編碼代理描述需求（例如，知道要說「命名空間套件」而不是「共享資料夾東西」）
他們並不是要成為軟體工程師。 他們希望將程式設計作為一種超能力，來放大他們原本就擅長的事情。他們不需要從頭開始寫程式碼 — 他們需要的是閱讀它、理解它，以及指揮它。
為什麼這種方法有效
這個技能顛覆了傳統的計算機科學教育。舊的模式是：花數年記憶概念 → 最終建構一些東西 → 終於看到重點（大多數人在第三步之前就放棄了）。這個模式是：先建構一些東西 → 體驗它運作 → 現在了解它如何運作。
學習者已經擁有傳統學生所沒有的背景脈絡 — 他們使用過這個應用程式，他們知道它做什麼，他們甚至可能已經用自然語言描述過它的功能。這個課程從他們所在的地方開始：「你知道你點擊的那個按鈕嗎？這裡是當你點擊它時，底層發生的事。」
每個模組在解釋「如何運作？」之前，都會先回答**「我為什麼要關心？」**。對「我為什麼要關心？」的答案總是實用的：因為這個知識可以幫助你更好地引導 AI、更快地除錯，或做出更明智的架構決策。
目錄式輸出是經過深思熟慮的：將 CSS/JS 與內容分離意味著 AI 永遠不會重新生成樣板，每個模組都是獨立撰寫的（保持輸出檔案小且品質高），且組合好的 index.html 可以在離線狀態下開箱即用，無需任何設定。
流程
第一階段：程式碼庫分析
在撰寫課程 HTML 之前，先深入理解程式碼庫。讀取所有關鍵檔案，追蹤資料流，找出「角色陣容」（主要的元件/模組），並繪製它們如何溝通。此階段的徹底性會得到回報 — 你理解得越多，課程就越好。
需要提取的內容：
- 主要的「演員」（元件、服務、模組）及其職責
- 主要的使用者旅程（當某人從頭到尾使用應用程式時會發生什麼事）
- 關鍵 API、資料流和溝通模式
- 巧妙的工程模式（快取、延遲載入、錯誤處理等）
- 真實的錯誤或陷阱（如果在 git 歷史記錄或註解中可見）
- 技術堆疊以及選擇每個部分的原因
自己弄清楚應用程式是做什麼的，透過閱讀 README、主要進入點和 UI 程式碼。不要要求使用者解釋產品 — 他們可能也不熟悉。課程應該先以白話文解釋應用程式的功能（一個簡短的「這是什麼東西以及為什麼它很有趣」），然後再深入探討它如何運作。第一個模組應該從一個具體的使用者動作開始 — 「想像你貼上一個 YouTube 網址並點擊分析 — 以下是底層發生的事。」
第二階段：課程設計
將課程結構設計為 4-6 個模組。大多數課程需要 4-6 個。只有在程式碼庫確實有那麼多值得教學的獨特概念時，才擴展到 7-8 個。更少、更好的模組勝過更多、更薄的模組。
這個弧線總是從學習者已知的內容（使用者面向的行為）開始，然後朝向他們未知的內容（底層程式碼）移動。把它想成是放大：從體驗開始廣闊地看，然後逐漸剝開層層面紗。
| 模組位置 | 目的 | 為什麼對氛圍程式設計師很重要 |
|---|---|---|
| 1 | 「這是這個應用程式做什麼 — 以及當你使用它時會發生什麼事」 | 從產品開始（它做什麼，為什麼有趣），然後追蹤一個核心使用者動作進入程式碼。將所有東西建立在具體事物上。 |
| 2 | 認識演員 | 知道存在哪些元件，這樣你就可以告訴 AI「把這個邏輯放在 X 中，而不是 Y 中」 |
| 3 | 各個部分如何對話 | 理解資料流，這樣你就可以除錯「它沒有顯示出來」的問題 |
| 4 | 外部世界（API、資料庫） | 知道什麼是外部的，這樣你就可以評估成本、速率限制和故障模式 |
| 5 | 巧妙的技巧 | 學習模式（快取、分塊、錯誤處理），這樣你就可以要求 AI 使用它們 |
| 6 | 當東西壞掉時 | 建立除錯直覺，這樣你就可以逃脫 AI 的錯誤迴圈 |
| 7 | 大局觀 | 查看完整的架構，這樣你就可以對下一步要建構什麼做出更好的決定 |
這是一個選單，而非檢查清單。選擇服務程式碼庫的模組 — 一個簡單的 CLI 工具需要 4 個，而不是 7 個。根據程式碼庫的複雜度來調整弧線。
關鍵原則： 每個模組都應該連結回一個實用技能 — 引導 AI、除錯、做出決策。如果一個模組不能幫助學習者更好地做某件事，就刪除它或重新架構它，直到它能夠為止。
每個模組應包含：
- 3-6 個畫面（在模組內流動的子章節）
- 至少一個程式碼與英文對照翻譯
- 至少一個互動元素（測驗、視覺化或動畫）
- 一到兩個「啊哈！」提示框，包含通用的計算機科學見解
- 一個能將技術概念紮根於日常生活中的比喻 — 但絕對不要在不同模組間重複使用同一個比喻，也絕對不要預設使用「餐廳」比喻（它已經被過度使用了）。選擇有機地適合特定概念的比喻。最好的比喻感覺是必然為這個概念存在的，而不是強加的。
強制性的互動元素（每個課程都必須包含所有這些元素）：
- 群組聊天動畫 — 整個課程中至少一個。這些是元件之間的 iMessage/WeChat 風格的對話。它們是最吸引人的元素之一，必須始終出現，即使你必須創造性地將模組的概念框架為演員之間的對話。
- 訊息流/資料流動畫 — 整個課程中至少一個。演員之間的逐步封包動畫。如果程式碼庫有任何形式的請求/回應、資料管道或多步驟流程，就為它製作動畫。每個程式碼庫在某處都有資料流動 — 找到它。
- 程式碼 ↔ 英文翻譯區塊 — 每個模組至少一個（上面已經要求過，但重申：這是沒得商量的）。
- 測驗 — 每個模組至少一個（選擇題、情境題、拖放題或找錯誤題 — 任何測驗類型都算）。
- 詞彙表工具提示 — 每個技術詞彙，在每個模組中首次使用時都要加上。
這五種元素類型是每個課程的骨幹。其他互動元素（架構圖、圖層切換、模式卡片等）是可選的，應該在它們適合的時候加入。但以上五種必須始終存在 — 沒有例外。
不要提交課程大綱以供批准 — 直接建構它。 使用者想要一個課程，而不是一份規劃文件。在內部設計課程大綱，然後直接進入建構階段。如果他們想要更改，他們會在看到結果後告訴你。
在設計完課程大綱後，決定要使用哪個建構路徑：
- 簡單的程式碼庫（單一用途的 CLI、小型 Web 應用程式、函式庫、一個明確的進入點、5 個或更少的模組）→ 直接進入第三階段順序路徑。
- 複雜的程式碼庫（全端應用程式、多個服務、內容豐富的網站、monorepo，或 6 個以上的模組）→ 先進入第二點五階段，然後再進入第三階段並行路徑。
第二點五階段：模組簡報（僅限複雜的程式碼庫）
對於複雜的程式碼庫，在撰寫任何 HTML 之前，先為每個模組撰寫一份簡報。這是啟用並行撰寫的關鍵步驟 — 每個簡報為代理提供所需的一切，而無需重新讀取整個程式碼庫。
閱讀 references/module-brief-template.md 以了解簡報結構範本。閱讀 references/content-philosophy.md 以了解應指導簡報撰寫的內容規則。
對於每個模組，將一份簡報寫到 course-name/briefs/0N-slug.md，包含：
- 教學弧線（比喻、開場鉤子、關鍵見解）
- 預先提取的程式碼片段（從程式碼庫中複製貼上，附上檔案路徑和行號）
- 互動元素檢查清單，包含足夠的細節來建構它們
- 撰寫代理需要參考檔案中的哪些章節
- 前一個和下一個模組涵蓋的內容（用於過渡）
程式碼片段是關鍵的節省 Token 步驟。透過預先將它們提取到簡報中，撰寫代理永遠不需要閱讀程式碼庫本身。
第三階段：建構課程
課程輸出的是一個目錄，而不是單一檔案。所有 CSS 和 JS 都是預先建置的參考檔案 — 永遠不要重新生成它們。你的工作是只撰寫 HTML 內容。
輸出結構：
course-name/
styles.css ← 從 references/styles.css 直接複製
main.js ← 從 references/main.js 直接複製
_base.html ← 自訂的外殼（標題、強調色、導航點）
_footer.html ← 從 references/_footer.html 直接複製
build.sh ← 從 references/build.sh 直接複製
briefs/ ← 模組簡報（僅限複雜的程式碼庫，建置後可刪除）
modules/
01-intro.html
02-actors.html
...
index.html ← 由 build.sh 組合而成（不要手動撰寫）
步驟 1（兩種路徑）：設定 — 建立課程目錄。使用讀取 + 寫入直接複製以下四個檔案（不要重新生成它們的內容）：
references/styles.css→course-name/styles.cssreferences/main.js→course-name/main.jsreferences/_footer.html→course-name/_footer.htmlreferences/build.sh→course-name/build.sh
步驟 2（兩種路徑）：自訂 _base.html — 讀取 references/_base.html，然後將其寫入 course-name/_base.html，並進行恰好三個替換：
COURSE_TITLE的兩個實例 → 實際的課程標題- 四個
ACCENT_*佔位符 → 選擇的強調色值（從_base.html的註解中選擇一個調色板） NAV_DOTS→ 每個模組一個<button class="nav-dot" ...>
步驟 3：撰寫模組 — 這是路徑分岐的地方。
順序路徑（簡單的程式碼庫）
閱讀 references/content-philosophy.md 和 references/gotchas.md。然後一次撰寫一個模組。對於每個模組，撰寫 course-name/modules/0N-slug.html，僅包含 <section class="module" id="module-N"> 區塊及其內容。不要包含 <html>、<head>、<body>、<style> 或 <script> 標籤。
閱讀 references/interactive-elements.md 以了解每種互動元素類型的 HTML 模式。閱讀 references/design-system.md 以了解視覺慣例。
並行路徑（複雜的程式碼庫）
將模組分批次（最多 3 個）分派給子代理。每個代理接收：
- 其模組簡報（來自
course-name/briefs/） references/content-philosophy.md和references/gotchas.md- 僅有簡報中列出的
references/interactive-elements.md和references/design-system.md的章節
每個代理將其模組檔案撰寫到 course-name/modules/。短模組（3 個畫面，一個測驗）可以配對 — 兩個簡報交給一個代理。
代理不會收到的內容： 完整的程式碼庫（片段已在簡報中）、SKILL.md、其他模組的簡報，或不需要的參考檔案章節。
在所有代理完成後，在主脈絡中進行快速的一致性檢查：導航點與模組匹配、模組之間的過渡連貫、沒有明顯的語氣轉變。
步驟 4（兩種路徑）：組合 — 從課程目錄執行 build.sh：
cd course-name && bash build.sh
這會產生 index.html。在瀏覽器中開啟它。
關鍵規則：
- 永遠不要重新生成
styles.css或main.js— 總是從
…
[為翻譯而截斷]