用 LLM
製作工具

這份文件

本文件規範以 LLM CLI 協作開發課堂工具的作業流程，適用對象為無程式背景的修課學生。內容限於工作方法與已知的平台行為，不涉及作品的形式、外觀與技術選型。標示為「作業約定」者為本課程的規定，非技術限制。

它有兩個讀者：修課學生，以及學生自己的 LLM CLI。下載後置於專案資料夾根目錄，每次開啟 session 時要求 CLI 讀取。

兩種啟動方式

• 首次：專案內只有本檔。第一則指令要求 CLI 讀取本檔，並依〈規格〉建立 spec.md、依〈版本控制〉建立版本控制、依〈Session 交接〉建立 HANDOFF.md。
• 續作：第一則指令要求讀取本檔、spec.md 與 HANDOFF.md。

全新 session 不帶前次對話的脈絡。部分 CLI 可恢復既有 session（例如 codex resume、claude --resume），恢復與否取決於 session 資料是否留存及是否在同一台機器；交接因此一律以檔案為準。

〈平台限制〉與〈發布〉僅適用於 browser 平台。〈問題回報〉第 4 項的 Console 要求同樣如此，其他平台以該環境的訊息輸出（Max 的 console、Pd 的 Pd window、序列埠輸出）替代，其餘規則不變。

AI 的使用範圍

本課程允許以 AI 協助程式撰寫與技術實踐：產出與修改程式碼、除錯、設定執行環境、說明某個功能有哪些做法。

〈規格〉規定由 CLI 提問、學生回答，用意即在此。提問是要學生把想法說清楚，不是由 CLI 代為構思。

書面文字依課綱辦理：送審版課綱明定禁止 AI 直接寫期末報告主文段落，創作自述同此。

實作平台

實作平台不限。Max/MSP、Pure Data、Python、microcontroller 或 DAW script 均可作為期末作品的實作環境，依作品需要選擇。

建議自 browser 起步，理由為三項條件：不需安裝執行環境、可發布為公開網址供他人開啟與試聽、同一份檔案不綁定特定作業系統。

規格

實作前建立 spec.md，記錄五項：

1. 工具的功能一句陳述。
2. 輸入來源microphone、既有音檔、滑鼠或鍵盤動作，或無輸入。
3. 操作者的動作明確到單一動作。
4. 完成判準可聽見或可看見的結果。
5. 不支援的情境刻意不處理的狀況，例如未授權 microphone、未選擇檔案、操作中途取消。未記錄者無法在驗收時區分「尚未完成」與「刻意不做」。

第四項決定其餘各項能否驗收。「製作一個好用的聲音工具」不構成判準，因為沒有任何觀察能判定其成立。「按下按鈕後，錄製的 20 秒環境音以 0.5 倍速播放，畫面同時顯示波形」構成判準。

第五項不得用於規避驗收：驗收失敗的情境不直接移入第五項。確有必要改列時，於 HANDOFF.md 第 4 欄記錄該決定與理由，並重新確認第四項是否仍成立。

規格由 CLI 問出，不由學生獨自寫成

CLI 若略過提問直接產出程式碼，中止並重述上述指令。

使用 Claude Code 者，安裝 superpowers plugin 可取得結構化的需求釐清流程（brainstorming skill）。安裝方式：於 Claude Code 內執行 /plugin，在 claude-plugins-official marketplace 安裝 superpowers。安裝介面依 Claude Code 現行版本，以其官方文件為準；其他 CLI 的安裝方式見 superpowers 專案的說明文件。未安裝時以上述指令替代，流程不變。

規格會隨製作過程修改，修改一律寫回 spec.md。

版本控制

LLM 修改既有程式時可能連帶影響其他功能，且不一定回報。版本控制的作用是讓任一先前狀態可被指名取回。

1. main 的歷史只保留經實際執行確認可運作的版本。未通過驗收的程式碼提交於實驗 branch。
2. commit message 描述行為變化。不使用 update、fix 這類無資訊的字樣。「加入錄音按鈕，可錄可播」在回溯特定聲音版本時可用，fix 不可用。
3. 實驗 branch 通過驗收後，以 squash 方式併入 main。使過程中未通過的提交不進入 main 的歷史；一般 merge 會把那些提交一併帶進 main，牴觸第 1 項。squash 後，實驗過程中 HANDOFF.md 的中間狀態不會留在 main；需要保存的是失敗原因與 ai-log.md 段落（第 5 項），交接現況本身不需要歷史。
4. 在 main 上直接修改而驗收失敗時，要求 CLI 由目前的修改另開實驗 branch 再提交。不在 main 上提交失敗狀態。未提交的修改不隨 branch 隔離，切換時會跟著移動，Git 也可能因為會覆寫而拒絕切換。
5. HANDOFF.md、spec.md、ai-log.md 的提交不受第 1 項限制。捨棄實驗 branch 前，先把失敗原因寫進 main 上的 HANDOFF.md，並將該 branch 上的 ai-log.md 段落併回 main：只留在被捨棄 branch 上的紀錄，續作時讀不到，期末也無法用於揭露。

復原時指名目標版本，例如「回到 commit 4a2f，那一版的錄音可以播放」；「上一個」在文件提交混入紀錄後不足以定位，commit message 因此須能辨識版本（第 2 項）。操作者不需記憶指令，但需知道此操作存在。

未納入版本追蹤的音檔、相依套件與執行環境不會隨版本回退還原，需另行備份。

Session 交接

交接文件的作用是讓新 session 取得現況、既有決定與已排除的方案，避免重走已證實失敗的路徑。在專案根目錄維持一份 HANDOFF.md，五個欄位：

1. 目前狀態可運作的功能，並標出對應的 commit。
2. 進行中正在處理的項目與未解決的問題。
3. 已排除的做法嘗試過而失敗的方案、失敗原因，以及當時的環境。環境改變後可重新評估，此欄不構成永久禁令。
4. 已定案的設計決定目前不重新討論的選擇。出現新證據時可重啟，重啟時記錄理由。
5. 下一步一至三項具體工作。

作業約定

• 欄位無內容時填「尚無」或「不適用」，不留空白。開場時核對所載 commit 是否存在於本專案、內容與實際狀態是否相符；空白、矛盾或屬於其他專案時，只就該部分與 CLI 重建，其餘內容照常沿用。
• 下列時點即更新並提交，不只在 session 結束前更新：通過一項驗收、驗收失敗、排除一個方案、切換 branch。session 中斷且其紀錄未留存時，未記錄的除錯過程無法復原。
• HANDOFF.md 為覆寫式文件，只記現況，不累積歷史。歷史由版本紀錄承擔。
• 單次 session 過長而 CLI 開始遺忘先前內容時，先更新 HANDOFF.md 與 ai-log.md，再開新 session。

迭代與驗收

單次指令只要求一項變更，變更完成後實際執行確認，通過後提交，再進行下一項。此為作業約定，用意是讓異常可歸因到單一變更。

CLI 不一定能播放或聆聽音訊輸出，其回報的「完成」不構成聲音正確的證據，也不表示它實際執行過該程式。

驗收由操作者執行，每一輪確認四項：

1. 工具若應產生聲音，是否產生。
2. 若有聲音，是否為預期內容，而非雜訊、削峰或極短片段。
3. spec.md 的完成判準是否成立。
4. 前一輪已可運作的功能是否仍可運作（回歸檢查）。

未經實際執行確認的狀態不併入 main。純文件變更不適用本節。

問題回報

「不能動」不構成可處理的回報。有效回報包含四項資訊：

1. 執行的操作。
2. 預期的結果。
3. 實際的結果。
4. 錯誤訊息原文，以及執行環境。browser 名稱與版本、開啟網頁的方式，或其他平台的對應資訊。browser 上按右鍵選「檢查」開啟 Console，複製訊息全文，不改寫、不摘要、不只取單行。

沒有訊息時照樣回報，於第 4 項註明「無訊息」。無訊息不等於無錯誤：錯誤可能發生在程式未讀取的地方，也可能是不會拋出例外的邏輯問題（例如音量被設為零）。此時要求 CLI 加入檢查點，並指明該檢查點顯示在哪裡、由哪個操作觸發、應觀察什麼數值。

平台限制 · Browser

以下為已知的 browser 行為，實際規則依 browser 與版本而異。症狀相同不代表原因相同：無聲或時間偏移同樣可能來自程式缺陷。確認原因後再修改，修改後重跑原案例並確認既有功能未退化。

1. 頁面載入時的自動發聲受 autoplay 政策限制。多數 browser 預設要求使用者先與頁面互動，AudioContext 才會啟動；實際行為依 browser 設定與既有授權而異。提供一個使用者會觸發的控制項可避開此限制。
2. microphone 需 secure context 並經使用者授權。https 與 localhost 屬 secure context。滿足此條件仍可能被 iframe 的權限政策、sandbox 設定或作業系統的麥克風權限阻擋，須逐項確認。
3. 以 file:// 開啟時，fetch 與 XMLHttpRequest 讀取本地音檔會被安全規則阻擋。經由這條路徑取得資料再交給 decodeAudioData 因此失敗。另外兩條路徑不受此限：<audio> 元素直接播放通常可行；使用者以檔案選擇器選取的檔案可經 arrayBuffer() 取得資料後解碼。改以 local server 或公開網址開啟可解除被阻擋的那條路徑，但不會改變遠端伺服器的 CORS 設定，跨來源的音檔仍需該伺服器授權。
4. 音訊格式支援依 container 與 codec 分別認定。以 MDN 的 Audio codecs 對照表確認目標 browser 是否支援所選格式；WAV（PCM）與 MP3 為常見的低風險選項，本文件未做版本比較。載入失敗有錯誤可讀：decodeAudioData 會回傳失敗，media element 具 error 事件與 MediaError。未見錯誤訊息不能推論沒有錯誤，須逐一確認這些錯誤介面是否被程式讀取並顯示。
5. 分頁移至背景時 timer 可能被節流。規則依 browser 與頁面狀態而異，音訊播放中等情況列有例外。切換視窗後節奏偏移不得直接歸因於節流，須分別觀察頁面可見性、timer 延遲與音訊狀態。作品涉及時間精度時，要求 CLI 列出可用的排程方式與差異，再行選擇。

查證關鍵字（MDN）：Autoplay guide、getUserMedia、CORS、Audio codecs、decodeAudioData、Timeouts in inactive tabs。

發布

作品須能在他人機器上開啟，僅本機可執行者不構成交件。Cloudflare Pages 提供免費的靜態網頁託管，可將網頁發布為公開網址。發布後網址為 https，〈平台限制〉第 2 條的 secure context 條件因此滿足；網頁由伺服器提供而非 file://，第 3 條被阻擋的載入路徑隨之解除。

本節只涵蓋靜態部署。Cloudflare Pages 另有 Functions 可執行伺服器端程式，不在本文件範圍。

兩種模式在建立專案時就要決定，之後不可互換

Cloudflare 文件明載：選擇 Direct Upload 後無法改為 Git 連動，需另建專案。

Wrangler 不限於 Direct Upload：Git 連動的專案亦可停用自動部署，改以 Wrangler 手動上傳。

push 成功不等於發布完成

建置可能失敗，而舊版仍在線上可以開啟，因此不能以「網址打得開」判定本次發布成功。Git 連動模式下，每次發布後於 Cloudflare 的部署紀錄核對狀態與 commit 代號是否為本次提交。Direct Upload 的上傳不帶 commit 資訊，須於 HANDOFF.md 記錄本次上傳對應哪一個 commit 的輸出，否則事後無法辨識線上版本的來源。

preview deployment 預設公開

Git 連動模式下，非正式 branch 的 push 也會產生可公開存取的 preview 網址。素材授權與當事人同意須在第一次 push 之前確認，不能留到正式發布時才處理。需要限制存取時，於專案設定啟用 Cloudflare Access。

發布後在乾淨環境確認

使用全新的 browser 設定檔，或清除該網站的站點資料與權限後開啟，逐項重跑〈迭代與驗收〉的驗收，並記錄裝置、browser 與版本、受測的部署代號。僅登出帳號不構成乾淨環境，快取、localStorage 與既有權限都可能仍在。

限制

• 單一檔案上限 25 MiB。長音檔需壓縮，或改以外部串流來源。
• 免費方案單一站台上限 20,000 個檔案，每月 500 次建置。
• 發布即公開。取得網址者皆可存取上傳的音檔，正式網址並可能被搜尋引擎索引。內容含他人聲音、未授權素材或私人錄音時，發布前須確認授權與當事人同意。此為課程的倫理要求，非技術限制。

交件

送審版課綱的《AI 使用規則》採「有條件開放」，明定必須揭露三項：哪些段落使用 AI、給 AI 的 prompt 內容、引用 AI 輸出時加註「AI-generated, edited by author」；違規處置為第一次扣 20%、第二次零分。書面文字（期末報告主文、創作自述）的撰寫規則依課綱辦理，本節規範的是程式碼協作過程的紀錄。

spec.md 與版本紀錄留下的是結果，不含提問過程，因此另建 ai-log.md，每次 session 追加一段：

• 該次的關鍵 prompt 原文。
• AI 產出的部分與操作者決定或改寫的部分，分別標示。
• 未採用的建議及其理由。

ai-log.md 於每次 session 結束前與 HANDOFF.md 一併更新提交，並於發布前再次確認本次 session 已有對應段落。此為手動紀錄；CLI 的 session 紀錄未留存時，未當場寫下的 prompt 無法重建。

另需保留：

• 素材來源，他人素材標註出處。
• 可執行的版本及其開啟方式。僅能在製作者本機執行者不構成交件。

每次提交前於 spec.md 末尾追加一行：本次變更與可觀察到的差異。期末創作自述以 ai-log.md 與該紀錄為材料。

不在本文件範圍

以下屬作品的設計決定，本文件不提供答案：

• 視覺形式：版面、色彩、字體、動態。
• 程式組織：單一檔案或多檔案、是否使用 framework。
• 效能：何時需處理效能，以及取捨對象。
• 功能邊界：完成度，以及刻意不處理的狀況。決定本身不受本文件規範，但須記入 spec.md 第 5 項，否則無法驗收。

向 CLI 詢問「哪一種比較好」會得到一個預設答案，該答案未經本作品的條件檢驗。有效的問法為「有哪些做法，差異在哪」，選擇由製作者作出並記入 spec.md。